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 assigned an API Key for your organization. Please contact support@ninthbrain.com for assistance.
To gain access to private data, we use an APIKey for authentication.
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. 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 --header "Authorization-Token: API_KEY_HERE"
wget https://api.ninthbrain.com/IndividualCertification/GetIndividualCertificationList?updatedSince=1/1/2016 --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. Ninth Brain provides a client library that can be integrated into any .NET application to ease development.
- certifications - List, update, and insert certifications
- individuals - List, update, and insert individuals
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 requestinvalid_parameters
(400 Bad Request) - Parameter missing or invalidunauthorized
(401 Unauthorized) - Unauthorized to access resourcerate_limit_exceeded
(403 Forbidden) - To many request the last hourinvalid_scope
(403 Forbidden) - Scope does not existinsufficient_scope
(403 Forbidden) - Don’t have the scope required to access resourcenot_found
(404 Not Found) - Resource was not foundnot_acceptable
(406 Not acceptable) - Unknown response formatinternal_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
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1342521939
{
"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 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.
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"
}
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."
}
}