Using the D&B Connect APIs

The API provides REST based access to D&B Connect. All requests must be made over HTTPS. All request and response body data is in JSON format.

Important information about D&B Connect API:

• Currently, D&B Connect API supports only PROD keys.
• API key and secret will be at a tenant level and not at a user level.
• D&B Connect API leverages Match and Append (matchEnrich) service which will return the one best match plus the requested data product contents.
• In order to take advantage of the Connect API, you will need to specify your source using the Connect UI. And it is very easy to use.
• Changes made in the Connect UI are automatically reflected in your API endpoint.
  For instance, if you need to add new element and/or update the corresponding confidence code, you do not need to contact your technical team. You may use the Connect UI to update the API endpoint with your changes.

Authentication

Key and secret were emailed to your Administrator with the subject line D&B Connect - Private API Key

D&B Connect 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.

Requests

The D&B Connect 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:

Matching

The purpose of the Connect API is to match your input data with an entity so it can be further enriched by Dun & Bradstreet data.

Connect API supports four different match types

• D-U-N-S Match where the input is the D-U-N-S value for the entity.
• Name and Location Match were the input is at least the entity name and the country it is located in.
• Registration Number Match were the input is at least the registration number of the entity and the country it is located in.
• Domain Match were the input is either an email address for the entity or the url for the entity.

Providing more data than the minimum is encouraged since it will provide more accurate match results.

Connect API accepts up to 12 parameters. Depending on the match type various ones are required.

A D-U-N-S match for Source_drcjq1kc (source values found in Connect web interface)

GET https://plus.dnb.com/v1/connect/matchEnrich/v1/Source_drcjq1kc?duns=804735132

A Name and Location match with the minimum required data

GET https://plus.dnb.com/v1/connect/matchEnrich/v1/Source_drcjq1kc?name=Gorman

Responses

All data is received as a JSON object. The response contains four main sections:

• input - this is the same data that the user provides in the query parameters.
• matched - the result of the match phase.  If no entity matches then this will only contain the matchStatus value. If several entitles match this will contain the best match.
• enriched - data selected by the user when setting up the source.  This will be empty if no entity meets the match criteria set for the source.
• cleansed - For Name matches this will contain the D&B standard way to describe the Name.
• detail - technical information about the match.

Example of successful D-U-N-S match response:

{
	{
		"inquiryDetail": {
			"name": "GORMAN",
			"country": "US"
		},
		"matchCandidates": [
			{
				"organization": {
					"duns": "802707141",
					"dunsControlStatus": {
						"operatingStatus": {
							"description": "Active"
						}
					},
					"primaryName": "GORMAN COMPANY",
					"primaryAddress": {
						"addressCountry": {
							"isoAlpha2Code": "US"
						}
					}
				},
				"matchQualityInformation": {
					"confidenceCode": 6,
					"matchGrade": "AZZZZZZZFZZ",
					"matchDataProfile": "0099999999999999000000980098",
					"nameMatchScore": 100.0
				}
			}
		],
		"candidatesMatchedQuantity": 1,
		"matchDataCriteria": "Name and Address Lookup",
		"matchStatus": "success",
		"embeddedProduct": {
			"organization": {
				"duns": "802707141",
				"primaryName": "Gorman Company",
				"assignmentModel": {
					"salesReliability": {
						"dnbCode": 33392
					},
					"physicalLocation": {
						"employeeCount": 3,
						"salesAmount": 1332326.0
					},
					"domesticUltimate": {
						"employeeCount": 8,
						"familyTreeMembersCount": 2
					}
				},
				"countryISOAlpha2Code": "US",
				"primaryAddress": {
					"addressLocality": {
						"name": "Phoenix"
					},
					"addressRegion": {
						"name": "Arizona",
						"abbreviatedName": "AZ"
					}
				}
			}
		},
		"cleanseAndStandardizeInformation": {},
		"transactionDetail": {
			"transactionID": "rrt-0b7918993e371e8cc-c-ea-26329-212763782-20",
			"transactionTimestamp": "2022-03-30 12:56:02+0000",
			"serviceVersion": "1",
			"inLanguage": "en-US"
		}
	}

RATE LIMITING

D&B Connect 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 Connect limits the number of requests based on contract. Quotas based on UTC time; Quota counters are reset based on the term as follows:

• Daily quotas reset at midnight UTC.
• Weekly quotas reset at midnight UTC Sunday.
• Monthly quotas reset at midnight UTC on the last day of the month.

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

Data Transport Security

Please see the Data Transport Security section in FAQ for more details.

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

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.

A list of error codes and recommendations for handing are available under Resources: 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=v1Authorization: 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 issending 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 Connect API Tutorial using Postman is available here.

Postman collections are provided for each API: Postman Collections.