On-Demand Entity Identification for Small Businesses

Also known as Small Business Match

Feature Request

IMPORTANT: Please see the new Online Services Security Enhancement Release, effective November 09, 2020.

Overview

The available criteria options are identical for Basic and Advanced match type requests. This feature will default to Advanced if a type is not specified.

There are several options available when implementing this feature.

1. Population: By default this feature will match against the universe of organizations for which D&B has assigned a D-U-N-S Number. An SBRI option (match type set to 'SBRI') is available to perform a match against the collection of U.S. small businesses for which a D-U-N-S Number has not been assigned.

2. Lookup: If a D-U-N-S Number is passed on the request, this feature will perform a direct match and return details about the organization to which the D-U-N-S Number is assigned. This option is not available when matching small businesses.

SBRI Lookup

In order to complete an SBRI lookup, name & address information must be submitted, along with matcht type text.

Global Availability

This data layer is only available for businesses domiciled in the United States.

Data Layer Entitlement

For customers in U.S. and Canadian markets, the API is provisioned for specific collections of products, reports, and/or features (collectively referred to as data layers) for production and trial usage. Entitlement is not required for testing in the sandbox environment.

• This feature is entitled as "On-Demand Entity Identification" for D&B Direct 2.0 customers.

NOTE: The SBRI match option of this feature will be entitled/invoiced under a "Search - Small Business Risk Insight" for D&B Direct 2.0 customers.

For customers in the UK, Ireland, Belgium, Netherlands and Luxembourg markets, the API is provisioned as a specific set of data layers for production, trial, and sandbox usage.

• This particular data layer is included in the D&B Direct Onboard 2.0 suite.

Specification

Please refer to the Minimum Requirements section in this topic for scenario specific Required fields.

GET https://direct.dnb.com/V5.0/organizations?match=true&MatchTypeText=SBRI&SubjectName=GORMAN MANUFACTURING&StreetAddressLine=492 KOLLER STREET&PrimaryTownName=SAN FRANCISCO&CountryISOAlpha2Code=US&TerritoryName=CA&FullPostalCode=94110
Authorization: <My Token>

Input parameters that include a "-n" designation may be repeated on the request, using a sequence number. For example, for the parameter "example-n", create a request like https://{endpoint}?{other parameters}&example-1={value}&example-2={value} and so on. If a single instance of the parameter is used, it still requires a "-1" suffix.

Endpoint

Use the following endpoint for requesting this feature. The {version} is dependent on the underlying service delivering the response.

NOTE: While "organizations" is part of this endpoint, there is no service by this name. Many D&B Direct calls have a similar structure; however, the {version} component is based on the SERVICE to which a given product is associated.

Testing

This operation will return a static set of results in the D&B Direct test environment (sandbox), regardless of the request parameters.

Exception: If the Small Business option is selected, this operation will not return any results in the D&B Direct sandbox.

Feature Response

NOTE: The D&B Direct REST implementation uses the BadgerFish approach for JSON with some minor variations.

Specification

The following is a list of the possible data fields returned by this operation in the JSON response. Samples are provided for testing successful and failed retrieval, and to demonstrate the basic layout of a response. The data returned in samples may not represent actual values that this feature will deliver.

The results from a small business search will return subject identification numbers (Subject ID) that may be used to request the Small Business Risk Insight product for additional information about an organization.

NOTE: The D-U-N-S Number returned in the response will be a nine-digit zero-padded, numeric value.

{
	"MatchResponse": {
		"@ServiceVersionNumber": "5.0",
		"TransactionDetail": {
			"ServiceTransactionID": "Id-0c90b85887646c00dc633900725c6df6-1",
			"TransactionTimestamp": "2017-03-02T16:35:10"
		},
		"TransactionResult": {
			"SeverityText": "Information",
			"ResultID": "CM000",
			"ResultText": "Success"
		},
		"MatchResponseDetail": {
			"CandidateMatchedQuantity": 1,
			"MatchCandidate": [{
				"SubjectID": "19248122082",
				"OrganizationPrimaryName": {
					"OrganizationName": {
						"$": "GORMAN MANUFACTURING COMPANY"
					}
				},
				"PrimaryAddress": {
					"StreetAddressLine": [{
						"LineText": "492 KOLLER STREET"
					}],
					"PrimaryTownName": "SAN FRANCISCO",
					"PostalCode": "94110",
					"TerritoryAbbreviatedName": "CA"
				},
				"TelephoneNumber": {
					"TelecommunicationNumber": "6505550000"
				},
				"MatchQualityInformation": {
					"ConfidenceCodeValue": 10,
					"MatchGradeText": "AAAAAZZ",
					"MatchGradeComponentCount": 7,
					"MatchGradeComponent": [{
						"MatchGradeComponentTypeText": {
							"$": "Name"
						},
						"MatchGradeComponentRating": "A",
						"MatchGradeComponentScore": 100,
						"DisplaySequence": "1"
					}, {
						"MatchGradeComponentTypeText": {
							"$": "Street Number"
						},
						"MatchGradeComponentRating": "A",
						"MatchGradeComponentScore": 100,
						"DisplaySequence": "2"
					}, {
						"MatchGradeComponentTypeText": {
							"$": "Street Name"
						},
						"MatchGradeComponentRating": "A",
						"MatchGradeComponentScore": 100,
						"DisplaySequence": "3"
					}, {
						"MatchGradeComponentTypeText": {
							"$": "City"
						},
						"MatchGradeComponentRating": "A",
						"DisplaySequence": "4"
					}, {
						"MatchGradeComponentTypeText": {
							"$": "State"
						},
						"MatchGradeComponentRating": "A",
						"DisplaySequence": "5"
					}, {
						"MatchGradeComponentTypeText": {
							"$": "PO Box"
						},
						"MatchGradeComponentRating": "Z",
						"DisplaySequence": "6"
					}, {
						"MatchGradeComponentTypeText": {
							"$": "Phone"
						},
						"MatchGradeComponentRating": "Z",
						"MatchGradeComponentScore": 448,
						"DisplaySequence": "7"
					}]
				}
			}]
		}
	}
}

Abbreviated Territory Names

When present, the Territory Abbreviated Name field will contain local abbreviations, which may be based on standard designations. For companies domiciled in the United States or Canada, this field will contain the second component of ISO 3166-2 codes. For example, the ISO 3166-2:US code for New Jersey is "US-NJ" and the value "NJ" will be delivered in this field. Similarly, the ISO 3166-2:CA code for Ontario is "CA-ON" and the value "ON" will be delivered in this field.

Response Codes & Error Handling

Successful service requests will return a CM000 response code in the TransactionResult ResultID field. Otherwise, one of the D&B Direct standard response codes will be returned.

This operation may return the following response codes: CM001, CM002, CM003, CM004, CM007, CM008, CM009, CM011, CM012, CM016, CP001, CP003, CP004, and SC001-SC009.

D&B Direct 2.0 API requests are provided on a metered basis; and may require entitlement prior to use in the production environment. In addition, a concurrency limit (QPS) is monitored to ensure that it is not exceeded. An error code will be returned in the event that a transaction is throttled.

Qualified usage (e.g., a successful response) is tracked and billed according to the terms & conditions of the customer's contract. The response codes CM000, CM010, PD002 and PD015 are considered successful. A built-in feature exists to prevent duplicate billing when multiple successful requests with the same criteria are submitted on the same calendar day (which is based on Eastern Standard Time [GMT-5]).

Business Elements

While D&B Direct uses a product canonical naming model in the request/response, many customers may be more familiar with the following business element labels.

What to do Next

• Retrieve additional Small Business details (using Subject ID)

• © Dun & Bradstreet, Inc. 2019 – 2024. All rights reserved.