Create Monitoring Registration

Create a Monitoring Registration for the product/datablock, version, and List of D-U-N-S Numbers (aka LOD) or Universe for which you want to receive change notifications for the specified frequency in either S3 or STP. The following are the different types of notifications that customer case can choose:

  1. UPDATE: For each D-U-N-S Number that has changed, only the changed data will be included in the notification.
  2. FULL_PRODUCT: For each D-U-N-S Number that has changed, the full details of the subscribed data set are included in the notification. This is equivalent to a seed for the D-U-N-S Number.
    IMPORTANT: Approval for FULL_PRODUCT registration is required. FULL_PRODUCT registrations are restricted to 1 datablock, and require Element Level monitoring (JSON Path inclusion/exclusion) to be set. Please reach out to your D&B Account team for assistance.
  3. SUMMARY: Available for Ultimate Beneficial Ownership (aka UBO/ cmpbol) and FULL_FAMILY_TREE product. In the case of FULL_FAMILY_TREE, for each D-U-N-S submitted in the registration, family tree changes are included in the notification.
  4. ALERT: Ability to set Thresholds against certain data elements. For each D-U-N-S Number that has changed, only the data which meet the threshold criteria are included in the notification. Not available for UBO (cmpbol) and FULL_FAMILY_TREE product.
    IMPORTANT: This notification type was referred as THRESHOLD until 1st July 2020. Any registrations created before that with the notficationType=THRESHOLD will continue to be supported.
  5. NONE: Only Seed file delivery. No change notices are delivered.

Monitoring Registration Process

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 or raise support ticket with https://support.dnb.com:

Property & Request param name Description Required Example
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. YES 999999999
Identifier (reference) 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. YES CUSTOMERNAME_ CMPELK_LOD_PROD
Description (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: . , -		 NO, Optional CMPELKV2UpdateRegn
Product (productID) 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.
IMPORTANT: cmpbol product cannot be registered for a Dynamic Universe, can only be registered for Full Universe. 		YES, either Product or Data Block(s)
For Family Tree: FULL_FAMILY_TREE
For UBO: cmpbol 		cmpelk
Data Block(s) (blockIDs) The block ID provided by Dun & Bradstreet that identifies the data block to be returned. Multiple values can be included, separated by commas. YES, either Product or Data Block(s) companyinfo_L1_v1
Product version (versionID) 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. YES, only for Product v2
LOD (duns) Indicates whether the registration is for List of D-U-N-S Numbers.
  • 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.		 For Data Products, UBO (cmpbol) & Family Tree: YES, Conditionally Required duns.txt
Subject IDs (subjectIDs) The list of unique identifiers assigned to the entities that can be selected by the subscriber for registration.
  • For Subject IDs, a file containing the list of Subject IDs (one per line) to be included in the registration must be provided. Supported file types:
    • .txt
    • .zip
Mutually exclusive with duns & Mutually inclusive with subjectIDType.		 For Data Products, UBO (cmpbol) & Family Tree: YES, Conditionally Required subjects.txt
Subject Type (subjectIDType) Denotes the type of the identifier used for the subject records in this registration. Possible values:
  • DUNS
  • SBFEID
Mutually exclusive with duns & Mutually inclusive with subjectIDType.		 For Data Products, UBO (cmpbol) & Family Tree: YES, Conditionally Required SBFEID
Universe (universe) Indicates whether the registration is for a Universe.
  • For Custom Universe, "CUSTOM".
  • For Universe, the name of a managed Universe.
This value cannot be changed once the registration is created. 		For Data Products: YES, Conditionally Required
For UBO (cmpbol): Only FULL
For Family Tree: Only FULL		 FULL
Custom Universe (universeCriteria) When universe is CUSTOM this field needs to be informed with a valid JEP expression. Supported fields and values in expression:
  • countryISOAlpha2Code: ISO 2 country code
  • hqCountryISOAlpha2Code: ISO 2 country code
  • operatingStatus ("ACTIVE", "OUT_OF_BUSINESS")
  • isStandalone or !isStandalone
  • failureScore_rawScore
  • supplierEvaluationRiskScore_rawScore
  • delinquencyScore_rawScore
  • globalBusinessRanking_rawScore
  • totalLossPredictorScore_rawScore

Note: No alert notification will be generated, if custom universe elements are not part of monitoring registration's data blocks. 		YES, for CUSTOM Universe. upper(countryISOAlpha2Code)=="US" AND upper(operatingStatus)=="ACTIVE"

upper(countryISOAlpha2Code)=="JP" AND isStandalone

upper(countryISOAlpha2Code)=="JP" AND !isStandalone

upper(countryISOAlpha2Code)=="JP" AND upper(hqCountryISOAlpha2Code)=="JP"

upper(countryISOAlpha2Code)=="PT" OR upper(countryISOAlpha2Code)=="GB" AND upper(operatingStatus)=="ACTIVE"

upper(countryISOAlpha2Code)=="GB" AND failureScore_rawScore==1.0

upper(countryISOAlpha2Code)=="US" AND failureScore_rawScore>1.0
Seed File (seedData) Indicates if a seed file should be delivered.Valid values:
  • true (default)
  • false
This value cannot be changed once the registration is created. 		For Data Products: YES
For Family Tree: YES
For UBO (cmpbol): N/A		 True
Notification Frequency (deliveryFrequency) Indicates how often notifications will be delivered. Valid values:
  • INTRA_DAY: Notifications will be sent as many times as the pipeline runs in a 24 hour period.
  • 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 except INTRA_DAY . 		YES, limited values.
For Data Products:
  • INTRA_DAY
  • DAILY
  • WEEKLY
  • MONTHLY (Approval required for FULL_PRODUCT notifications)
For Family Tree:
  • INTRA_DAY
For UBO (cmpbol):
  • INTRA_DAY
 DAILY
Delivery Trigger (deliveryTrigger) Indicates how notifications will be delivered. Valid values:
  • PUSH: Notifications will be sent via file.
  • API_PULL: Notifications will be retrieved by API. See Notifications through API for more information.
Note: FULL_FAMILY_TREE and cmpbol supports only PUSH delivery trigger. 		YES
For FULL_FAMILY_TREE and cmpbol: PUSH only		 PUSH
Notification Type (notificationType) Indicates the level of detail each change notification will include for any D-U-N-S Number that has changed. Valid values:
  • UPDATE: For each D-U-N-S Number that has changed, only the changed data will be included in the notification.
  • FULL_PRODUCT: For each D-U-N-S Number that has changed, the full details of the subscribed data set are included in the notification. This is equivalent to a seed for the D-U-N-S Number.
    IMPORTANT: Approval for FULL_PRODUCT registration is required. FULL_PRODUCT registrations are restricted to 1 datablock, and require Element Level monitoring (JSON Path inclusion/exclusion) to be set. Please reach out to your D&B Account team for assistance.
  • SUMMARY: Available for UBO (cmpbol) and FULL_FAMILY_TREE product. In case of FULL_FAMILY_TREE, for each D-U-N-S submitted in the registration, family tree changes are included in the notification.
  • ALERT: Ability to set Thresholds against certain data elements. For each D-U-N-S Number that has changed, only the data which met threshold criteria will be included in the notification. Not available for UBO (cmpbol) and FULL_FAMILY_TREE product.
    IMPORTANT: This notification type was referred as THRESHOLD until 1st July 2020. Any registrations created before that with the notficationType=THRESHOLD will continue to be supported.
  • NONE: Do not send notifications (not including Seed File)
This value cannot be changed once the registration is created. 		YES, limited values.
For Data Products:
  • UPDATE
  • FULL_PRODUCT
  • THRESHOLD*
  • NONE
For Family Tree:
  • SUMMARY
For UBO (cmpbol):
  • SUMMARY
  • FULL_PRODUCT
 UPDATE
Destination Type (destinationType) The communications protocol used to transfer change notifications and any other material related to the registration. Valid values:
  • STP
  • S3
  • GCS
For more information, see Destination Type 		YES S3
File Transfer Profile (fileTransferProfile) 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.
  • If Destination Type = GCS, the GCS path. For information on setting up GCS for monitoring access, Configure GCS.
 YES arn:aws:s3:::sample_bucket
Compression Type (compressionType) The compression technique used for the delivering the file. Valid values:
  • gzip
  • zip
 NO, Optional gzip
Encryption Key (encryptionKey) A key used to encrypt the files being delivered. This is only applicable if the File Transfer Profile is S3 or GCS.
For information on setting up S3 for monitoring access, Configure S3 Bucket.
For information on setting up GCS for monitoring access, Configure GCS Bucket.		 YES, Conditionally Required arn:aws:kms:us-east-1:2167:key/8d27048e-9b70-79982a417561
IAM Role (assumeRole) Access role for destination type. This can also be provided if the File Transfer Profile is S3 and is not applicable otherwise. For information on setting up IAM role for monitoring access, Configure IAM Role. NO, Optional arn:aws:iam::123456745558:role/qa-customer-role
Email Addresses (email) 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. YES jsmith@company.com, gjones@company.com
JSON Path Inclusion (jsonPathInclusion) 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.		 For Data Products: NO, Optional
For Family Tree & UBO (cmpbol): N/A		 organization.financials
JSON Path Exclusion (jsonPathExclusion) 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.		 For Data Products: NO, Optional
For Family Tree & UBO (cmpbol): N/A		 organization.legalEvents
Order Reason (orderReason) A D&B code value that defines the grounds for the customer requesting the product, e.g., required to support a credit decision.
Note : Required only for inquired or traded up German companies..
Possible values:
  • 6332 (Credit Decision)
  • 6333 (Assessment of credit solvency for intended business connection)
  • 6334 (Assessment of credit solvency for ongoing business connection)
  • 6335 (Debt Collection)
  • 6336 (Commercial Credit Insurance)
  • 6337 (Insurance Contract)
  • 6338 (Leasing Agreement)
  • 6339 (Rental Agreement)
 For Data Products: NO, Optional
For Family Tree & UBO (cmpbol): N/A		 6332
Thresholds (thresholds) For the data product/block(s) being monitored, set Thresholds against certain data elements. Notices will be generated only when threshold conditions are met. Please refer here for the JSON schema layout.
  • id : The unique identifier assigned to the threshold.
  • jsonPaths.path : Json paths to be included for alert condition.
  • jsonPaths.alias : The unique identifier assigned by the customer for the jsonPath.
  • condition : Threshold condition to monitor element(s).
    • See Monitoring APIs for more information
For Data Products: NO, Optional
For Family Tree & UBO (cmpbol): N/A		 [{
"id": "testRules",
"jsonPaths": [{
"path":
"organization.legalEvents. hasLegalEvents",
"alias": "events"
}],
"condition": "(events)"
}]
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, please coordinate with your Dun & Bradstreet representative to setup STP profile.
    • 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
    • Customers need to provide their S3 AWS bucket location for files to be delivered.
    • S3 bucket policy must allow write access by monitoring user. See Appendix: Configure S3 Bucket for details.
    • If “assumeRole” is provided in the request, the S3 bucket policy must grant write access to the specified role (“assumeRole”). See Appendix: Configure IAM Role for details.
  • GCS
    • Customers need to provide their Google Cloud Storage bucket location for files to be delivered.
    • GCS bucket policy must allow write access by monitoring service account. See Appendix: Configure GCS 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/datablock 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 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

Notifications through API

Provides the ability to pull change notifications for a small LOD registrations through API. It is recommended that pull API is only used for small registrations as it is more efficient and effective to have large numbers of notifications delivered via push (files). The registration must have been created with deliveryTrigger set to API_PULL in order to use the pull API. This is available for both FULL_PRODUCT and UPDATE notification types. FileTransferProfile is required for this type of registration to receive the seed files (if seed=true) and the exception file. It is not recommended to use longer deliveryFrequency WEEKLY or MONTHLY. In order to pull the notifications through API, the registration must be unsuppressed.

Pull Notification

For technical specifications refer: Pull new Notifications.

  • Notices will be available in the queue only for 4 days from the creation. It is recommended that customer pull the notification periodically based on their scheduled delivery frequency. If there are no notification they would get http status code as 204 with no messages.
  • Max number of notification pulled per request can be specified in the request. This is optional parameter with default=1. Customer has to call the Pull API multiple times until they get http status code as 204 for that period.
Replay(re-pull) Notification

For technical specifications refer: Replay(re-pull) Notifications.

  • Notifications which are pulled are only available for replay (to be re-pulled) via the replay API for 14 days. If notifications are not pulled for 4 days then they will be removed and a re-seed will be necessary.
  • Max number of notification and startTimestamp should be provided as part of the request. To pull the next set of notifications, the customer need to provide the timestamp of the last notifications that was pulled.
Please note:
  • If the registration is suppressed, Pull notification API will not return any notification.
  • If the registration is on hold, then Pull notification will return error.
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.)

Data Blocks/Data Products

Please refer to the Monitoring Guide by clicking here

Full Family Tree Product

Please refer to the Monitoring Guide by clicking here

UBO (cmpbol)

Please refer to the Monitoring Guide by clicking here

DNB Full Logo Direct+ Product Documentation