Technical Basics

Basics

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

All resource paths are relative to the API-endpoint.

Create an application

To use the API, you need to be assigned an API Key for your organization. Please contact support@ninthbrain.com for assistance.

Authorization

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

Versions

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.

Including APIKey in request

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

Authorization-Token: 8ESOtm65KvmJABUE1kbhvqyk5akV1uTRNu93p0zN2UX3WwRcObs9qkTBtklRXDS

Interacting With the API

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.

Scopes

Available scopes
  • certifications - List, update, and insert certifications
  • individuals - List, update, and insert individuals
Example

Client errors

When a client side error occur you will get appropriete 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
  • internal_server_error (500 Internal Server Error) - An unexpected error occured while processing the request
Example request
GET https://api.ninthbrain.com/Certifications/NotExistingMethod
Response
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=utf-8
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1342521939

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

Response Formats

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

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

Rate limiting

All responses are rate limited. Four additional headers are sent in all responses:

    X-RateLimit-Limit: 1000
    X-RateLimit-Remaining: 999
    X-RateLimit-Reset: 1342521939

X-RateLimit-Limit - Current rate limit.
X-RateLimit-Remaining - Requests left during the current period.
X-RateLimit-Reset - When your period ends you get new request. It’s a unix timestamp.

When you exceed your rate limit, a rate_limit_exceeded error will be returned on all rate limited resources. Your requests are reset every hour.

Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8

{
  "hourly_limit": 1000,
  "remaining_hits": 986,
  "current_hits": 14,
  "reset_time_in_seconds": 1342521939,
  "reset_time": "Tue, 17 Jul 2012 10:45:39 +0000 GMT"
}

Errors

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."
  }
}