Monitoring Guide

The Monitoring feature provides the ability to receive notifications when changes occur to content contained in specific data products and D-U-N-S Numbers®.

D&B Direct+ data API provides access to numerous products, each with a set of attributes. Monitoring allows you to receive notifications when any of those attribute values change for the D-U-N-S Number in the registration.

For more information on the products, please see the Data Product APIs.

Monitoring

Registration

D&B Direct+ Monitoring Registrations represent a request to monitor a set of D-U-N-S Numbers against one of the D&B Direct+ Data Products. It also includes details on how notifications are to be delivered and other information necessary for monitoring.

The D-U-N-S Numbers can be specified as:

  • List of D-U-N-S Numbers (LOD): A specific list of D-U-N-S Numbers included with the registration.
  • Using a Dun & Bradstreet Managed Universe
    • Dynamic Universe: In a dynamic Universe, D-U-N-S Numbers are identified by specified criteria defined by Dun & Bradstreet. For a list of available Universes, see the Monitoring page under Dun & Bradstreet Managed Universes.
    • Full Universe: The full Dun & Bradstreet Universe.

The Monitoring Registration also allows for an optional request for a seed (or baseline) of the data to be delivered per the delivery channel configuration in the Registration.

Seed

A seed file provides a baseline of data for the Monitoring Registration. When you create a registration, if Seed File = True:

  • Seed generated and delivered per the Monitoring Registration settings within 7 days.
  • Seed File data is delivered in a text file with JSON formatted records conforming to that of the D&B Direct+ Platform.
  • Change notifications are initially suppressed allowing time for the seed file to be generated and processed. An unsuppress request must be issued in order to start receiving change notifications. (See the Monitoring, Suppress or Unsuppress API page.)

Notifications

Change notifications provide details about changes that occur to D-U-N-S Numbers within the Monitoring Registration.

Once a registration is created and processed, regular notifications are delivered to the destination and at the frequency specified in the registration.

For STP and S3, multiple files may be received depending on the number of notifications. The individual notifications are grouped by D-U-N-S Numbers and in date/time ascending order. A single D-U-N-S Number will never be split between multiple files. Best practice to update a single D-U-N-S Number, is to process the notifications in a file in order.

While it is unlikely, it is possible that the same D-U-N-S Number will have more than one UPDATE notification in a single package.

Getting Started with Monitoring

  1. Create a Monitoring Registration for the product, version, and D-U-N-S Numbers or Universe for which you want to receive change notifications. See Create a Registration.
  2. If a seed file was requested:
    a) Process the file. For information on its contents, see Process a Seed File.
    b) Unsuppress notifications to start receiving change notifications. (See the Monitoring, Suppress or Unsuppress API page.)
  3. Process Change Notifications. For information on the content of change notifications, see Process Change Notifications.

Monitoring Registration Process

Create Registration Flow

Create a Monitoring Registration

In order to receive change notifications, a Monitoring Registration must be created; a separate registration is required for each product and version you want to monitor.

To create a registration, the following information needs to be provided; customers should work with their Dun & Bradstreet Representative to have registrations created:

Property Description
Subscriber The subscriber ID assigned by Dun & Bradstreet that uniquely identifies the subscriber. The subscriber for which the registration is created allows that subscriber to later manage the registration through the APIs.
Identifier A string used to identify the registration. The reference must be unique for each subscriber. This value cannot be changed once the registration is created.
Description A description for the registration. Provide a description that clearly identifies the purpose of the registration.

Valid contents: Up to 256 characters that can include A-Z, a-z, 0-9, and the following special characters: . , -
Product The product ID provided by Dun & Bradstreet that identifies the product to be included in this registration. Only one product can be included in a registration. The product cannot be changed once the registration is created.
Product version The version ID (e.g., v1) that identifies the product version to be used for this registration. Only one version can be included in a registration. The version cannot be changed once the registration is created.
Universe or LOD Indicates whether the registration is for a Universe or List of D-U-N-S Numbers.
  • For Universe, the name of a managed Universe.
  • For LOD, a file containing the list of D-U-N-S numbers (one per line) to be included in the registration must be provided. Supported file types:
    • .txt
    • .zip
See the List of D-U-N-S Numbers File for more information.
This value cannot be changed once the registration is created.
Seed File Indicates if a seed file should be delivered.
Valid values:
  • True
  • False
This value cannot be changed once the registration is created.
Notification Frequency Indicates how often notifications will be delivered.

Valid values:
  • INTRA_DAY: For future use when content is updated more than once a day.
  • DAILY: System processes notifications shortly after midnight UTC. (Due to various circumstances, two DAILY notification files may be received on the same day. The timestamp date in one of the files may be of the day before it arrives at the delivery site)
  • WEEKLY: System processes notifications shortly after midnight UTC each Sunday.
  • MONTHLY: System processes notifications shortly after midnight UTC on the first of each month.

If there are no new notifications, a 0 notification header file will be delivered for the specified frequency.

Notification Type Indicates the level of detail each change notification will include for any D-U-N-S Number that has changed.

Valid values:
  • FULL_PRODUCT: For each D-U-N-S Number that has changed, the full details are included in the notification. This is equivalent to a seed for the D-U-N-S Number.
  • UPDATE: For each D-U-N-S Number that has changed, only the changed data will be included in the notification.
This value cannot be changed once the registration is created.
Destination Type The communications protocol used to transfer change notifications and any other material related to the registration.

Valid values:
  • STP
  • S3
For more information, see Destination Type
File Transfer Profile The specific location for file delivery; one of the following:
  • If Destination Type = STP, the STP profile name allocated for the subscriber to enable data exchange.
  • If Destination Type = S3, the S3 ARN path. For information on setting up S3 for monitoring access, Configure S3 Bucket.
S3 Encryption Key A key used to encrypt the files delivered to S3. This is required if the File Transfer Profile is S3 and is not applicable otherwise.

For information on setting up S3 for monitoring access, Configure S3 Bucket.
Email Addresses Email addresses for users to be notified regarding monitoring activities for this Registration. A D&B contact email (employee or partner) must be included in this list.
JSON Path Inclusion For the data product being monitored, the JSON paths that will be monitored. Only changes to the values for these paths will be included in notification files. Changes to other values will not be delivered through monitoring.

Either jsonPathInclusion or jsonPathExclusion may be specified.

See Element-Level Monitoring for more information.
JSON Path Exclusion For the data product being monitored, the JSON paths that will not be monitored. Changes to values for all other paths in the product will be included in monitoring notifications.

Either jsonPathInclusion or jsonPathExclusion may be specified.

See Element-Level Monitoring for more information.

Destination Type

The Destination Type and File Transfer protocol identify where monitoring files are delivered (both seed and notification files).

  • STP
    • STP is Dun & Bradstreet's secure file transfer location. If you choose to use STP, you must request a location through Dun & Bradstreet.
    • Files are delivered to the STP location specified in the Monitoring Registration.
    • Delivered files remain on STP for 15 days. To change this time limit, please contact STP Support.
  • S3
    • S3 is hosted by AWS; you will need to create the location and bucket for files to be delivered.
    • S3 bucket policy must allow write access by monitoring user. See Appendix: Configure S3 Bucket for details.
Element-Level Monitoring

Element-Level Monitoring provides the ability to choose the elements for which you want to receive monitoring notifications. The available elements are limited to those in the product being monitored. Elements can be configured in the request of Create a Registration and Edit Registration Details APIs through the jsonPathInclusion OR jsonPathExclusion parameters.

We strongly recommend customers work with their Dun & Bradstreet Representative to enable this feature.

  • Select whether to provide an exclude or include list:
    • Use jsonPathInclusion parameter to receive change notifications only on the specified elements.
    • Use jsonPathExclusion parameter to receive change notifications on all other elements of the product, except for the specified elements.
  • The JSON Path may be for an element, element within an Object, an Object, or an Array. Elements within Arrays cannot be monitored individually.
  • If the JSON Path of an Object or Array is specified, changes for the aggregate and all sub-elements will be included in the notifications.
  • To specify multiple elements separate each JSON paths with a comma. Any path specified that is not part of the product will result in error. See the Data Dictionary for the list of elements in each data product.
  • Updates to Element-Level Monitoring may take up to two delivers to take effect.

Element-Level Monitoring does not apply to FULL_PRODUCT registrations or Seed files; the entire product record for the D-U-N-S Number is included in Seed files.

If you are updating an existing registration, it is highly-recommended that you use the Get Registration Details API to first pull the existing configuration, so you do not inadvertently omit an existing path. Update registration does an overwrite of the previous configuration

List of D-U-N-S Numbers File

File types accepted for List of D-U-N-S Numbers Registration are:

  • Monitoring will accept zipped and unzipped files. The type of zipped files accepted are pkzip files. Only one file is accepted per Registration, multiple files in a zipped file is considered an Invalid file type. The file type accepted are DEFLATE Compressed Data Format Specification version 1.3 (pdf) (RFC 1951).
  • The maximum file size accepted is 500 MB.
  • If the full list of D-U-N-S Numbers required cannot be specified in a single file, they can be added to the Registration through the Add D-U-N-S Numbers to Registration API.

Registration Management Communication

  • Create Registration Processed: Once the registration is processed, the system will send an email indicating that the registration was processed. If a seed file was not requested, the registration will be processed within 48 hours; if a seed file was requested, the process may take up to 7 days.
  • Invalid File Type: Once a request is received, if a file of an invalid type is provided, the system will send an email to the address provided. This applies to Create Registration, Add D-U-N-S Numbers, and Remove D-U-N-S Numbers.
  • Problem loading file: Once a request is received, if there was a problem loading the file, the system will send an email to the address provided. This applies to Create Registration, Add D-U-N-S Numbers, and Remove D-U-N-S Numbers.
  • Exception File: If applicable, a file containing a list of D-U-N-S Numbers that could not be processed and the reason is delivered per the delivery channel configuration in the Registration. This applies to Create Registration, Add D-U-N-S Numbers, Remove D-U-N-S Numbers, and re-seed requests.
  • If a seed file was requested, it can take up to 7 days to process and deliver the file to the location specified in the Registration.
D-U-N-S Number Exception File

The Exception file is a tab-delimited text file and contains one line per D-U-N-S Number for which there was a processing exception.

Sample Exception File
 DUNS        Code   Information
 808080808   40003  101010101
 707070707   40002
 606060606   10001
Exception File Contents
Attribute Data Type JSON Type Description
DUNS Element Integer The D-U-N-S Number is an identification number assigned by Dun & Bradstreet that uniquely identifies the entity in accordance with the Data Universal Numbering System (DUNS).
Code Element Integer A number assigned by Dun & Bradstreet that uniquely identifies the reason for this exception. One of the following:
  • 10001: The D-U-N-S Number not found
  • 10003: The D-U-N-S Number is not valid. Must be 9-characters containing only digits 0-9.
  • 10004: The D-U-N-S Number is not available for the requested product.
  • 10200: The D-U-N-S Number cannot be returned for the requested product.
  • 21012: The D-U-N-S Number is already exists in the Registration.
  • 40001: The D-U-N-S Number is UNDER_REVIEW these D-U-N-S Numbers are part of the Registration; however, the D-U-N-S Number will not be included in the seed file. If the D-U-N-S Number status changes to REVIEWED, a SEED record wil be included in the next notification delivery.
  • 40002: The requested D-U-N-S Number has been deleted.
  • 40003: The requested D-U-N-S Number has been transferred; please see D-U-N-S Number transfer details.
  • 40105: The requested D-U-N-S Number does not contain sufficient data.
Information Element String If the D-U-N-S Number was transferred, contains the D-U-N-S Number to which it was transferred. The transferred TO D-U-N-S Number is not part of the Registration; to add it, use the Add DUNS to Registration API. (See the Monitoring, Add DUNS to existing Registrations API page.)

Seed Delivery

As part of the Monitoring Registration there is an option to request a seed file. This file is a baseline extract of the data requested in the Registration. Once the registration is processed, the seed files will be delivered per the delivery channel configuration in the Registration.

A seed delivery includes two types of files: Seed Header and Seed Data.

Seed Header File

Provides metadata for the Seed Data file, such as number records, along with Seed Data file names delivered per the delivery channel configuration in the Registration.

Sample: PRD_MKTLNK_STP_2017020808104948_SEED_HEADER.json

{
  "fileHeader" : {
	"headerType" : "SEEDFILE",
	"fileId" : "rrt-f98e3872-a-eu-6623-63069210-1",
	"inLanguage" : "en-US",
	"reference" : "PRD_MKTLNK_STP ",
	"productId" : "aasmcu",
	"versionId" : "v1",
	"totalRecordCount" : 92456097,
	"fileTimeStamp" : "2017-01-05T09:59:46.988Z",
	"files" : [
	  {
		"name" : "PRD_MKTLNK_STP_20170208124948_SEEDFILE_1.zip",
		"hash" : "71a00d72f7d3f7caaec0b174dc444dccfaa0e230af85bbe444d8365b98083ba0"
	  },
	  {
		"name" : "PRD_MKTLNK_STP_20170208124948_SEEDFILE_2.zip",
		"hash" : "8f33b5469f92f4aba4d41c06475090f491ff3dfabec92474298c368cb60c3f67"
	  },
	  {
		"name" : "PRD_MKTLNK_STP_20170208124948_SEEDFILE_3.zip",
		"hash" : "d21535ba1bfff44144465ad038f0a0555a371fdb0f3dd5f61b20ea71684b94be"
	  },
	  {
		"name" : "PRD_MKTLNK_STP_20170208124948_SEEDFILE_4.zip",
		"hash" : "8b6e1206a29ec1fb09ee7c13598df6602245894e201f9556532c7b722a89aedb"
	  },
	  {
		"name" : "PRD_MKTLNK_STP_20170208124948_SEEDFILE_5.zip",
		"hash" : "619bfe4684a4852b222fc40a6d64b26242a3778e51d0f889e66abce1de8d688e"
	  },
	  {
		"name" : "PRD_MKTLNK_STP_20170208124948_SEEDFILE_6.zip",
		"hash" : "b363db52412800435cf8528ef58feb64d54444940b609df244e4bb53ef728c8e"
	  },
	  {
		"name" : "PRD_MKTLNK_STP_20170208124948_SEEDFILE_7.zip",
		"hash" : "717eb5a4f5d913eeca5610d3b3f4aa0d6266ff40553f87b4cf2f2e6e49f92bd9"
	  },
	  {
		"name" : "PRD_MKTLNK_STP_20170208124948_SEEDFILE_8.zip",
		"hash" : "c46e5a13e64772bd8cc0d3bd6b4cb7a5a61b339ea92984d78ba1326871d6cba5"
	  }
	]
  }
}

Seed Header File Attribute Descriptions
Attribute Data Type JSON Type Description
fileHeader Aggregate Element The details of the information in the file.
fileHeader.headerType Element String The type of the seed header file.

Possible values:
  • SEEDFILE
  • NOTIFICATION
fileHeader.reference Element String The unique identifier assigned to the Monitoring Registrations when it was created.
fileHeader.fileID Element String The file's unique identifier.
fileHeader.fileTimeStamp Element String The date and time, in ISO 8601 UTC Z standards, when the response was created by the application.
fileHeader.inLanguage Element String An IETF BCP 47 code value that defines the language in which this product was rendered.
fileHeader.productId Element String The product ID associated with the Monitoring Registration
fileHeader.versionId Element String The product version ID associated with the Monitoring Registration
fileHeader.totalRecordCount Element Integer The total number of records included with this seed request.
fileHeader.files Aggregate Object The details of the seed data files.
fileHeader.files.name Element String The name of the seed data file.
fileHeader.files.hash Element String The hash size of the seed data file.

Seed Data File

The Seed data file is a text file; each record in the file is in JSON format and contains one line per D-U-N-S Number included in the Monitoring Registration.

For details on the JSON structure, please see the applicable data product's API Response documentation.

Once the seed file is consumed, the Registration must be unsuppressed to receive notifications. This can be done with the Monitoring API. (See the Monitoring, Suppress or Unsuppress API page.)

Change Notifications

Once a registration request is processed and notifications are unsuppressed, if necessary, change notifications are pushed to the chosen delivery channel (STP, S3) with the frequency specified in the Monitoring Registration.

STP and S3 notification deliveries include:

Notification Header File

Sample Notification Header File
{
  "fileHeader" : {
    "reference" : "STG_CMPELK",
    "headertype" : "NOTIFICATION",
    "fileId" : 0,
    "fileTimeStamp" : "2017-01-18T13:51:31.923Z",
    "inLanguage" : "en-US",
    "productID" : "cmpelk",
    "productVersion" : "v1",
    "totalRecordCount" : 192939522,
    "files" : [
      {
        "name" : "STG_CMPELK_20170118133445_NOTIFICATION_1.zip",
        "hash" : "e9494312b6f13f6f65d3200700b6370aa745680aaaed166ac2ad3f86a6849ec4"
      },
      {
        "name" : "STG_CMPELK_20170118133445_NOTIFICATION_2.zip",
        "hash" : "b23d4c50d9f1a2f40562b2fbaabed69ebb3876259526e77f0c6a13b263a3ba1b"
      }
    ],
    "notificationCount" : [
      {
        "count" : 597659,
        "type" : "ENTER"
      },
      {
        "count" : 6256,
        "type" : "TRANSFER"
      },
      {
        "count" : 191706866,
        "type" : "UPDATE"
      },
      {
        "count" : 191,
        "type" : "UNDER_REVIEW"
      },
      {
        "count" : 18155,
        "type" : "EXIT"
      },
      {
        "count" : 597862,
        "type" : "SEED"
      },
      {
        "count" : 12330,
        "type" : "DELETE"
      },
      {
        "count" : 201,
        "type" : "UNDELETE"
      },
      {
        "count" : 2,
        "type" : "REVIEWED"
      }
    ]
  }
}
Notification File Header Attribute Descriptions
Attribute Data Type JSON Type Description
fileHeader Aggregate Object The details of the information in the file.
fileHeader.reference Element String The unique identifier assigned to the Monitoring Registrations when it was created.
fileHeader.headerType Element String The type of the seed header file. Possible values:
  • SEEDFILE
  • NOTIFICATION
fileHeader.fileID Element String The file's unique identifier.
fileHeader.fileTimeStamp Element String The date and time, in ISO 8601 UTC Z standards, when the response was created by the application.
fileHeader.inLanguage Element String An IETF BCP 47 code value that defines the language in which this product was rendered.
fileHeader.productID Element String The product ID associated with the Monitoring Registration
fileHeader.productVersion Element String The product version ID associated with the Monitoring Registration
fileHeader.totalRecordCount Element Integer The total number of records included with this seed request.
fileHeader.files Aggregate Object The details of the seed data files.
fileHeader.files.name Element String The name of the seed data file.
fileHeader.files.hash Element String The SHA-256 hash of the seed data file.
fileHeader.notificationCount Aggregate Object The details of the type of notifications in the file(s).
fileHeader.notificationCount.count Element Integer The number of records of the type.
fileHeader.notificationCount.type Element String The type of notification (see D-U-N-S Number Status Types).

Notification Data Files

Notification files are text files. They contain one row for each notification, which is in JSON. Each row starts with the notification type and then includes applicable details of the D-U-N-S Number for which the notification applies. The notifications are grouped by D-U-N-S Numbers and then are in ascending order by timestamp. The notifications for a single D-U-N-S Number will never be split across multiple files; the order of D-U-N-S Numbers in a file or between files is not guaranteed.

Notification File Names

D-U-N-S Numbers monitoring notification files use the following naming convention:

Intra_Day Notifications: REFERENCE_YYYYMMDDHHMMSS_FILE-TYPE_FILE-NUMBER

Daily Notifications: REFERENCE_YYYYMMDDHHMMSS_FILE-TYPE_FILE-NUMBER

Weekly Notifications: REFERENCE_YYYYMMDD_FILE-TYPE_FILE-NUMBER

Monthly Notifications: REFERENCE_YYYYMM_FILE-TYPE_FILE-NUMBER

Where:

  • REFERENCE = the reference defined at registration request.
  • YYYYMMDDHHMMSS = the date and time the file was generated.
  • YYYYMMDD = the date the file was generated.
  • YYYYMM = the year and month the file was generated.
  • FILE-TYPE = one of the following:
    • EXCEPTIONS
    • NOTIFICATION
    • NOTIFICATION HEADER
    • SEED HEADER
    • SEEDFILE
  • FILE-NUMBER = the number of the file. Not included for header files. Multiple files are delivered to keep the maximum size under 3GB.
Notification Data File Contents

A Notification file may contain:

  • Status changes for D-U-N-S Numbers. For details on status types, see D-U-N-S Number Status Types.
  • D-U-N-S Number data changes as UPDATE or SEED records.
  • SEED records for newly created D-U-N-S Numbers that meet the registration Universe criteria.
  • SEED records for D-U-N-S Numbers added to the registration.
Element Descriptions

Each record in the file may contain the following elements, based on the notification type.

File Element Data Type Description Notification Types
type String The type of notification. All
organization Object The details of the entity's organization. All
organization.duns String The D-U-N-S Number is an identification number assigned by Dun & Bradstreet that uniquely identifies the entity in accordance with the Data Universal Numbering System (DUNS). All
elements Array Array of elements of the D-U-N-S Number that have been updated. UPDATE, SEED
elements.element String JSON Path of element that has been updated. UPDATE, SEED
elelments.previous String Previous value of the element.See the specific product response for details on attributes and values included in this section. UPDATE
elements.current String Current value of the element.See the specific product response for details on attributes and values included in this section. UPDATE
elements.timestamp String The date and time, in ISO 8601 UTC Z standards, when this element was updated by the application. UPDATE
organization.dunsControlStatus String The details of the entity established to provide products and/or services in the marketplace or to the community. TRANSFER, DELETE, UNDELETE
organization.dunsControlStatus.dunsTransfers Array History of D-U-N-S Number deletes and D-U-N-S Number transfer for this entity. TRANSFER
organization.dunsControlStatus.dunsTransfers.retainedDUNS String In the event that the D-U-N-S Number of this entity is retired, this field contains the D-U-N-S Number to reference for future product requests TRANSFER
D-U-N-S Number Status Types

Monitoring tracks several types of changes:

Notification Type Explanation
DELETE The D-U-N-S Number has been deleted; it is no longer available through Direct+ APIs or Monitoring.
ENTER The D-U-N-S entered the Universe in the Monitoring Registration. This may occur when a new D-U-N-S Number is created or an existing one is changed so it now meets the Universe criteria.

Example 1: Registration is configured for Commercially Active Universe.
  • DUNS-A is not currently in the Commercially Active Universe because mail is not deliverable.
  • DUNS-A is changed and mail deliverable flag is changed to True. It now meets the Universe criteria.
  • An ENTER notification is triggered and included in the next notification file.
Example 2: Registration is configured for Full Universe.
  • DUNS-B is not part of the Universe because it is deleted.
  • DUNS-B is undeleted.
  • An ENTER notification is triggered and included in the next notification file.
(For information on Universe criteria, please see the Monitoring Overview.)
EXIT The D-U-N-S Number is no longer part of the Universe in the Monitoring Registration. This occurs when a D-U-N-S Number is deleted, transferred, or the content changes so that it no longer meets the Universe criteria.

Example 1: Registration is configured for Commercially Active Universe
  • DUNS-C currently meets the criteria for Commercially Active.
  • DUNS-C is changed so it is now de-listed. It no longer meets the Universe criteria.
  • An EXIT notification is triggered and included in the next notification file.
Example 2: Registration is configured for Full Universe.
  • DUNS-D is part of the Universe.
  • DUNS-D is deleted.
  • An EXIT notification is triggered and included in the next notification file.
(For information on Universe criteria, please see the Monitoring Overview.)
REVIEWED The review of the D-U-N-S Number has been completed; changes notifications will now be processed for this D-U-N-S Number.
SEED
  • For Monitoring Registrations configured with a Universe and created with Seed File = True, a SEED notification is sent when a D-U-N-S Number has entered a Universe due to data changes.
  • For Monitoring Registrations configured for a List of D-U-N-S Numbers (LOD) and created with Seed File = True, a SEED notification is sent when a D-U-N-S Number has been added to the Monitoring Registration by request for LOD Registrations.
  • For Monitoring Registrations configured to receive FULL_PRODUCT notifications, a SEED notification is sent when a D-U-N-S Number has been updated.
TRANSFER The D-U-N-S Number has been transferred to another D-U-N-S Number; the retained D-U-N-S Number is also transmitted.
UNDELETE The D-U-N-S Number has been undeleted and is now available through Direct+ APIs and Monitoring.
UNDER_REVIEW The D-U-N-S Number is currently under review. No change notifications will be received while the D-U-N-S Number is in this state. However, the D-U-N-S Number remains in the registration so when the status changes the appropriate notification(s) will be delivered based on the new status.
UPDATE Content related to the subject D-U-N-S Number has been updated.

Scenarios and Which Status Types Are Included

For Dun & Bradstreet Managed Universe Registrations, the notifications are only sent if the D-U-N-S Number meets the Universe conditions.

For LOD Registrations, the notifications are only sent if the D-U-N-S Number is part of the Monitoring Registration.

Unless otherwise noted, the information below applies to both UPDATE and FULL_PRODUCT registrations.

Activity Notification Types for Universe Registrations Notification Types for LOD Registrations Notes
A new D-U-N-S Number is created.
  • ENTER
  • SEED
n/a SEED record only included if Registration has Seed File = True.
A D-U-N-S Number is marked as deleted.
  • UPDATE or SEED
  • DELETE
  • EXIT
  • UPDATE or SEED
  • DELETE
Any pending notifications for the registered D-U-N-S Number before it became deleted will be sent. However, while the D-U-N-S Number has a status of deleted, no further update notifications will be sent. UPDATE or SEED depends on Registration notificationType setting.
A D-U-N-S Number is undeleted.
  • ENTER
  • SEED
  • UNDELETE
  • SEED
For Universe registration, a SEED record only included if Registration has Seed File = True.

For LOD registration, a SEED record is included if Registration as Seed File = True OR notificationType is FULL_PRODUCT.
The D-U-N-S Number data changes, which may include:
- New content
- Updated content
- Removed content
  • UPDATE or SEED
  • UPDATE or SEED
UPDATE or SEED depends on Registration notificationType setting.
The D-U-N-S Number data changes cause it to no longer meet the Universe criteria.
  • EXIT
n/a
DUNS-A is transferred to DUNS-B. DUNS-A was in Registration; DUNS-B is not. For DUNS-A
  • TRANSFER
  • EXIT
For DUNS-A
  • TRANSFER
For LOD Registrations, modify Registration to remove DUNS-A and add DUNS-B.
DUNS-A is transferred to DUNS-B. DUNS -B was in Registration; DUNS-A is not. No notification. No notification.
A D-U-N-S Number is placed under review.
  • UNDER_REVIEW
  • UNDER_REVIEW

The review of a D-U-N-S Number is completed.
  • REVIEWED
  • SEED
  • REVIEWED
  • SEED
SEED is only included if Registration included SEED request.
A D-U-N-S Number is added to Registration. n/a
  • ADDED
  • SEED
SEED is only included if Registration included SEED request.
A D-U-N-S Number is removed from Registration. n/a
  • REMOVED

A D-U-N-S Number is under review AND is Transferred For DUNS-A
  • TRANSFER
  • EXIT
For DUNS-B
  • ENTER
  • SEED
  • TRANSFER

If the registration does not include a Seed File = True, in order to baseline a D-U-N-S Number that has been added to the Registration or has Entered the Universe, a data API call can be used.


Notification File Record Examples

Delete Example
{
  "type":"DELETE",
  "organization":{
      "duns":"217825255"
  }
}

Enter Example
{
  "type":"ENTER",
  "organization":{
    "duns":"217825255"
  }
}

Exit Example
{
  "type":"EXIT",
  "organization":{
     "duns":"217825255"
  }
}

Reviewed Example
{
  "type":"REVIEWED",
  "organization": {
     "duns":"217825255"
  }
}

Seed Example
{
  "type":"SEED",
  "organization":{
     "duns":"611710674",
     ...(product contents here)
  }
}

Transfer Example
{
  "type":"TRANSFER",
  "organization":{
     "duns":"611710674",
     "dunsControlStatus":{
        "dunsTransfers"[{
           "retainedDUNS":"064332299"
         }
         ]
     }
  }
}

Undelete Example
{
  "type":"UNDELETE",
  "organization":{
      "duns":"217825255"
  }
}

Under Review Example
{
   "type":"UNDER_REVIEW",
   "organization":{
      "duns":"217825255"
   }
}

UPDATE String Element
{
  "type":"UPDATE",
  "organization":{
     "duns":"217825255"
  }
   "elements": [ {
   "element":"organization.registeredAddress.streetName",
   "previous":"BUILDING 4, HATTERS LANE, CROXLEY GREENBUSINESS PARK",
   "current":"BUILDING 4, HATTERS LANE",
}
]

UPDATE Array Element
{
 "type":"UPDATE",
  "organization":{
     "duns":"217825255"
  }
  "elements": [ {
   "element": "organization.industryCodes",
  "previous": [
     {
       "typeDescription": "North American Industry Classification System 2012",
       "description": "Unclassified Establishments",
       "priority": 1,
       "code": "999990",
       "typeDnBCode": 24664
     },
     {
       "typeDescription": "D&B Hoovers Industry Code",
       "description": "Nonclassifiable establishments",
       "priority": 1,
       "code": "2058",
       "typeDnBCode": 25838          },
     {
       "typeDescription": "US Standard Industry Code 1987 - 4 digit",
       "description": "Nonclassified establishment",
       "priority": 1,
       "code": "9999",
       "typeDnBCode": 399
     },
     {
       "typeDescription": "D&B Standard Industry Code",
       "description": "Nonclassifiable establishments",
       "priority": 1,
       "code": "99990000",
       "typeDnBCode": 3599
     },
     {
      "typeDescription": "NACE Revision 2",
      "description": "Undetermined",
      "priority": 1,
      "code": "9999",
      "typeDnBCode": 29104
     }
  ],
  "current": [
     {
      "code": "238210",
      "description": "Electrical Contractors",
      "typeDescription": "North American Industry Classification System 2012",
      "typeDnBCode": 24664,
      "priority": 1
     },
     {
      "code": "1857",
      "description": "Electrical Contractors",
      "typeDescription": "D&B Hoovers Industry Code",
      "typeDnBCode": 25838,
      "priority": 1
     },
     {
      "code": "1731",
      "description": "Electrical contractor",
      "typeDescription": "US Standard Industry Code 1987 - 4 digit",
      "typeDnBCode": 399,
      "priority": 1
     },
     {
      "code": "17310203",
      "description": "Environmental system control installation",
      "typeDescription": "D&B Standard Industry Code",
      "typeDnBCode": 3599,
      "priority": 1
     },
     {
      "code": "C",
      "description": "Construction",
      "typeDescription": "D&B Standard Major Industry Code",
      "typeDnBCode": 24657,
      "priority": 1
     },
     {
      "code": "4321",
      "description": "Electrical installation",
      "typeDescription": "NACE Revision 2",
      "typeDnBCode": 29104,
      "priority": 1
     }
  ]
}
]

UPDATE Object Element with Changed Values
{
 "type":"UPDATE",
  "organization":{
     "duns":"217825255"
  }
  "elements": [ {
     "element":"organization.telephone",
    "previous": [
        {
          "telephoneNumber":"5555551212",
          "isdCode":"86",
          "isUnreachable":false
        }
     ],
     "current": [
        {
          "telephoneNumber":"5555551000",
          "isdCode":"86",
          "isUnreachable":false
        }
     ],
     "timestamp":"2016-07-29T13:22:19Z"
}
]

UPDATE Object with Added Values
{
 "type":"UPDATE",
  "organization":{
     "duns":"217825255"
  }
  "elements": [ {
   "element":"organization.telephone",
   "previous":[],
   "current":[
      {
        "telephoneNumber":"57687353158",
        "isdCode":"86",
        "isUnreachable":false
       }
   ],
   "timestamp":"2016-07-29T13:22:19Z"
}
]

Object with Removed Values
{
  "type":"UPDATE",
  "organization":{
     "duns":"217825255"
  }
  "elements": [ {
  "element":"organization.telephone",
   "previous":[
     {
       "telephoneNumber":"5555551212",
       "isdCode":"86",
       "isUnreachable":false
     }
   ],
   "current":[]
}
]

When Notifications are Not Delivered

Regular notifications will not be delivered under the following circumstances:

  • Maintenance Window
  • Notifications are suppressed

Maintenance Window

Periodically, the D&B Direct+ system must undergo maintenance. During these periods, notification delivery is suspended to ensure consistency with Direct+ API content.

When reinstated, notifications include all changes that occurred during the maintenance window.

During system maintenance monitoring notifications are not delivered. They are accumulated and packaged once the maintenance is complete. The delivered files contain each individual . This provides you with all the interim changes that occurred during the maintenance window.

NOTE: This is different than suppression. When a Monitoring Registration is suppressed, interim updates are not included in the notification once delivery is unsuppressed.

Suppressed Notifications

Notifications may be suppressed through the API. During this period, the system aggregates the changes for each day into a single UPDATE notification. When the notifications are unsuppressed, the aggregated notifications are delivered. The previous value is the last value delivered before the notifications were suppressed and the current value is the value of the last change before the notifications are delivered.

Appendix: Configure S3 Bucket

In order for monitoring to deliver files to S3 and ensure they are encrypted, the monitoring user must be given access.

  • DNB Profile Id: 219829223284
  • DNB IAM User: otmutransfer
  1. Create an S3 bucket using instructions provided by AWS.
  2. Give monitoring user read access to S3 bucket (see Bucket IAM Policy).
  3. Give monitoring user read access to encryption keys (see Bucket Key Policy).
  4. Create key following instructions provided by AWS.
  5. Go to the AWS Identity and Access Management (IAM) console at https://console.aws.amazon.com/iam/home#encryptionKeys.
  6. Open the Encryption Keys section.
  7. Select the appropriate AWS region (do not use the region selector in the navigation bar (top right corner). A list of keys is displayed.

  8. Select the alias name. The details are displayed:

  9. Use the bucket and key information to configure the registration.

Bucket IAM Policy

The following is sample configuration for the IAM policy to be applied:

{
    "Version": "2012-10-17",
    "Statement": [
        {
           "Sid": "Monitoring Bucket permissions",
           "Effect": "Allow",
           "Principal": {
              "AWS": "arn:aws:iam::219829223284:user/otmutransfer"
            },
            "Action": "s3:PutObject",
            "Resource": "arn:aws:s3:::customer-bucket-name/*"
        }
    ]
}

Bucket Key Policy

{
{
      "Sid": "Allow use of the key",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::219829223284:user/otmutransfer"
      },
      "Action": [
        "kms:Encrypt",
        "kms:ReEncrypt*",
        "kms:GenerateDataKey*"
      ],
      "Resource": "arn:aws:kms:us-east-1:219829223284:key/8d27048e-9b70-47a2-af7d-79982a417561"  ---> Customer key ARN
    } 

D&B Direct+ Managed Universes

All Universes include the following rules:

  • Company status is not Deleted
  • Company status is not Under Review
Description Universe ID Universe Rules
Full Universe FULL This universe includes D-U-N-S Numbers that meet the general rules listed above. No additional rules are applied.
Active in Japan ACTVJP This universe includes D-U-N-S Numbers that meet all the following criteria:
- Country is Japan (JP)
- Operating Status is Active
Alternative Linkage LNKALT This universe includes D-U-N-S Numbers that meet all the following criteria:
- Alternative Linkage element is present and not null.
Commercially Active CMCLACTV This universe includes D-U-N-S Numbers that meet all the following criteria:
- Company is not de-listed
- Mail is deliverable
- Operating Status is Active
Decision HQ AASDHQ This universe includes D-U-N-S Numbers that meet all the following criteria:
- isStandalone=false or null
Exclude Branches EXBRCH This universe includes D-U-N-S Numbers that meet all the following criteria:
- Is not a branch
Fortune 1000 F1000 This universe includes D-U-N-S Numbers that meet all the following criteria:
- Fortune1000 = True
- Operating status is Active
Global IT Buydex AASBIG This universe includes D-U-N-S Numbers that meet all the following criteria:
- IT Buydex element is present and not null
- Operating status is Active
Global Marketable & Corporate Linkage MKTLNK This universe includes D-U-N-S Numbers that meet all the following criteria:
- dunsControlStatus.isMarketable is True
- isStandalone is false.
Material Change AASMCU This universe includes D-U-N-S Numbers that meet all the following criteria:
Either
- Opportunity Final Segment Code is present and not null.
- Material Change Segment Code element is present and not null.
And
- Operating Status is Active
Minority Linkage LNKMIN This universe includes D-U-N-S Numbers that meet all the following criteria:
- Minority Linkage element is present and not null.
Total Loss Predictor AASTLP This universe includes D-U-N-S Numbers that meet all the following criteria:
- Total Loss Predictor element is present and not null.
Upward Linkage LNKUPD This universe includes D-U-N-S Numbers that meet all the following criteria:
- isStandalone is false