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:
Note: Subjects can be identified using the D-U-N-S Number (or) other subject ID type.

API Method	Description
Add Subjects to an Existing Registration	At any time after a registration is created, you may add additional subjects to be monitored using the Monitoring API. For guidelines on using this feature, see Add Subject IDs to an Existing Registration.
Add Single Subject to a Registration	At any time after a registration is created, you may add a single subject to the registration. Note: This method is applicable only for Data Blocks and Data Products except Full Family Tree Registration.
Check for Subjects in Registration	Checks if the specified SubjectID exists in the specified Registration.
Export List of Subjects from Registration	A list of Subjects that are included in a Registration can be exported to a file. For guidelines on using this feature, see Export List of Subjects.
Remove Subjects from a Registration	At any time after a registration is created, you may remove Subjects from the registration; you will no longer receive notifications on SubjectIDs that have been removed. For guidelines on using this feature, see Remove Subject IDs from an Existing Registration.
Remove Single Subject from a LOD Registration	At any time after a registration is created, you may remove single Subject from the registration; any existing notifications for the deleted Subject will still be delivered.
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.
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.
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.

IMPORTANT: The following APIs has been deprecated. These are included only for reference purpose. New implementations must use Subject based APIs mentioned above.

API Method	Description
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. Note: This method is applicable only for Data Blocks and Data Products except Full Family Tree Registration.
Check for D-U-N-S Numbers in Registration	Checks if the specified D-U-N-S Numbers exists in the specified Registration.
Export List of D-U-N-S Numbers from Registration	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.
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.

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 Subject IDs to an Existing Registration

This feature can be used to add one or more Subjects to an existing Monitoring Registration. Adding Subjects 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:

Lists of up to 5million can be submitted each hour. Avoid submitting multiple smaller requests. 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 Subject IDs must be attached to the request. The file must be a flat structure, with each Subject ID 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 Subject ID 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 Subject IDs 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 Subject IDs 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 Subject IDs/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 Subjects, please see Add Subject IDs to an existing Registration or Remove Subject IDs 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.

Note: deliveryFrequency can only be decreased.
it can be changed from INTRA_DAY to DAILY (or) DAILY to WEEKLY (or) DAILY to MONTHLY (or) WEEKLY to MONTHLY - but cannot be updated from MONTHLY to WEEKLY, MONTHLY to DAILY, WEEKLY to DAILY, DAILY to INTRA_DAY.

Export List of Subjects

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 Subject IDs that are currently part of the Registration.

The file will be available in the defined delivery location as REFERENCE_YYYYMMDDHHMMSS_SubjectIDsExport_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 Subject IDs from an Existing Registration

This feature can be used to remove one or more Subjects from an existing Monitoring Registration. Removing Subjects 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:

Lists of up to 5million can be submitted each hour. Avoid submitting multiple smaller requests. 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 Subject IDs must be attached to the request. The file must be a flat structure, with each Subject ID to be removed on a separate line.

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

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:

Lists of up to 5million can be submitted each hour. Avoid submitting multiple smaller requests. 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

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.

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:

Lists of up to 5million can be submitted each hour. Avoid submitting multiple smaller requests. 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.