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.

Control the response by setting the Accept header to application/json or application/xml. The server will respond with the requested media type. If the header is omitted, the response will default to XML.

Set the Content-Type header to application/xml or application/json to indicate what type of data is sent.

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

Maximum return limits

The following return limits are in place:

Contractor movement => 3,000
Custom questionnaire => 5,000
Custom questionnaire submission => 10,000
Custom questionnaire submission answer => 10,000
Induction Holder => 1,000
Notification => 200
Staff movement => 5,000
Visitor event => 10,000

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

Limiting the response

It is recommended to always include a limit parameter when retrieving a list of data.

To limit the result include a GET parameter named limit with the desired amount (e.g. /staff/?limit=50). Ensure the provided value is below the maximum return limit.

Filtering

The q parameter allows for result filtering, and multiple filters can be used by separating them with a comma (e.g. q=id>5,status:active) The following filter-operators are supported:

Equals (:)
The ":" operator filters resources based on equality.

Example: q=status:active would match any records that have an active status

Starts With (%)
To use the starts-with operator (%), simply add the "%" character followed by the search string you want to filter by. For name fields both first and lastname will be matched.

Example: q=name%jo would match John Doe as well as Bill Johnson

Greater Than (>)
The greater than operator (>) is used for numerical or date fields. It allows you to retrieve records where the specified field value is greater than a given value.

Example: q=id>10 would match 11 but not 9

Less Than (<)
The less than (<) operator is used for numerical or date fields. It allows you to retrieve records where the specified field value is less than a given value.

Example: q=id<10 would match 9 but not 11

Wildcard (~)
The wildcard operator(~) allows to search for records that match a particular pattern or substring. It allows the user to search for records by using a wildcard character (%), representing zero or more characters in the search pattern.

Example: q=name~J%e would match Jake or Jesse

Sorting

When sorting records, the API provides the order parameter. By default, sorting is done in ascending order. If you want to sort a column in descending order, you can prefix the column name with a hyphen (-).

For example, to sort records in descending order by the id column, you would use ?order=-id.

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.