Monitoring APIs

The Monitoring APIs allow you to manage your registrations. This page provides a list of the available APIs as well as guidelines and best practices for using them.

The following functions are provided to manage Registrations:

• Add D-U-N-S Numbers to an Existing List of D-U-N-S Numbers (LOD) Registration: At any time after a registration is created, you may add additional D-U-N-S Numbers to be monitored using the Monitoring API. For guidelines on using this feature, see Add D-U-N-S Numbers to an Existing Registration.
• Add Single D-U-N-S Number to a LOD Registration: At any time after a registration is created, you may add a single D-U-N-S Number to the registration.
• Check for D-U-N-S Numbers in Registration: Checks if the specified D-U-N-S Numbers exists in the specified Registration.
• Delete a Registration: If you no longer need a registration, it can be deleted. Delete cannot be undone.
• Edit Registration Details: Some properties of a registration can be modified (e.g., email addresses or delivery method). For guidelines on using this feature, see Edit Registration.
• Export List of D-U-N-S Numbers: A list of D-U-N-S Numbers that are included in an LOD Registration can be exported to a file. For guidelines on using this feature, see Export List of D-U-N-S Numbers.
• Get Registration Details: Returns the settings for a specific Registration.
• Get Registration Status: Returns the status of the registration: Locked or Active. If a registration is Locked, no API requests for it will be accepted; once it is Active, requests can be accepted.
• List Pending Deliveries: Provides a list of artifacts that have not yet been delivered (e.g., because delivery was suppressed).
• List Registrations (for subscriber): Returns a list of all Registrations for a specific subscriber (based on authentication code). The system will return a list of Registration identifiers, but no other details.
• Remove D-U-N-S Numbers from a LOD Registration: At any time after a registration is created, you may remove D-U-N-S Numbers from the registration; you will no longer receive notifications on D-U-N-S Numbers that have been removed. For guidelines on using this feature, see Remove D-U-N-S Numbers from an Existing Registration.
• Remove Single D-U-N-S Number from a LOD Registration: At any time after a registration is created, you may remove single D-U-N-S Number from the registration; any existing notifications for the deleted D-U-N-S Number will still be delivered.
• Request Notifications be sent: If notifications were suppressed and have now been unsuppressed, this feature can be used to request notifications be sent immediately rather than waiting until the next regularly scheduled delivery.
• On Hold Notifications: Notifications can be placed On Hold. The On Hold state will retain the registration configurations, but the system will not process the registration. Registrations can be subsequently transitioned from the On Hold state to Current state.
• Suppress Notifications: Notifications can be supressed using the Monitoring API. Once suppressed, no notifications will be delivered until an unsuppress request is received for the same Registration. During this period, the system aggregates the changes for each day into a single UPDATE notification. Supress Notifications should not be used in the long term. If a Registration is no longer required it should be deleted, or placed on Hold. Note - if a Intra-day or Daily frequency registration is supressed for a month it will automatically be transitioned to On Hold.
• Unsuppress Notifications: To start receiving notifications for a Registration that was previously suppressed, use the Monitoring API to unsupress the notifications. Once unsuppressed, monitoring notifications will be delivered at the next regularly scheduled notification period. If there were any changes between when the notifications were suppressed and unsuppressed, the change notification will contain the original value from that time and current value.
• Pull new Notifications: Provides the ability to Pull notifications for a registration. The registration must have been created with deliveryTrigger set to API_PULL in order to use the pull API. If maxNotifications is not specified then one notification will be returned (if available). Notifications are available for up to 4 days to be pulled. 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). Notifications which are pulled are 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.
• Replay (re-pull) Notifications: Provides the ability to replay (re-pull) previously pulled notifications for a registration. Notifications which were pulled are available for replay (to be re-pulled) via the replay API for 14 days. If maxNotifications is not specified then one notification will be returned (if available). The replay API will return to the first notification after timestamp indicated by the mandatory replayStartTimestamp parameter up to the maxNotifications number if available.

Before using any API, you must have an access token; see the Authentication page for more information.

The following resources are available:

• Error and Information Messages is a list of all error messages with explanation and suggested actions.
• JSON sample containing all possible response elements.
• Postman collection allowing you to run the APIs from Postman.

Add D-U-N-S Numbers to an Existing Registration

This feature can be used to add one or more D-U-N-S Numbers to an existing Monitoring Registration. Adding D-U-N-S Numbers is a batch operation; once the API request is accepted, the request will be processed and an email will be sent once it is completed.

Best Practice:

• For lists 100,000 or fewer, multiple requests per day can be submitted, but should be limited to 2 or 3; requests will be rejected if the registration is locked. If a registration is locked, no API requests for it will be accepted until the initial requests have been processed.
  
• For larger lists, please coordinate with your Dun & Bradstreet representative to schedule a seed file delivery.

A file with a list of D-U-N-S Numbers must be attached to the request. The file must be a flat structure, with each D-U-N-S Number to be added on a separate line.

Any failures are logged in the Registration exceptions file that is transferred to the defined delivery location.

If the initial Monitoring Registration included a request for seed data, a Seed Notification for each added D-U-N-S Number will be included with the next regularly scheduled notification.

Delete Registration

This feature can be used to delete a Registration. Once a Registration is deleted, it cannot be restored (it must be re-created) and change notifications will no longer be provided for the product and D-U-N-S Numbers in that Registration.

Before deleting a registration, consider:

• To stop receiving notifications for a short time, instead of deleting the registration suppress the notifications.
• If you may create the registration again later, retrieve the details and D-U-N-S Numbers in the registration before deleting it (this is particularly useful if you are changing from monitoring v1 to monitoring v2 of the same product).

  - Get Registration Details
  - Get list of D-U-N-S Numbers in Registration
  

Deleting a registration requires 2 steps:

• Requesting the delete.
• Confirming the delete.

Edit Registration

This API can be used to change most Registration properties. The following cannot be changed:

• Reference
• Product
• Version

To change the registered D-U-N-S Numbers, please see Add D-U-N-S Numbers to an existing Registration or Remove D-U-N-S Numbers from an Existing Registration.

Changing Frequency

A frequency change does not happen immediately. The previous frequency is still in effect until the last delivery in the cycle. For example:

• If the frequency is changed from DAILY to WEEKLY, the current DAILY notifications are delivered.
• If the frequency is changed from WEEKLY to DAILY, the current WEEKLY notifications are delivered on their original schedule, then daily notifications will be delivered.

Export List of D-U-N-S Numbers

The system sends an email confirming the file has been delivered per the delivery channel configuration in the Registration.

The text file provided will list all the D-U-N-S Numbers that are currently part of the Registration.

The file will be available in the defined delivery location as REFERENCE_YYYYMMDDHHMMSS_DunsExport_FILE-NUMBER.zip

• REFERENCE = the reference defined at registration request.
• YYYYMMDDHHMMSS = the date and time the file was generated.
• FILE-NUMBER = the number of the file. Not included for header files. Multiple files are delivered to keep the maximum size under 3GB.

Remove D-U-N-S Numbers from an Existing Registration

This feature can be used to remove one or more D-U-N-S Numbers to an existing Monitoring Registration. Removing D-U-N-S Numbers is a batch operation; once the API request is accepted, the request will be processed and an email will be sent once it is completed.

Best Practice:

• For lists 100,000 or fewer, multiple requests per day can be submit, but should be limited to 2 or 3; requests will be rejected if the registration is locked. If a registration is locked, no API requests for it will be accepted until the initial requests have been processed.
  
• For larger lists, requests should be limited to once per week.

A file with a list of D-U-N-S Numbers must be attached to the request. The file must be a flat structure, with each D-U-N-S Number to be removed on a separate line.

Any failures are logged in the Registration exceptions file that is transferred to the defined delivery location.