Technical Basics

• API-endpoint: https://api.ninthbrain.com

All resource paths are relative to the API-endpoint.

• Date Format: The date format used by the API is the Standard ISO 8601 format. Please see the following link for more information: https://en.wikipedia.org/wiki/ISO_8601

To use the API, you need to be generate an API Key for your organization. As a Site Director, in NBS, visit the API Keys area to generate your first API Key. Please contact support@ninthbrain.com for assistance.

To gain access to private data, we use an APIKey for authentication.

The current version of the API is v2.0. You must specify the version as part of your request URI using the api-version=2.0 parameter. If a parameter for the version parameter is not included, it will default to v1.0. Please note that v1.0 is depreciated and may not be supported in the future.

Include the Authorization-Token in the header when accessing the resources to authorize.

Authorization-Token: 8ESOtm65KvmJABUE1kbhvqyk5akV1uTRNu93p0zN2UX3WwRcObs9qkTBtklRXDS

To interact with the API, Ninth Brain recommends using a client like Postman or Insomnia.

Within the client enter the appropriate URL to the API method you want to retrieve in the URL box. For instance, to retrieve a list of all individual certifications updated since January 1, 2016, use https://api.ninthbrain.com/IndividualCertification/GetIndividualCertificationList?updatedSince=1/1/2016&api-version=2.0. For retrieving data, make sure the dropdown to the left of the URL is set to “Get”. Next, in the Headers tab, enter a key of “Authorization-Token”. The value is then your API Key.

Click Send and you will receive the data back in JSON format.

The API can be also interacted with using something as simple as a curl or wget call. (Note: Windows systems do not come bundled with curl or wget so they will have to be obtained manually: wget curl

curl https://api.ninthbrain.com/IndividualCertification/GetIndividualCertificationList?updatedSince=1/1/2016&api-version=2.0 --header "Authorization-Token: API_KEY_HERE"
wget https://api.ninthbrain.com/IndividualCertification/GetIndividualCertificationList?updatedSince=1/1/2016&api-version=2.0 --header "Authorization-Token: API_KEY_HERE"

Please keep in mind that these methods of interacting are really only useful for testing the API and familiarizing yourself with the data and format available. In order to get the most use out of it, the API will have to be programmed into your system. There are infinite ways to do this depending on the environment you are working with.

• certifications - List, update, and insert certifications
• individuals - List, update, and insert individuals

When a client side error occur you will get appropriate HTTP status code and a body with information about the error.

• invalid_request (400 Bad Request) - Not a valid request
• invalid_parameters (400 Bad Request) - Parameter missing or invalid
• unauthorized (401 Unauthorized) - Unauthorized to access resource
• rate_limit_exceeded (403 Forbidden) - To many request the last hour
• invalid_scope (403 Forbidden) - Scope does not exist
• insufficient_scope (403 Forbidden) - Don’t have the scope required to access resource
• not_found (404 Not Found) - Resource was not found
• not_acceptable (406 Not acceptable) - Unknown response format
• too_many_requests (429 Too Many Requests) - Too Many Requests received. See Rate Limiting for more info.
• internal_server_error (500 Internal Server Error) - An unexpected error occured while processing the request

GET https://api.ninthbrain.com/Certifications/NotExistingMethod

HTTP/1.1 404 Not Found
Content-Type: application/json;charset=utf-8

{
  "error": "not_found",
  "error_message": "The resource was not found"
}

• application/json - .json ( Default )
• text/xml - .xml

You can specify another response format through the Accept header as specified in rfc2616

All requests are rate limited. You are limited to 100 requests per 1 minute interval. If you reach this threshold you will receive a 429 response code. Rate limiting resets after 1 minute.

When the Ninth Brain API returns error messages, it does so in your requested format. For example, an error from a JSON method might look like this:

{
  "Message": "An error occurred processing the method.",
  "Errors": {
    "Error": "The First Name cannot be empty."
  }
}