DNA API

DNA API is built using REST principles which ensures predictable URLs that makes writing applications easy. This API follows HTTP rules, enabling a wide range of HTTP clients can be used to interact with the API. Every resource is exposed as a URL. The URL of each resource can be obtained by accessing the API base URL.

API protocols

The DNA API uses POST and GET requests to communicate and HTTP response codes with proper message to indicate status and errors. All responses come in standard JSON as well as XML format. The DNA API is served over HTTPS TLS v1.1+ to ensure data privacy; HTTP and HTTPS with TLS versions below 1.1 are not supported. All requests must include a Content-Type and the body must be valid JSON or XML.

API environments

• Sandbox: Stateful sandbox environment; use test credentials and build out and test your integration
  base URL: http://api-dnabehavior-mirror.azurewebsites.net
• Production: Production API environment; all requests are billed
  base URL: http://api-dnabehavior.azurewebsites.net

The Sandbox environment supports only test Items. All testing should be done in our Sandbox environments. All activity in the Production environment will be billed.

Getting Started

In order to utilize the DNA API, you will first need an API account (Username and Password) to get access token. In order to receive your account credentials, click here to make a request. Please include following details in your request:

• Organization Name
• An email (to be used as API Account Username)
• Preferred Language
• Origin of your client applications that will make requests to the Web API. We will whitelist your client application origin to enable your access.
• List of API endpoints you wish to access.
  • Natural Behavior
    • Submit Answers
    • Get Assessment Results
    • Get Hiring Data
  • Report
    • Get Report PDF

Once you are approved, you will receive an email on your email address with API account credentials.

You will receive back from DNA Behavior the following:

• Username and Password Credentials to the Sandbox and Production environments.
• IP Pack: (Required only for the POST Natural Behavior Submit Answer API)
  • This is a zipped folder you will receive via email and will include the question model for Natural Behavior.
  • In addition, if you are completing an integration that is not in English you may request for the Non-English Factor Names and Unique Styles for your language in this pack.

Get Access Token

All Web API endpoints are accessible only when valid access token is provided in Authorization header of HTTP request sent to Web API endpoints. You will require API Account credentials to get access token. Please make sure that you have received an email from us with your Web API Account credentials.

You need to post API account credentials based on details provided below to get access token.

URL: https://<API host domain>/Token
Request Type: POST
Content-Type: application/x-www-form-urlencoded
Request Parameters:
• username: <API account username>
• password: <API account password>
• grant_type: "password"

Please see sample Javascript/jQuery code to obtain access token.

var loginData = {
    grant_type: 'password',
    username: self.loginEmail(),
    password: self.loginPassword()
};
$.ajax({
    type: 'POST',
    url: '/Token',
    data: loginData
}).done(function (data) {
    self.user(data.userName);
    // Cache the access token in session storage.
    sessionStorage.setItem(tokenKey, data.access_token);
}).fail(showError);
                

If the request succeeds, the authorization server returns an access token in the response body. Notice that we store the token in session storage, to use later when sending requests to the API. Unlike some forms of authentication (such as cookie-based authentication), the browser will not automatically include the access token in subsequent requests. The application must do so explicitly.

HTTP Request:

POST https://<API host domain>/Token HTTP/1.1
Host: <API host domain>
User-Agent: Mozilla/5.0 (Windows NT 6.3; WOW64; rv:32.0) Gecko/20100101 Firefox/32.0
Accept: */*
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
X-Requested-With: XMLHttpRequest
Referer: https://<API host domain>/
Content-Length: 67
grant_type=password&username=user%40example.com&password=Password1!
                

You can see that the request contains the user's credentials. You must use HTTPS to provide transport layer security.

HTTP Response:

HTTP/1.1 200 OK
Content-Length: 669
Content-Type: application/json;charset=UTF-8
Server: Microsoft-IIS/10.0
Date: Fri, 01 July 2018 01:22:36 GMT
{
  "access_token":"imSXTs2OqSrGWzsFQhIXziFCO3rF...",
  "token_type":"bearer",
  "expires_in":1209599,
  "userName":"user@example.com",
  ".issued":"Fri, 01 July 2018 01:22:36 GMT",
  ".expires":"Fri, 01 July 2018 01:22:36 GMT"
}
                

Send an Authenticated Request

Now that we have a bearer token, we can make an authenticated request to the API. This is done by setting the Authorization header in the request.

HTTP request:

GET https://<API host domain>/API/NaturalBehavior/1 HTTP/1.1
Host: <API host domain>
User-Agent: Mozilla/5.0 (Windows NT 6.3; WOW64; rv:32.0) Gecko/20100101 Firefox/32.0
Accept: */*
Authorization: Bearer imSXTs2OqSrGWzsFQhIXziFCO3rF...
X-Requested-With: XMLHttpRequest
                

HTTP response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Server: Microsoft-IIS/10.0
Date: Fri, 01 July 2018 01:22:36 GMT
Content-Length: 26
"Hello, user@example.com"