Using the API

MRI OnLocation provides a RESTful API for managing data. Applications can manage functions by making HTTPS requests to URLs that represent those features.

Media types

The Accept and Content-Type HTTP headers can be used to describe the content being sent or requested within an HTTP request.

Set Accept to application/json if requesting a response in JSON.

When sending data, setting the Content-Type to application/xml tells the client that the data being sent in the request is XML.

Request types

Method Description Example
GET Retrieve information. GET requests must be safe and idempotent, meaning regardless of how many times it repeats with the same parameters, the results are the same. They can have side effects, but the user doesn't expect them, so they cannot be critical to the operation of the system. Requests can also be partial or conditional. Retrieve a staff member with an ID of 1: GET /staff/1
POST Request that the resource at the URI do something with the provided entity. Often POST is used to create a new entity, but it can also be used to update an entity. Create a new staff member: POST /staff
PUT Update an entity at a URI. PUT can update an existing one. A PUT request is idempotent. PUT replaces an existing entity. If only a subset of data elements are provided, the rest will be replaced with empty or null. Modify the staff profile with an ID of 1: PUT /staff/1
DELETE Request that a resource be removed; however, the resource does not have to be removed immediately. It could be an asynchronous or long-running request. Delete a staff member with an ID of 1: DELETE /staff/1
HEAD Retrieves the http-headers for a document rather than the document itself. Fetch photo metadata from the staff profile with an ID of 1: HEAD /staff/1/photo

Return limits

The following return limits are in place:

  • Employee movement => 5,000
  • Contractor movement => 3,000
  • Visitor event => 10,000
  • Custom questionnaire => 5,000
  • Custom questionnaire submission => 10,000
  • Custom questionnaire submission answer => 10,000
  • Notification => 200

If more records are required, you can aggregate the results by using pagination.

Pagination

The API uses a cursor/keyset pagination. To prevent skipping results due to relative ordering, requests should always use id column to order the result.

For example, to navigate through the entire employee list with 10 records at a time, start with the following query:

GET /staff/?order=id&limit=10

The next query would take the highest id of the response, and add a filter parameter. If the highest returned id was 100, this query would retrieve the following 10 items:

GET /staff/?order=id&limit=10&q=id>100

Status codes

Status codes indicate the result of the HTTP request:

  • 1XX - informational
  • 2XX - success
  • 3XX - redirection
  • 4XX - client error
  • 5XX - server error

Common status codes include:

  • 200 – The request has succeeded with output
  • 204 – The request has succeeded without output
  • 400 – Bad, request may be malformed or missing data
  • 403 – Forbidden, API key may be restricted to other endpoints
  • 404 – Resource not found
  • 405 – Method not allowed, e.g. DELETE on a non-deletable resource
  • 429 – Rate limited due to excessive requests
  • 500 – Server error, unable to process the request and we have been notified

Rate limits

This API is rate-limited. You can only query the API service up to 100 times per minute per API key.

We reserve the right to adjust the rate limit for given endpoints to provide a high-quality service for all clients.

If the rate limit is exceeded, OnLocation will respond with an HTTP 429 Too Many Requests response code and a body that details the reason for the rate limiter kicking in.

The response will also have a Retry-After header that tells you how many seconds to wait before retrying.