D&B API Overview

Welcome to the D&B Direct+ Developer Portal!

The API is REST based. All requests must be made over HTTPS. All request and response body data is in JSON format.

Authentication

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 page.

Requests

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.
PATCH Used to update Monitoring Registrations.

Rate limiting

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.

Quota Enforcement

D&B Direct+ limits the number of requests based on contract quota limits and terms. These limits apply to the following APIs:

  • Data
  • Family Tree
  • Identity Resolution (IDR)
  • Search

Each API call counts towards the quota regardless of product or feature used; it is the total number of calls for the API.

Responses

All data is received as a JSON object. Details on response contents can be found in the individual API documents.

Example Requests & Responses

Each API document includes an example request and response. As with any REST API, you can also test API requests and responses using a Chrome extension like Advanced REST Client or POSTMAN.

Postman collections are provided for each API: Postman Collections.

To get started with Postman, please see the Postman Tutorial.

Versioning and Changes

  • 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.

Breaking vs. non-breaking changes

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:

  • Renaming fields
  • Changing JSON paths
  • Changing fields from a single value to an array
  • Removing fields

API Best Practices

We strongly recommend that you design your integration with the following guidelines in mind:

  • Adhere to rate limiting guidelines
  • Handle errors appropriately
  • Implement logging

Adhere to rate limiting guidelines

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."
    }

Handle “Too Many Requests” error

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).

Handle errors appropriately

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 on every API page. For example, Error and Information Codes.

Implement Logging

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"
      }
    }

API Troubleshooting

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:

  1. Try executing the same API Request using a tool like cURL or Postman. By taking your code out of the equation, you can isolate troubleshooting to the raw Request / Response.
  2. If you receive a similar error when you execute the Request using cURL or Postman, there is likely an issue with the Request format or contents. Refer to the API Documentation for the correct format and contents.
  3. If you are able to execute the Request successfully using cURL or Postman, than it is likely that the Request your code is sending is different than what you intend. You’ll need to compare the successful Request with the unsuccessful Request that your code is generating.

    • Examine the Request that your code is sending (including the HTTP verb, URI, headers, and Request body) and the Response that it’s receiving back from Smartsheet (including the HTTP status code, headers, and response body).
    • Inspect the full trace of Request and Response in the log file. Compare the Request that your application is logging with the successful Request from cURL or Postman, and update your code to correct any discrepancies.
    • Try a tool like Fiddler or Charles HTTP Proxy to inspect the full trace of Request and Response. Compare the Request trace that your application generates with the successful Request from cURL or Postman, and update your code to correct any discrepancies.

Testing with Postman

A D&B Direct+ API Tutorial using Postman is available here.

Postman collections are provided for each API: Postman Collections.