Authentication Process

Before D&B Direct API services can be invoked, the credentials must be activated. Instructions and a link for activating username/password combinations will be included in an email sent upon completion of the registration process. If you do not receive an email, or unable to locate it, please contact the D&B support team for assistance (and specify if this a production, trial or sandbox related issue).

The system will generate a unique username for accounts created after December 6, 2013. Prior to that date, the customer-supplied email address was used as the username. No change is required for existing credentials.

Most of the D&B Direct products and features require contractual entitlement prior to production (and trial) environment access. Please refer to the data layer entitlement page for more details.

SOAP Authentication

All D&B Direct API services require that a valid username and password be provided in the SOAP header with each call to an operation. The 2.0 services do not require that an API key be supplied.

If the credentials are valid and the associated account is entitled to access the product or feature, the request will be processed. If the authentication process fails, an error response code will be returned. The security related response codes are prefixed with "SC."

Sample Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:com="http://services.dnb.com/CompanyServiceV2.0">
   <soapenv:Header>
      <wsse:Security soapenv:mustUnderstand="0" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
         <wsse:UsernameToken wsu:Id="UsernameToken-11">
            <wsse:Username>MyUsername</wsse:Username>
            <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">MyPassword</wsse:Password>
         </wsse:UsernameToken>
      </wsse:Security>   
   </soapenv:Header>
   <soapenv:Body>
		<!--Request Body as per the service schema-->
   </soapenv:Body>
</soapenv:Envelope>

Response - Invalid Credentials

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <com:MatchResponse ServiceVersionNumber="4.0" xmlns:com="http://services.dnb.com/CompanyServiceV2.0">
         <TransactionDetail>
            <ApplicationTransactionID>Id-b118ae275255a7cf0cfb742e</ApplicationTransactionID>
            <ServiceTransactionID>Id-b118ae275255a7cf0cfb742e</ServiceTransactionID>
            <TransactionTimestamp>2013-10-09T15:00:31</TransactionTimestamp>
         </TransactionDetail>
         <TransactionResult>
            <SeverityText>Error</SeverityText>
            <ResultID>SC001</ResultID>
            <ResultText>Your user credentials are invalid. Please contact your D&amp;B Representative or your local Customer Service Center.</ResultText>
         </TransactionResult>
      </com:MatchResponse>
   </soapenv:Body>
</soapenv:Envelope>

REST Authentication

Implementation of D&B Direct API services using REST methodology involves obtaining an Authentication Token, that is then submitted with subsequent requests during a particular session (up to eight hours).

Secure access to D&B Direct services is managed through the use of an Authentication Token, which can be obtained by sending an HTTP POST request to Authentication Service URL, passing a valid username and password in the HTTP header. The 2.0 services do not require that an API key be supplied. If the user credentials are valid, an Authentication Token (valid for eight hours) will be returned back in the Authorization tag in the HTTP header of the response.

Once an Authentication Token is obtained, it should be embedded in the HTTP header of all subsequent requests. If the Authentication Token is valid and the user is entitled to access the product or feature being requested, the service will be processed and requested information returned as a JSON object. If the Authentication Token is invalid, an error code will be returned in the JSON response.

NOTE: For an explanation of the D&B Direct REST implementation, refer to our JSON response guidelines.

Sample Request - Get New Token

POST https://maxcvservices.dnb.com/rest/Authentication
x-dnb-user: MyUsername
x-dnb-pwd: MyPassword

A {version} parameter is not required when initiating a request to the Authentication service.

Response - Success

HTTP/1.1 200 OK
Date: Wed, 09 Oct 2013 18:47:22 GMT
Authorization: <MyToken>
x-dnb-user: MyUsername
x-dnb-pwd: MyPassword

Response - Failed

HTTP/1.1 401 ERROR
Date: Wed, 09 Oct 2013 18:51:11 GMT
Authorization: INVALID CREDENTIALS
x-dnb-user: MyUsername
x-dnb-pwd: MyPassword

Sample Request - Invoke Operation with Token

GET https://maxcvservices.dnb.com/V4.0/organizations?CountryISOAlpha2Code=US&SubjectName=GORMAN%20MANUFACTURING&match=true&MatchTypeText=Advanced&TerritoryName=CA
Authorization: <MyToken>

Response - Expired Authentication Token

HTTP/1.1 401 UNAUTHORIZED
Date: Thu, 10 Oct 2013 14:55:19 GMT
Authorization: <MyToken>
Content-Type: application/json
Content-Encoding: gzip

{"MatchResponse": {
  "TransactionDetail":   {
    "ApplicationTransactionID": "REST",
    "ServiceTransactionID": "Id-c04bbdff5256bfd70a7b742e",
    "TransactionTimestamp": "2013-10-10T10:55:19"
  },
  "TransactionResult":   {
    "SeverityText": "Error",
    "ResultID": "SC001",
    "ResultText": "Your user credentials are invalid. Please contact your D&B Representative or your local Customer Service Center."
  }
}}
Back to Top