Elorus REST API

The Elorus developer API enables external applications access the Elorus platform and update organization data programmatically. For example, you may use the API to:

This portal provides documentation for developers, as well as an interactive console to query the API.

Accessing the API

You may access the API through https://api.elorus.com/v{VERSION}/, where {version} corresponds to the API version number. The current version is 1.0, meaning the API is available at https://api.elorus.com/v1.0/.

The API specification may well change as the application grows. We will maintain separate API versions to ensure your applications will keep working even after major upgrades.

Authentication / Authorization

To connect to the API one must be registered with Elorus and own an API key. To obtain your key you must contact the Elorus support team and generate it for you. Afterwards you can always visit your account settings page and get your API key.

The API key must be sent on every request through the standard Authorization HTTP header:

Authorization: Token CaBd3257h8jhgf

In the event of an unauthenticated request, the Elorus API returns a HTTP 401 response.


Organizations are a core concept in Elorus. Each user is assigned a role within an organization / company, depending on which he may or may not be able to perform actions. To specify the organization on which you wish to operate, you must provide the custom X-Elorus-Organization HTTP header:

X-Elorus-Organization: 128759403567807

Since each API key represents a user, the ability to retrieve, update or delete data depends on the user role within the specified organization.

In the event of an unauthorized request, the Elorus API returns a HTTP 403 response. Additional details about the error may be provided within the response body.


Throughout this documentation we assume the X-Elorus-Organization is always sent on every request. In the event of a non-organization specific action, we explicitly state that you may skip this header.


Development guidelines

To start developing with the Elorus API you need to sign up for a free account. The best way to try out Elorus and test your code is through the demo organizations at zero cost. While developing your application, it is recommended to restrict all API requests only to demo organizations by providing the X-Elorus-Demo HTTP header:

X-Elorus-Demo: true

This way Elorus will enforce a demo organization, preventing accidental data loss on production organizations.

Demo organizations

Demo organizations are a special form of organizations, suitable for reviewing Elorus and experimenting with the API. Within a demo organization:


Currently demo organizations are created only upon request. Contact the Elorus support team to get started with your demo organization.


Call rate limits

Each user has a hard limit of 1000 API calls per day. At the same time, a user may not perform more than 60 requests per minute. If an API call e these limits, you will receive an HTTP 429 response. The accompanying error message will look like "Request was throttled. Expected available in 60.0 seconds".

Localization

Language

The English language is used throughout the Elorus API, regardless of the authenticated user's language preference. The English locale conventions are also used for decimal numbers and dates:

Timezone

The UTC timezone is used throughout the Elorus API. Datetime values are formatted in the standard ISO format.

Responses

Upon successful call you will receive a HTTP 200 or HTTP 204 response, depending on whether additional information is attached to the body.

Upon unsuccessful call you may receive a few different status codes, depending on the nature of the error:

The response content type is application/json for most operations, unless otherwise is explicitly stated.

Paging - Filtering

In some cases (mainly the list end-points) you may use filters to restrict the results. These are query parameters (part of the URL) and are documented in the respective sections. List end-points return the results paginated in sets of 100s. You may use use the page query parameter to control the page. For example, to get the second page of the clients you may use the following URL:

https://api.elorus.com/v{VERSION}/contacts/?page=2&type=client

API v1.0 (BETA) documentation