Direct+ Product Documentation
The API is REST based. All requests must be made over HTTPS. All request and response body data is in JSON format.
D&B Direct+ API calls utilize access tokens, generated from a consumer key/secret combination, for authentication (based on the Client Credentials Grant flow of the OAuth 2 specification.
For details on generating an Access Token, please see the Authentication Guide.
The D&B Direct+ API is based on REST principles: data resources are accessed via standard HTTPS requests in UTF-8 format to an API endpoint. Where possible, the API strives to use appropriate HTTP verbs for each action:
| VERB | DESCRIPTION |
|---|---|
| GET | Used for retrieving content. |
| POST | Used for performing an action such as Search or creating a Monitoring Registration. |
| DELETE | Used for deleting Monitoring Registrations or unsuppressing notifications. |
| PATCH | Used to update Monitoring Registrations. |
For each API, the API Reference page includes the URI, Verb used, a description, code sample, request parameters, and response parameters.
The code sample is automatically generated from the request parameters. Code should be verified before use; all parameters are included in the sample, even if they are mutually exclusive.
D&B Direct+ applies rate limits on a subscriber basis (based on Consumer Key), regardless of how many users are using the API.
If you get status code 429, it means there were too many requests to be processed. Additional information is under Adhere to rate limiting guidelines.
D&B Direct+ limits the number of requests based on contract. Quotas based on UTC time; Quota counters are reset based on the term as follows:
Each API call counts towards the quota regardless of product or feature used; it is the total number of calls for the API.
All data is received as a JSON object. Details on response contents can be found on the individual API Reference page. Responses for each API are documented on its API Reference page.
IMPORTANT: Please see the Security Upgrade Enhancements, effective October 27, 2020.
Non-breaking changes: New functionality and bug fixes will be added to the API over time. You should expect to see new endpoints or new attributes for existing objects. Such changes will not result in a new API version. Please make sure that your code can handle new attributes gracefully. Also, please make sure your code does not depend on the order in which records are returned, unless it is explicitly stated in this documentation.
Breaking changes: If and when we decide to add functionality that breaks the contract of the current API, we will publish it with a new version number, so as to keep the existing API functionality backwards compatible.
Deprecations: An API may occasionally be deprecated which indicates that the API should no longer be used in active development. Deprecated APIs typically remain present and usable for a reasonable period of time following the release in which they were deprecated, but may be removed entirely from a future release. You should never use deprecated APIs in new development, and if you have existing code that uses deprecated APIs, we recommend that you update that code as soon as possible.
Non-breaking changes tend to be additive: adding new fields or nested resources to your resource representations, adding new endpoints such as a PUT or PATCH that was previously unavailable. API consumers should build client code that is resilient to these kinds of non-breaking changes.
Breaking changes include:
We strongly recommend that you design your integration with the following guidelines in mind:
In order to prevent abuse and undue stress, API clients have restrictions for transactions per second (tps) and transactions quota per week, month, or year based on the customer contract.
If tps is exceeded, the system responds with a 429 HTTP status code, along with one of the following as part of the JSON response body:
"error": {
"errorCode": 0045,
"errorMessage": "Too Many Requests."
}
"error": {
"errorCode": 0046,
"errorMessage": "Too Many Requests."
}
In addition, Direct+ uses a Spike Arrest for each API to handle traffic spikes and avoid lag and downtime.
If Spike Arrest limit is exceeded, the system responds with a 429 HTTP status code, along with one of the following as part of the JSON response body:
"error": {
"errorCode": 0047,
"errorMessage": "Too Many Requests."
}
We recommend that you design your integration to gracefully handle the tps limit error. One way of doing that would be to have your integration sleep for 60 seconds when this error is encountered, and then subsequently retry the request. Alternatively, you might choose to implement exponential backoff (an error handling strategy whereby you periodically retry a failed request with progressively longer wait times between retries, until either the request succeeds or the certain number of retry attempts is reached).
A successful error handling strategy requires that your integration recognize the difference between errors that can potentially be resolved by retrying the request and errors that should never be retried automatically. The HTTP status code that is returned with each response is your first indication as to the outcome of the request.
| HTTP status code | Meaning | Retry? |
|---|---|---|
| 2xx | Request was successful. | n/a |
| 4xx | A problem with the request prevented it from being executed successfully. | Never automatically retry the request. |
| 5xx | The request was properly formatted, but the operation failed on the D&B side. | In some scenarios, requests could be automatically retried using exponential backoff. In other cases, requests should not be retried. |
A list of error codes and recommendations for handing are available under Resources: Error and Information Codes.
We strongly recommend that you design your integration such that it is capable of logging API requests and responses. Having access to the raw requests and responses (including detailed error codes and error messages) when API issues emerge will streamline troubleshooting and accelerate time to resolution.
The following examples show the type of information that your application should log for API requests and responses.
Request: verb, URI, header(s), request body
GET https://plus.dnb.com/v1/data/duns/2376389?productId=cmpelk&versionId=v1
Authorization: Bearer MY_TOKEN
Content-Type: application/json
Response: HTTP status code, response body
HTTP status: 400 Bad Request
{
"transactionDetail": {
"transactionID": "rrt-e39b70d3-b-ea-4947-10833556-1",
"transactionTimestamp": "2017-03-24T21:24:46.545Z",
"inLanguage": "en-US",
"productID": null,
"productVersion": null
},
"inquiryDetail": {
"duns": "2376389",
"productID": "cmpelk",
"productVersion": "v1"
},
"error": {
"errorCode": "10003",
"errorMessage": "Supplied DUNS number format is invalid"
}
}
Should you encounter issues with the API while building an integration using a particular programming language (e.g., Java, C#, PHP, Python), keep the following troubleshooting techniques in mind:
A Direct+ API Tutorial using Postman is available here.
Postman collections are provided for each API: Postman Collections.
Direct+ Product Documentation