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:
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:
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.
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:
- Get Registration Details
- Get list of Subject IDs/D-U-N-S Numbers in Registration
Deleting a registration requires 2 steps:
This API can be used to change most Registration properties. The following cannot be changed:
To change the registered Subjects, please see Add Subject IDs to an existing Registration or Remove Subject IDs from an Existing Registration.
A frequency change does not happen immediately. The previous frequency is still in effect until the last delivery in the cycle. For example:
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.
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
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:
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.
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:
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.
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:
- Get Registration Details
- Get list of D-U-N-S Numbers in Registration
Deleting a registration requires 2 steps:
This API can be used to change most Registration properties. The following cannot be changed:
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.
A frequency change does not happen immediately. The previous frequency is still in effect until the last delivery in the cycle. For example:
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.
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
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:
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.