Amilia API documentation

The Amilia API allows an organization or partner to fetch data for reporting and integration. It also allows pushing information to Amilia. The API follows RESTful principles and returns JSON.

Get started

Organization

Partner

Versions

We recommend you use version 3 for either organizations or partners, as version 2 is deprecated.

Base URL

Through the documentation data that is meant to be replaced with your own values is surrounded by {curly brackets}. All the endpoints of a given api version share the same root URL (see version page). If using {rewriteUrl} (as is the case in v1 and v2) check in your Amilia account under Account - Options for the value of {rewriteUrl} you must use.

Required Headers

While the Amilia API generally doesn't require you to send specific headers with your request, we do recommend using the X-Amilia-Origin header to let us know who's calling our API for the purpose of identifying potential issues, notifying our partners of deprecations, or helping out with persistant issues. As a parameter, you could send your Amilia partner developer email address or your organization name.

You will find on our use cases page the step-by-step process of how to build an app with our API.

Types of authentication

There are two ways to be authorized with the Amilia API. We offer a bearer JWT-token with a person's identity, or an API key/secret pair for scope based authorization. The JWT token can be retrieved through our authentication API with a user's credentials, while an API key/secret pair is generated through the UI in the back-office under Account -> API Tokens (requires Api Token module to be enabled). The latter is useful in cases where you'd want someone to have access to a limited set of API endpoints, but not to the actual Amilia back-office.

JWT-Token

In order to acquire the JWT-Token you need to use the Amilia authentication endpoint and supply a valid username and password. The username and password should combined with a single colon (:) and passed in the header in the following format:

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
The result is a JWT token that expires after 1 year.
For more information on basic auth, see Basic Authentication Wikipedia

In our API, basic authentication is used solely with the call Authenticate the user in the API, in both organizations and partners as well as the corresponding call in v2.

The JWT token can then be used to authorize for the API endpoints by passing it as Authorziation:

Bearer eyJ0eXAiOiJKV1QiLC.eyJ...qsmw (real token is quite long)

API Key/Secret pair

As an alternative to the JWT token, you can use an API Key/Secret pair given out by an organization administrator from the UI under Account -> Api Tokens in the Amilia back-office. The key and secret have a designated scope, have a specific expiration date, and can be revoked by the administrator at any time. This allows more control over access to the organization's data. The API key/secret has to be passed to the API with the X-Amilia-ApiKey and X-Amilia-ApiSecret headers.

With Postman

There are two steps to authenticating with Postman:

  • Getting a token using basic auth.
  • Making calls using the token or key/secret pair.

1) Getting a token

Enter the authorization request url (see Authentication in version page).
In the Authorization tab, choose type 'Basic Auth' and enter your username (your.address@email.com) and password, as shown in the image below.
Send the request. The response will be a token. You will have to use this token with all the other calls.

Authenticating with Postman

2a) Making a call using the token.

Set Authorization type to 'Bearer Token' in the header and enter the previously obtained token.
Send the request. You should get a response like the one below, shown for the Get keywords call.

Making a call with Postman

2b) Making a call using the API Key/Secret pair.

Add the key and secret with two new header fields: X-Amilia-ApiKey and X-Amilia-ApiSecret (case insensitive).

Making a call with Postman

If you set up the token for the entire collection, you can have each future request inherit the authentication method and save yourself the effort of adding these settings each time.

Similarly, you can set the pre-request script for the entire collection to add the origin header:

pm.request.headers.add({key: 'X-Amilia-Origin', value: '<email-address>' })

Partners and organizations

The main difference between partners and organizations is the amount of information from the API you have access to, which is related to authorization.

Partners

Amilia Partners get access to specific API endpoints (marked [Partner]) in order to provide unique services to organizations accross the board. In order to become an Amilia parter, you can contact Amilia's API team at api@amilia.com.

Organizations

Calls that are accessible to organizations are marked with a [Must be authorized for org] label. For organizations, most endpoints require authentication, and they are marked with a [Must be authenticated] label. To have access to these endpoints you need a valid token or api/key pair.

The labels [Partner] and [Must be authorized for org] are mutually exclusive.

Getting a valid Amilia account (partners and organizations)

For the JWT token authorization you need a valid Amilia account with permissions on the organization you want to access the API of. The account needs a valid email as username, and the email address must have a mailbox. In order to avoid problems with staff changes within the organization, we recommend using a dedicated API user account that is not linked to a specific person, but that is created specifically to access the API, such as amilia-api@example.com.
However, in order to better separate access to API endpoints and access to the Amilia back-office, we recommend you create an API Key/Secret pair for your API access instead.

Error codeError name - Meaning
400Bad Request - Parameters or their format are invalid
401Unauthorized - Token is invalid
403Forbidden - User is not authorized to perform this operation
404Not Found - Entity was not found
422Unprocessable entity - Validation error
429Too Many Requests - Maximum number of calls per second exceeded

If you contact us for an error, you can provide the TransactionId in the response:

Typical error response

You can only do a certain number of calls per second to our API for one given IP address. Our default value is set to 100 calls per second. Do not worry if your web page makes Ajax calls from the client's browser: this limit will most probably never be met. If you ever do hit this limit, you will receive an HTTP status code 429. You will know that you hit our limit and must wait a little before making your next calls.

Amilia also provides webhooks, which can be used to send a payload to an endpoint, once an event happens in Amilia, for example an activity registration, or a facility booking. The payload can be then used to trigger a workflow, either through the receiving app's API, or an intermediary like Zapier.

Contact us at api@amilia.com to discuss how webhooks could be used within your app!