Request

Authentication

To use the Revelian Assessment API, you will need a Client Identifier and an API Key. If you don’t have these already, please contact Revelian to arrange it.

You will need to include your Revelian Client Identifier and secret API key in every request to the Revelian Assessment API.

These details must be sent as HTTP Basic Authentication credentials:

Your API key provides access to the Revelian API so be sure to protect it.

Request Headers

Header Description
Authorization You must send your Client Identifier and API key as HTTP Basic Authentication credentials. (Required)
Accept Content-Types that are acceptable for the response. Only application/json is supported. Defaults to application/json if not supplied. (Optional)
Content-Type The MIME type of the body of the request (used with POST and PUT requests). Only application/json is supported. Defaults to application/json if not supplied. (Optional)

Example

Authorization: Basic ZDVlN2U3MzgtNWVhOC00MGMxLThhN2MtNTg0NWQyZWUyMWYzOlNlY3JldEFQSUtleQ==
Content-Type: application/json
Accept: application/json

Filters

A number of resources may be filtered by supplying supported query parameters to obtain results that match the supplied filter. Query parameter values must be URL encoded where appropriate.

Details of request filters are documented on each resource.

Example

An example of a position list request that filters the response to match positions with ‘title’ of ‘Position 1’

GET https://{BASE_URL}/positions?title=Position+1

Pagination

API resource endpoints that return multiple items will be limited to 100 items by default. However, the page size may be customized by supplying the limit query string parameter with a maximum allowable value of 1000 items per page.

Parameter Description
limit Non-negative number that defines maximum number of results to return in the response

Where appropriate, next and previous links will be returned in the response to support subsequent paging of items. See links in list resources for further information.

Example

An example of retrieving the first 5 positions for the organization

GET https://{BASE_URL}/positions?limit=5

Optional Fields

Where an endpoint returns a collection of resources the default behaviour is for the response to include only the id and links of each resource. However, most endpoints allow for one or more optional fields to be specified by supplying query parameters on the request. If optional fields are included in the request then these fields will be present on each resource in the response.

Parameter Description
fields A comma separated list of fields to be included on each resource in the response collection

Details of the supported optional fields are documented on each resource.

Example

An example request to retrieve assessments including the optional fields code and name

GET https://{BASE_URL}/assessments?fields=code,name
[
  {
    "id": "{AssessmentId}",
    "_links": [
      {
        "rel": "self",
        "href": "https://{BASE_URL}/assessments/{AssessmentId}"
      }
    ],
    "code": "RCAT",
    "name": "Cognitive Ability Test"
  },
  {
    "id": "{AssessmentId}",
    "_links": [
      {
        "rel": "self",
        "href": "https://{BASE_URL}/assessments/{AssessmentId}"
      }
    ],
    "code": "RVI",
    "name": "Revelian Values Inventory"
  }
  ...
]

Charsets

Requests must currently only contain characters from the Latin1 charset. Requests that contain characters outside of this range will be explicitly rejected with a 400 - Bad Request.

Rate Limits

Requests are currently rate limited to a maximum of 500 requests per minute with no more than 20 requests per second. Additionally, requests for Position Results are further restricted to a maximum of 30 requests per minute with no more than 2 requests in any given second.

If a request limit is exceeded, subsequent requests will be rejected with a 429 - Too Many Requests response code until the time frame for the breached limit expires.

These limits are per API Key and are not adjustable. Care should be taken by integrations to ensure that limits are not exceeded e.g. by queuing outbound requests, throttling the sending of these requests, and (if necessary) retrying the request should a 429 - Too Many Requests response be received.