Search Guide

The Search API allows you to find entities using one or more specified property values. Search API provides the following features:

  • Contact search for contacts
  • Criteria search for companies
  • Typeahead search for companies

Common Characteristics

The following describe common behavior across search features.

Navigators provide ability to further filter search results (company criteria or contact).

If the returnNavigators parameter is included in the request the system returns Navigators along with the first page of search results.

Some Navigators are always included. Others are only included when they are found in entities in the result set. In both cases, the number of records for which the Navigator applies is included in the response.

Navigator Always Company Contact
numberOfEmployees-consolidated Yes Yes No
yearlyRevenue Yes Yes No
businessEntityType No Yes No
familytreeRolesPlayed No Yes No
location
- primaryAddress.countryISOAlpha2Code
- primaryAddress.addressRegion
- primaryAddress.addressLocality
No Yes Yes
industry (usSicV4) No Yes Yes
managementResponsbilities (MRC) No No Yes

To use Navigators, copy the sub-elements of query object into the body of the request.

Response structure

For request object:


{
  "navigators": {
    "yearlyRevenue": [
      {
        "candidatesMatchedQuantity": 844,
        "query": {
          "yearlyRevenue": {
            "minimumValue": 0,
            "maximumValue": 1000000
          }
        }
      }
    ]
  }
}

For request element or array Note: If request parameter is an array, the data type in the response is an array, but will contain only one value. Each available value is in a separate navigator entry.


{
  "navigators": {
    "businessEntityType": [
      {
        "candidatesMatchedQuantity": 763,
        "query": {
          "businessEntityType": [
            0
          ]
        }
      }
    ]
  }
}

Example

Note: See the Criteria Search JSON examples for more complete response samples.

Request 1


{
  "searchTerm": "dun",

Response 1 (snippet)


{
  "navigators": {
    "yearlyRevenue": [
      {
        "candidatesMatchedQuantity": 844,
        "query": {
          "yearlyRevenue": {
            "minimumValue": 0,
            "maximumValue": 1000000
          }
        }
      },
      {
        "candidatesMatchedQuantity": 25,
        "query": {
          "yearlyRevenue": {
            "minimumValue": 1000000,
            "maximumValue": 5000000
          }
        }
      }
    ],
    "numberOfEmployees": [
      {
        "candidatesMatchedQuantity": 756,
        "query": {
          "numberOfEmployees": {
            "informationScope": 9067,
            "minimumValue": 0,
            "maximumValue": 4
          }
        }
      },
      {
        "candidatesMatchedQuantity": 90,
        "query": {
          "numberOfEmployees": {
            "informationScope": 9067,
            "minimumValue": 5,
            "maximumValue": 10
          }
        }
      }
    ],
    "businessEntityType": [
      {
        "candidatesMatchedQuantity": 763,
        "query": {
          "businessEntityType": [
            0
          ]
        }
      },
      {
        "candidatesMatchedQuantity": 129,
        "query": {
          "businessEntityType": [
            451
          ]
        }
      }
    ],
    "familyTreeRole": [
      {
        "candidatesMatchedQuantity": 72,
        "query": {
          "familytreeRolesPlayed": [
            9140
          ]
        }
      },
      {
        "candidatesMatchedQuantity": 9,
        "query": {
          "familytreeRolesPlayed": [
            9141
          ]
        }
      }
    ],

To filter original search by family tree role = 9140, copy that query section (below) to the request and submit it.


       "familytreeRolesPlayed": [
            9140
          ]

Request 2


{
  "searchTerm": "dun",
    "familytreeRolesPlayed": [
            9140
          ]

Pagination

Criteria and Contact search results can be paginated; the request indicates how many results are included per page and which page number to return.

For example, if the page size is 20 and the page number is 3, results 41-60 are returned.

Multiple requests must be made to return all results. The maximum number, maximum page size, and maximum page number varies. Please see the API documentation Request Body descriptions for more information:

Search methods

For each parameter, the system uses one of the following search methods:

Search Method Description
Exact match Finds entities with the exact string entered. Correct punctuation is needed for the system to find matches. For example, If the term is "Company, Inc.", searching for "Company Inc" will not find a match.
Full Word match in sentence Parses inquiry string by using spaces as delimiters, and matches to entities using the words in any order. Any punctuation before or after a word must be included as part of the search string for the system to find a match.
Partial match (S/E) Finds the inquiry at the beginning of the entity attribute value. This is effectively a "wildcard at end" search.
Partial word match, any location Finds words anywhere in the entity attribute that match the inquiry string. It does not match the middle of words. Words are separated by spaces or punctuation.

String search examples
Search Method Sample Request Value Finds Does not find
Exact match (DUNS) 123456789 123456789
Full Word match in sentence (streetAddressLine1) - 13 parkway west
- 13 west parkway
- West 13 parkway
- Parkway west 13
- 14 parkway west - 13 parkway east
Partial word match, from start to end (Telephone) 973555 - 9735551212
- 9735551000
- 2015551212
- 9731230000
Partial word match, anywhere DNB NYSE:DNB

Delimiters

The Search engine indentifies words by spaces and periods.

For example:

  • Dun and Bradstreet = 3 words
  • dnb.com = 2 words
  • DUN&Bradstreet = 1 word

Equivalent Terms

The Search function recognizes some equivalent terms, improving quality of search results.

Equivalent Localities and Regions

Due to name changes, sometimes the locality or region criteria value in the search request is not the same as stored in the Dun & Bradstreet data; to improve search results, Search recognized the following as equivalent:

Old Name New Name
Bangalore Bengaluru
Belgaum Belagavi
Bellary Ballari
Bhir Beed
Bombay Mumbai
Burdwan Bardhaman
Calcutta Kolkata
Calicut Kozhikode
Chinsurah Chuchura
DhedhiDhani Mansanagar
Hubli Hubballi
Madras Chennai
Mangalore Mangaluru
Mysore Mysuru
Orissa Odisha
Pondicherry Puducherry
Poona Pune
Shimoga Shivamogga
Thana Thane
Trivandrum Thiruvananthapuram
Tumkur Tumakuru
Uttaranchal Uttarakhand

Synonyms

Currently supported synonyms:

Term Synonyms
and and, &
association association, assoc, assoc.
corporation corporation, co., corp., corp
incorporated incorporated, inc, inc.
limited limited, ltd, ltd., lmtd, llc, pty limited, pty, proprietary limited, pty ltd, pty ltd., plc

Competitors Search provides one method for initiating the request:

  • GET

The GET request searches by the provided D-U-N-S Number® and returns the top 3 competitors along with other competitors up to a total of 50.

How Results are Sorted

When results are returned, the system sorts them as follows:

  • The top 3 competitors as determined by Dun & Bradstreets expert analysis of the entity's competitors.
  • For Other competitors , the system sorts results as follows:
    • Active then Inactive
    • Revenue (descending)
    • Headquarters then Branch
    • D-U-N-S Numbers

Contact Search provides two methods for initiating the request:

  • GET
  • POST

The GET request searches by either email address or contact ID and returns one record.

The POST request provides several search parameters and may return multiple examples. The information below applies to the POST request.

Parameter Search Methods

The table below identifies the search method used for each request parameter.

Request Parameter Search Method
addressLocality Full word match
addressRegion Full word match
contactEmail Exact Match
contactID Exact Match
countryISOAlpha2Code Exact Match
duns Exact Match
familyName Partial word match, any location
givenName Partial word match, any location
industryCodes.code Exact Match
industryCodes.description Full Word Match
industryCodes.typeDnbCode Exact Match
jobTitles Full word match
postalCode Partial word match (S/E)
primaryName Full word match
tickerSymbol Partial word match (S/E)
tradestyle Full word match
usSicV4 Exact Match

How Results are Sorted

When results are returned, the system sorts them as follows:

  • If the sort parameter is not included, the response is ordered by givenName (ascending) first then lastName (ascending).

  • If the sort parameter is included, the ordering specified is used.

Criteria Search for Companies

Search requires that at least one "Standalone" parameter be included. These parameters are:

  • domain
  • duns
  • dunsList
  • industryCodes.code
  • industryCodes.description
  • industryCodes.typeDnbCode
  • locationRadius
  • primaryName
  • registrationNumbers
  • searchTerm
  • streetAddressLine1
  • telephoneNumber
  • tickerSymbol
  • tradestyleName
  • usSicV4

Parameter Search Methods

Criteria Search Method
addressLocality Full word match
addressRegion Full word match
businessEntityType Exact Match
countryISOAlpha2Code Exact Match
domain Exact Match
duns Exact match
dunsList Exact match
familytreeRolesPlayed Exact Match on any item in the list
globalUltimateFamilyTreeMembersCount Range
industryCodes.code Exact Match
industryCodes.description Full Word Match
industryCodes.typeDnbCode Exact Match
isExporter Exact Match
isFemaleOwned Exact Match
isImporter Exact Match
isMailUndeliverable Exact Match
isManufacturingLocation Exact Match
isMarketable Exact Match
isMinorityOwned Exact Match
isOutofBusiness Exact match
isPubliclyTradedCompany Exact match
isStandalone Exact match
isTelephoneDisconnected Exact Match
locationRadius Radius
numberOfEmployees Range
numberOfEmployees, consolidated or individual Exact Match
postalCode Partial word match (S/E)
primaryName Full Word match
registrationNumbers Exact Match
searchTerm Full word match
streetAddressLine1 Full word match
telephoneNumber Partial Match (S/E)
tickerSymbol Partial word match, any location
tradeStyleName Full Word match
usSicV4 Exact Match
yearlyRevenue Range

How Results are Sorted

If locationRadius is included in criteria, the system sorts the results as follows:

  • Distance from the specified latitude/longitude (if applicable)
  • D-U-N-S Numbers

Otherwise, the system sorts results as follows:

  • Active then Inactive
  • Revenue (descending)
  • Headquarters then Branch
  • D-U-N-S Numbers

Typeahead Search for Companies

Typeahead search enables users to quickly find company records without having to type the entire company information in the search request.

Parameter Search Methods

Request Parameter Search Method
searchTerm Partial Match, any location
countryISOAlpha2Code Exact Match

How Results are Sorted

When results are returned, the system sorts them as follows:

  • Active then Inactive
  • Revenue (descending)
  • Headquarters then Branch
  • D-U-N-S Numbers