Cookies Settings

Loading

dnb-logo
Direct 2.0
Collapse

Contact Email Lookup

Returns search results of people based on keyword.

Update History

  • August 27, 2021 (v6.4 SOAP & REST): Enabling the mapping for contact FullName search element in request.
  • June 3, 2016 (v6.3 SOAP & REST): Added Job Function to Inquiry Details and new enumeration value Job Function to Sort Basis Text.
  • June 3, 2016 (v6.3 SOAP & REST): Added Job Function and Job Ranking to Find Candidate response.
  • December 12, 2014 (v6.1 SOAP & REST): Changes to the FindContact and Find Company operations include: 1. Added the following enumerations to InclusionDataEnum – IncludeNonMarketable, IncludeDelisted; and 2. Added the following enumerations to SortBasisText - Relevancy.
  • October 25, 2013 (v6.0 SOAP & REST): The following changes apply: IndustryTypeCode has been changed from a free-form text field to an enumerated type; Multiple postal code ranges may now be specified on requests; MarketingRiskClassCode may now include a value of 0 indicating "unknown"; InclusionDataDescription may now include a value of "IncludeNonMarketableOnly"; Three new filters provide the ability to screen on publicly traded companies, descendants of publicly traded companies, and organizations having a manufacturing facility; Added a new sort criteria: ConsolidatedEmployeeQuantity. This field is also included on the response; and Two new search facets that correspond to the publicly traded company filters.

Feature Request

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

Overview

A separate email only version (search mode set to 'EmailLookup') of this function is available to search for people using an email address. No other criteria may be used in conjunction with the email address. The sorting and pagination options, however, do apply.

1. Sorting Results: By default, the results from this service will be descending by order of relevancy (i.e. best matched results). Optionally, both the sort direction and a primary sort field can be designated on the request.

2. Pagination: Options exist to designate the maximum number of records per request, and the starting row number. The maximum number of records this feature will return on a single request is 10,000. The default page length is 25 records.

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 "Email Lookup" 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

Sample Request (EMailLookup)
GET https://direct.dnb.com/V6.1/organizations?findcontact=true&ContactEmailAddress=testemail@gormantest.com&SearchModeDescription=EmailLookup&InclusionDataDescription=IncludeNonMarketable
Authorization: <MyToken>

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.

Name Characteristics
ApplicationTransactionID string, up to 64 chars, Optional

A number assigned by the calling application to uniquely identify this request.

TransactionTimestamp dateTime, Optional

The date and time when this request was created. When the request is from an intermediary, such as a workflow manager or service bus, this is the date and time when the message was sent to the D&B function, i.e., the date and time when the xml document was created by the requesting intermediary.

SubmittingOfficeID string, up to 64 chars, Optional

A number that identifies the system or the software application from where this request originated. / A number used to uniquely identfy the D&B business segment or delivery channel from where this request originated.

ContactEmailAddress string, Optional

Text recording the electronic mail address used by a subject by which the subject can transmit and or receive text messages, links, and files electronically, typically via a network, like the Internet.

ExactLocationFindIndicator boolean, Optional
SortDirectionText SortDirectionEnum, Optional

Possible values: Ascending; Descending

CandidateMaximumQuantity integer, up to 6 digits, Optional
CandidatePerPageMaximumQuantity integer, less than or equal to 10000, Optional
CandidateDisplayStartSequenceNumber integer, less than or equal to 10000, Optional
SearchModeDescription SearchModeEnum, Optional

Text describing the nature of search to be applied during the search process.

Possible values: Basic; Advanced; EmailLookup

InclusionDataDescription-n InclusionContactDataEnum, Optional

Text that denotes an inclusion requirement that the Search process should apply to allow subjects from being returned as candidates. For example if the value is specified as Out of Business, then the Search process should return candidates that have an Operating Status which denotes Out Of Business.

Possible values: IncludeUndeliverableAddressSubject; IncludeOutofBusiness; IncludeIncompleteData; IncludeContactsOnlyWithDirectEmail; IncludeContactsOnlyWithDirectPhone; IncludeContactsOnlyWithDirectEmailOrDirectPhone; IncludeNonMarketableOnly; IncludeNonMarkeTable IncludeDelisted

SortBasisText SortBasisTextContactEnum, Optional

Possible values: DUNSNumber; FirstName; FullName; LastName; ManagementResponsibilityCodeText; OrganizationPrimaryName; ConsolidatedEmployeeQuantity; SalesRevenueAmount; Relevancy; JobRanking

CustomerReferenceText-n string, at least 1 char, up to 240 chars, Optional (up to 5x)
CustomerBillingEndorsementText string, at least 1 char, up to 240 chars, Optional

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.

REST (EntityList)
GET https://direct.dnb.com/V{version}/organizations?findcontact

Testing

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

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.

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

Sample Response (EMailLookup)
{"FindContactResponse": {
   "@ServiceVersionNumber": "6.1",
   "TransactionDetail":    {
      "ApplicationTransactionID": "Id-38a2865a47a64a5bc7d512a9-1",
      "ServiceTransactionID": "Id-38a2865a47a64a5bc7d512a9-1",
      "TransactionTimestamp": "2018-02-16T09:19:52"
   },
   "TransactionResult":    {
      "SeverityText": "Information",
      "ResultID": "CM000",
      "ResultText": "Success"
   },
   "FindContactResponseDetail":    {
      "CandidateMatchedQuantity": 1,
      "CandidateReturnedQuantity": 1,
      "FindCandidate": [      {
         "DUNSNumber": "804735132",
         "ContactID": {"$": "804735132-220656221"},
         "OrganizationPrimaryName": {"OrganizationName": {"$": "Gorman Manufacturing Company, Inc."}},
         "ConsolidatedEmployeeDetails": {"TotalEmployeeQuantity": 153},
         "NonMarketableReasonText": [ ],
         "ContactName":          {
            "FirstName": "Kevin",
            "MiddleName": "J",
            "LastName": "Hunt",
            "FullName": "Kevin J Hunt"
         },
         "PrincipalIdentificationNumberDetail": [         {
            "@DNBCodeValue": 24215,
            "@TypeText": "Professional Contact Identifier",
            "PrincipalIdentificationNumber": "220656221"
         }],
         "JobTitle": [{"JobTitleText": {"$": "Sec-treas"}}],
         "ManagementResponsibilityCodeText": [{"$": "Secretary"}],
         "ContactDataSourceDetail": {"NameInformationSourceName": {"$": "DNB"}},
         "DirectTelephoneInformationAvailableIndicator": false,
         "DirectEmailInformationAvailableIndicator": false,
         "ManufacturingIndicator": true,
         "DisplaySequence": 1
      }]
   }
}}
Name Characteristics
FindContactResponse Aggregate
FindContactResponse { TransactionDetail Aggregate, Required

Records information necessary to process a particular request. Examples of a request is the ordering of a product.

FindContactResponse { TransactionDetail { ApplicationTransactionID string, up to 64 chars, Optional

A number assigned by the calling application to uniquely identify this request.

FindContactResponse { TransactionDetail { ServiceTransactionID string, up to 64 chars, Required

A number assigned by the D&B service to uniquely identify this transaction.

FindContactResponse { TransactionDetail { TransactionTimestamp dateTime, Required

The date and time when this request was submitted or the date and time when the requesting intermediary, such as a workflow manager or service bus, sent the message to the D&B function, i.e., the date and time when the xml document was created by the requesting intermediary.

END: FindContactResponse } TransactionDetail /Aggregate
FindContactResponse { TransactionResult Aggregate, Required

Records the different outcomes of the transaction.

FindContactResponse { TransactionResult { SeverityText string, Required
FindContactResponse { TransactionResult { ResultID string, up to 32 chars, Required
FindContactResponse { TransactionResult { ResultText string, up to 512 chars, Optional
FindContactResponse { TransactionResult { ResultMessage Aggregate, Optional (Infinite)
FindContactResponse { TransactionResult { ResultMessage { ResultDescription string, up to 512 chars, Required

Text that describes the additional information regarding the outcome of the transaction.

END: FindContactResponse } TransactionResult } ResultMessage /Aggregate
END: FindContactResponse } TransactionResult /Aggregate
FindContactResponse { FindContactResponseDetail Aggregate, Optional

Records data relating to responses for search based on contact information. This may include details such as the total Number of contacts that matched the search criteria, name and address details of the contact etc.

FindContactResponse { FindContactResponseDetail { CandidateMatchedQuantity integer, Required

Total Number of Contacts that matched the Search Criteria.

FindContactResponse { FindContactResponseDetail { CandidateReturnedQuantity integer, Optional
FindContactResponse { FindContactResponseDetail { FindCandidate Aggregate, Optional (Infinite)

Records the details of the candidates that matched the search criteria.

FindContactResponse { FindContactResponseDetail { FindCandidate { DUNSNumber string, up to 15 chars Pattern: {([0-9a-zA-Z]*)}, Optional
FindContactResponse { FindContactResponseDetail { FindCandidate { OrganizationPrimaryName Aggregate, Optional
FindContactResponse { FindContactResponseDetail { FindCandidate { OrganizationPrimaryName { OrganizationName string, up to 256 chars, Required
END: FindContactResponse } FindContactResponseDetail } FindCandidate } OrganizationPrimaryName /Aggregate
FindContactResponse { FindContactResponseDetail { FindCandidate { TradeStyleName Aggregate, Optional (Infinite)
FindContactResponse { FindContactResponseDetail { FindCandidate { TradeStyleName { OrganizationName string, up to 256 chars, Required
END: FindContactResponse } FindContactResponseDetail } FindCandidate } TradeStyleName /Aggregate
FindContactResponse { FindContactResponseDetail { FindCandidate { ConsolidatedEmployeeDetails Aggregate, Optional

Records current employee data which includes all employees who are engaged in the operations of the legal entity (including employees located at branch locations) as well as all employees who are engaged in the operations of every direct descendant in its family tree (based on controlling interest), i.e., subsidiaries. Note: An organization which is classified by D&B as a branch" location cannot have a "Consolidated" employee figure."

FindContactResponse { FindContactResponseDetail { FindCandidate { ConsolidatedEmployeeDetails { TotalEmployeeQuantity long, Optional

A number that defines how many people are directly engaged and paid by the organization to perform or support its business operations.

END: FindContactResponse } FindContactResponseDetail } FindCandidate } ConsolidatedEmployeeDetails /Aggregate
FindContactResponse { FindContactResponseDetail { FindCandidate { NonMarketableReasonText string, up to 256 chars, Optional (Infinite)

Text specifying the reason why the subject's data is not considered marketable by D&B.

Possible values: 11027 [NIXIE]; 11024 [Out of business]; 11028 [De-listed]; 25837 [Insufficient Data]

FindContactResponse { FindContactResponseDetail { FindCandidate { ContactName Aggregate, Optional
FindContactResponse { FindContactResponseDetail { FindCandidate { ContactName { FirstName string, up to 64 chars, Optional

First name of the principal.

FindContactResponse { FindContactResponseDetail { FindCandidate { ContactName { MiddleName string, up to 64 chars, Optional

Middle name of the principal.

FindContactResponse { FindContactResponseDetail { FindCandidate { ContactName { LastName string, up to 64 chars, Optional

Last name of the principal.

FindContactResponse { FindContactResponseDetail { FindCandidate { ContactName { FullName string, up to 240 chars, Optional

Full Name of the principal.

FindContactResponse { FindContactResponseDetail { FindCandidate { ContactName { NameSuffix Aggregate, Optional (Infinite)
FindContactResponse { FindContactResponseDetail { FindCandidate { ContactName { NameSuffix { NameSuffixText string, up to 16 chars, Optional

A text identifying either a familial suffix to the principals name (E.g. Senior, Junior, III. ) or a professional/qualification suffix to the principals name (E.g. MD, FRICS, PhD etc.) or some other suffix to the principals name (E.g. Baronet, Retired.).

END: FindContactResponse } FindContactResponseDetail } FindCandidate } ContactName } NameSuffix /Aggregate
END: FindContactResponse } FindContactResponseDetail } FindCandidate } ContactName /Aggregate
FindContactResponse { FindContactResponseDetail { FindCandidate { PrincipalIdentificationNumberDetail Aggregate, Optional (Infinite)

An entry loop which can repeat multiple times to allow the recording of the identifiers assigned to the principal by D&B.

FindContactResponse { FindContactResponseDetail { FindCandidate { PrincipalIdentificationNumberDetail @DNBCodeValue integer, up to 7 digits, Attribute (1x)

Possible values: 24215

FindContactResponse { FindContactResponseDetail { FindCandidate { PrincipalIdentificationNumberDetail { PrincipalIdentificationNumber string, Optional

A number assigned by an external body or by D&B which either uniquely identifies or helps to identify an individual.

END: FindContactResponse } FindContactResponseDetail } FindCandidate } PrincipalIdentificationNumberDetail /Aggregate
FindContactResponse { FindContactResponseDetail { FindCandidate { JobTitle Aggregate, Optional (Infinite)

An entry loop which can repeat multiple times to allow the recording of the name used by the organization to describe this person's job, e.g., Leader Global Communication, Manager National Technical Support Center.

FindContactResponse { FindContactResponseDetail { FindCandidate { JobTitle { JobTitleText string, up to 3000 chars, Optional

Text that denotes a position held by the principal or manager.

END: FindContactResponse } FindContactResponseDetail } FindCandidate } JobTitle /Aggregate
FindContactResponse } FindContactResponseDetail } FindCandidate } ManagementResponsibilityCodeText string, up to 3000 chars, Optional
END: FindContactResponse } FindContactResponseDetail } FindCandidate } JobFunction string, Optional

Title assigned by D&B based on the routine set of tasks or activities undertaken by a person in that position.

END: FindContactResponse } FindContactResponseDetail } FindCandidate } JobRanking /Element
FindContactResponse } FindContactResponseDetail } FindCandidate } ContactDataSourceDetail /Aggregate
FindContactResponse } FindContactResponseDetail } FindCandidate } ContactDataSourceDetail } NameInformationSourceName string, up to 256 chars, Optional
FindContactResponse } FindContactResponseDetail } FindCandidate } ContactDataSourceDetail } EmailInformationSourceName string, up to 256 chars, Optional
FindContactResponse } FindContactResponseDetail } FindCandidate } ContactDataSourceDetail } TelephoneInformationSourceName string, up to 256 chars, Optional
END: FindContactResponse } FindContactResponseDetail } FindCandidate } ContactDataSourceDetail /Aggregate
FindContactResponse { FindContactResponseDetail { FindCandidate { DirectTelephoneInformationAvailableIndicator boolean, Optional

When 'true' indicates that the telephone information required to connect to the contact without the assistance of an operator is available. When turend OFF (set to 0), it indicates that the telephone information required to connect to the contact without the assistance of an operator is not available. When NULL or absent, it indicates that it is not known if the telephone information required to connect to the contact without the assistance of an operator is available.

FindContactResponse { FindContactResponseDetail { FindCandidate { DirectEmailInformationAvailableIndicator boolean, Optional

When 'true' indicates that the email information used to communicate solely with the contact is available. When turend OFF (set to 0), it indicates that the email information used to communicate solely with the contact is not available. When NULL or absent, it indicates that it is not known if the email information used to communicate solely with the contact is available.

FindContactResponse { FindContactResponseDetail { FindCandidate { ManufacturingIndicator boolean, Optional

When 'true' indicates that the subject has a manufacturing facility. When 'false' indicates that the subject does not have a manufacturing facility; however as this is the assumed condition there is no requirement to create this tag to represent this fact.

FindContactResponse { FindContactResponseDetail { FindCandidate { DisplaySequence integer, up to 5 digits, Optional
END: FindContactResponse } FindContactResponseDetail } FindCandidate /Aggregate
END: FindContactResponse } FindContactResponseDetail /Aggregate
END: FindContactResponse /Aggregate

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: CM002, CM003, CM004, CM005, CM007, CM012, CM018, CM022, 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]).

Search operations that involve pagination will only be recorded once -- upon the initial search request. Therefore, customer online usage (OLUS) reports will display a single entry for each unique combination of search criteria requested.

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.

Business Element Name Description
Company Principal First Name First name of the principal

PCM XPath: //FindCandidate/ ContactName/ FirstName

Company Principal Full Name Full Name of the principal

PCM XPath: //FindCandidate/ ContactName/ FullName

Company Principal Job Title

PCM XPath: //FindCandidate/ JobTitle/ JobTitleText

Company Principal Last Name Last name of the principal

PCM XPath: //FindCandidate/ ContactName/ LastName

Company Principal Name Prefix A text defining the correct form of address for this principal. E.g. Dr, Professor, Lord, etc.

PCM XPath: //FindCandidate/ ContactName/ NamePrefix/ NamePrefixText

Company Principal Name Suffix A text identifying either a familial suffix to the principals name (E.g. Senior, Junior, III. ) or a professional/qualification suffix to the principals name (E.g. MD, FRICS, PhD etc.) or some other suffix to the principals name (E.g. Baronet, Retired.).

PCM XPath: //FindCandidate/ ContactName/ NameSuffix/ NameSuffixText

Direct E-Mail Indicator Indicates if the contact's direct email information is available or not

PCM XPath: //FindCandidate/ DirectEmailInformationAvailableIndicator

Direct Phone Indicator Indicates if the contact's direct telephone number information is available or not

PCM XPath: //FindCandidate/ DirectTelephoneInformationAvailableIndicator

D-U-N-S Number The subject identifier under the Data Universal Numbering System.

PCM XPath: //FindCandidate/ DUNSNumber

Manufacturing Indicator ManufacturingIndicator denotes that the subject has a manufacturing facility.

PCM XPath: //FindCandidate/ ManufacturingIndicator

Non Marketable Reason Text

PCM XPath: //FindCandidate/ NonMarketableReasonText

Primary Business Name Text recording a name of this organization.

PCM XPath: //FindCandidate/ OrganizationPrimaryName/ OrganizationName

Principal Identification Number A number assigned by an external body or by D&B which either uniquely identifies or helps to identify the principal.

PCM XPath: //FindCandidate/ PrincipalIdentificationNumberDetail/ PrincipalIdentificationNumber

Total Employee Quantity

PCM XPath: //FindCandidate/ ConsolidatedEmployeeDetails/ TotalEmployeeQuantity

Trade Style Name Text recording tradestyle name (doing business as) of this organization.

PCM XPath: //FindCandidate/ TradeStyleName/ OrganizationName

The preceding list is not presented in the order, nor manner, in which the information is packaged and delivered via the D&B Direct API. Legend: [C] = may be included in a Custom Data product; [M] = may be referenced by the Monitoring process; [M+] = Monitored using an aggregate or attribute XPath.

Feature Notes

The results from this search will return principal identification numbers (Principal ID) that may be passed to the People feature to obtain additional information about individuals.