Dun & Bradstreet Business Match

Dun & Bradstreet Business Match searches D&B for organizations that match the business stored on a Lendflow application. The Workflow Builder block runs service dnb_bm_l1 for business entities and returns candidate organizations with match-quality details.

Requirements

Only the business legal name and country are required by the current D&B request validator. Additional valid values improve the provider’s match context.

Application field	Requirement	Notes
Business legal name	Required	Must contain at least one character.
Business address country	Required	Must use a valid ISO alpha-2 country code.
Address line 1	Optional	Additional valid address information can improve matching.
Address line 2	Optional	Additional valid address information can improve matching.
City	Optional	Additional valid address information can improve matching.
State or region	Optional	Must be valid for the business country when present.
Postal code	Optional	Must be valid for the business country when present.
Business contact telephone	Optional	Must be valid when present.
Business contact email	Optional	Must be valid when present.
Existing D-U-N-S Number	Optional	Uses the identifier already stored on the business when available.
EIN or Canadian business number	Optional	Used only when valid for the country: an EIN for US businesses or a business number for Canadian businesses.

Run through the application enrichment API

Call PUT /api/applications/{application_id}/enrich through Enrich Business Credit Application.
Set provider to dnb_bm_l1.
Do not send service-specific options; Business Match has no configurable options.
Include stage_id only when the application workflow requires a specific underwriting stage.
Confirm that the response contains data.onqueue: true.
Poll Get Commercial Data with services[]=dnb_bm_l1.

{
  "provider": "dnb_bm_l1",
  "stage_id": "00000000-0000-4000-8000-000000000000"
}

The request is asynchronous. data.onqueue: true confirms that Lendflow queued the job; it does not mean D&B returned a candidate. The commercial-data endpoint returns this service in a stored-validation wrapper:

Provider result: data.commercial_data.dnb.bm_l1.response
Stored request: data.commercial_data.dnb.bm_l1.request
Latest lifecycle message: data.statuses.dnb.bm_l1
Provider HTTP status: data.commercial_data.dnb.bm_l1.status_code

Unlike most services, the D&B Business Match request is nested beside response in the commercial_data object, not under request_data.

Data Orchestration availability and flow

The Dun & Bradstreet Business Match block is available in Workflow Builder’s underwriting Match group for business entities. It runs dnb_bm_l1.

Add Dun & Bradstreet Business Match to a business underwriting workflow.
Ensure the required business name, country, and D&B access are available before the block runs.
Connect the block before any downstream step that needs a D-U-N-S Number, then save and publish the workflow.
Execute the published orchestration through Execute Data Orchestration with template_id, application_id, and stage_id when applicable.
Confirm that the response contains data.executed: true.
Monitor the asynchronous run with List Data Orchestration Logs.
Read the stored result and status from the commercial-data paths above.

Business Match has no upstream data-service dependency. When a candidate contains a D-U-N-S Number, Lendflow stores the first candidate’s value on the business; place Business Match before D&B report blocks that depend on that identifier.

What the service returns

Response area	Meaning
`matchCandidates`	Zero or more D&B organizations that match the submitted business information.
`organization`	Identity, address, contact, operating-status, and corporate-linkage data for one candidate.
`matchQualityInformation`	Overall confidence, name score, match grade, and component-level match signals.
`displaySequence`	Provider ranking of the candidate in the returned result set.

Representative response

This abbreviated response follows Lendflow’s current D&B fixture. Business and contact values are sanitized.

{
  "matchCandidates": [
    {
      "displaySequence": 1,
      "organization": {
        "duns": "123456789",
        "primaryName": "EXAMPLE SUPPLY LLC",
        "isStandalone": true,
        "primaryAddress": {
          "streetAddress": { "line1": "100 MAIN ST", "line2": null },
          "addressLocality": { "name": "AUSTIN" },
          "addressRegion": { "name": null, "abbreviatedName": "TX" },
          "postalCode": "78701",
          "addressCountry": { "name": "United States", "isoAlpha2Code": "US" }
        },
        "dunsControlStatus": {
          "operatingStatus": { "dnbCode": 9074, "description": "Active" },
          "isMailUndeliverable": false
        }
      },
      "matchQualityInformation": {
        "confidenceCode": 10,
        "nameMatchScore": 100,
        "matchGrade": "AAAAAZZAFAA",
        "matchGradeComponents": [
          { "componentType": "Name", "componentRating": "A" },
          { "componentType": "Phone", "componentRating": "Z" }
        ]
      }
    }
  ]
}

Response attributes

Candidate identity and ranking

Attribute	Type	Meaning	Possible values or units	When returned
`matchCandidates`	Array of objects	Candidate organizations returned by D&B.	Zero or more candidates.	On a stored provider response.
`matchCandidates[].displaySequence`	Number	Candidate order assigned by D&B.	Positive integer; a lower number appears earlier.	For each candidate.
`matchCandidates[].organization.duns`	String or null	D-U-N-S Number for the candidate.	Identifier string.	When D&B identifies the organization.
`matchCandidates[].organization.primaryName`	String or null	Primary organization name.	Provider text.	When available.
`matchCandidates[].organization.isStandalone`	Boolean or null	Whether D&B reports the organization outside a legal family tree.	`true` or `false`.	When D&B supplies the flag.
`matchCandidates[].organization.telephone`	Array of objects	Provider telephone records.	Items can contain `telephoneNumber` and `isUnreachable`.	When available; it can be empty.
`matchCandidates[].organization.websiteAddress`	Array	Provider website records.	Zero or more objects.	When available; it can be empty.
`matchCandidates[].organization.tradeStyleNames`	Array	Trading names associated with the organization.	Zero or more objects.	When available; it can be empty.
`matchCandidates[].organization.mostSeniorPrincipals`	Array	Senior principal records.	Zero or more objects with `fullName` when supplied.	When available; it can be empty.

Addresses and operating status

Attribute	Type	Meaning	Possible values or units	When returned
`organization.primaryAddress`	Object or null	Primary address for the candidate.	Provider address object.	When available.
`organization.primaryAddress.streetAddress.line1`	String or null	First address line.	Text or `null`.	When available.
`organization.primaryAddress.streetAddress.line2`	String or null	Second address line.	Text or `null`.	When available.
`organization.primaryAddress.addressLocality.name`	String or null	City or locality.	Text or `null`.	When available.
`organization.primaryAddress.addressRegion.abbreviatedName`	String or null	State or region abbreviation.	Provider code or `null`.	When available.
`organization.primaryAddress.postalCode`	String or null	Postal code.	String, preserving leading zeroes.	When available.
`organization.primaryAddress.postalCodeExtension`	String or null	Postal-code extension.	String or `null`.	When available.
`organization.primaryAddress.addressCountry.isoAlpha2Code`	String or null	Country code.	ISO alpha-2 code.	When available.
`organization.mailingAddress`	Object or null	Mailing address.	Fields can be `null`, empty arrays, or populated values.	When available.
`organization.dunsControlStatus.operatingStatus.dnbCode`	Number or null	D&B operating-status code.	Provider code.	When available.
`organization.dunsControlStatus.operatingStatus.description`	String or null	Human-readable operating status.	Provider text such as `Active`.	When available.
`organization.dunsControlStatus.isMailUndeliverable`	Boolean or null	Whether mail is reported undeliverable.	`true` or `false`.	When available.

Match quality

Attribute	Type	Meaning	Possible values or units	When returned
`matchQualityInformation.confidenceCode`	Number	D&B’s overall candidate confidence code.	Numeric provider code; the current fixture uses `10`.	For each candidate when scored.
`matchQualityInformation.nameMatchScore`	Number	Name-similarity score.	Numeric provider score; current fixture uses `100` for an exact name match.	When scored.
`matchQualityInformation.matchGrade`	String	Compact component-grade string.	Provider code.	When D&B calculates a grade.
`matchQualityInformation.matchGradeComponents`	Array of objects	Named match components and ratings.	Components such as Name, Street Number, City, State, Phone, and Postal Code.	When D&B supplies component grading.
`matchQualityInformation.matchGradeComponents[].componentRating`	String	Match quality for one component.	Current UI maps `A` to Match, `B` to Similar, `F` to Different, and `Z` to Not available.	For each returned component.
`matchQualityInformation.matchGradeComponentsCount`	Number	Number of returned grade components.	Count.	When supplied.
`matchQualityInformation.matchDataProfile`	String or null	D&B’s compact data-profile code.	Provider code; preserve without reinterpreting.	When supplied.
`matchQualityInformation.matchDataProfileComponents`	Array of objects	Component values underlying the data profile.	Provider component codes.	When supplied.
`matchQualityInformation.matchDataProfileComponentsCount`	Number	Number of profile components.	Count.	When supplied.

Errors and statuses

Status or error	Meaning
`Not yet started`	Lendflow has no service log for `dnb_bm_l1`.
`Started`	The external-service job started and remains asynchronous.
`Success`	Lendflow stored a D&B response and at least one candidate passed the service’s response check.
`DNB service Name and Address Lookup, error: ...`	Input validation failed, D&B returned no candidates, or D&B returned an error. Review the appended provider or validation message.
`Unable to retrieve DNB bearer token`	D&B authentication did not return an access token. Verify service access and credentials.
Service unavailable	The service is disabled for the client or D&B cannot be reached.
Provider HTTP status in `status_code`	The HTTP status saved with the D&B validation record. It is separate from Lendflow’s lifecycle message.

FAQ

Which inputs are required?

Business legal name and business-address country are required. Address, telephone, email, D-U-N-S Number, and country-specific registration number are optional but can improve match context.

Does data.onqueue true mean a match exists?

No. It only confirms that Lendflow queued the asynchronous job. Poll the commercial-data endpoint and inspect statuses.dnb.bm_l1 and commercial_data.dnb.bm_l1.response.matchCandidates.

Where is the stored D&B request?

It is at data.commercial_data.dnb.bm_l1.request. This service is an exception to the usual request_data placement.

Does Business Match save the D-U-N-S Number?

Yes, when the first candidate contains a D-U-N-S Number, Lendflow saves it on the application’s business for downstream D&B services.

How should I handle null and empty values?

Treat both as unavailable provider data. D&B can return null for scalar fields and empty arrays for unpopulated collections such as mailing-address components, websites, trading names, and principals.