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 the 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: https://api-sandbox.dnabehavior.org
• Production: Production API environment; all requests are billed
  base URL: https://api.dnabehavior.biz

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 address (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 PDF

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

You will receive back the following details from DNA Behavior:

• Username and Password Credentials to the Sandbox and Production environments.
• IP Pack: (Required only for the POST Natural Behavior Submit Answers 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 the valid access token is provided in Authorization header of the 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://<base URL>/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.

$.ajax({
    type: "POST",
    url: "https://<base URL>/Token",
    data: {
             username: "user@example.com",
             password: "Password1!",
             grant_type: "password"
         },
    success: function (data) { localStorage.setItem('access_token', data.access_token); },
    error: function (jqXHR, textStatus, errorThrown) { alert(jqXHR.responseText || textStatus); }
    });
                

If the request succeeds, the authorization server returns an access token in the response body. Notice that we store the token in browser's local storage, to use later when sending requests to the API.

HTTP Request:

POST https://<base URL>/Token HTTP/1.1
Host: <base URL>
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://<base URL>/
Content-Length: 67
grant_type=password&username=user@example.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: Mon, 01 October 2018 12:00:00 GMT
{
  "access_token":"imSXTs2OqSrGWzsFQhIXziFCO3rF...",
  "token_type":"bearer",
  "expires_in":1209599,
  "userName":"user@example.com",
  ".issued":"Mon, 01 October 2018 12:00:00 GMT",
  ".expires":"Mon, 08 October 2018 12:00:00 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://<base URL>/API/NaturalBehavior HTTP/1.1
Host: <base URL>
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"