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 Amilia doesn't require you to send specific headers with your request (yet), 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

Authentication can be of several types. In this API we use basic authentication and token.

Basic authentication

In basic authentication, the users authenticate themselves by providing a username and password. The username and password are then encapsulated in base64, an encoding scheme. They are not encrypted. 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.

Token authentication

All our calls except Authenticate the user in the API (from organizations v3 and partners v3) require a token authentication. As the name says, this type of authentication uses a token. A token is a unique string randomly generated from a first time user's username and password in order to fetch a specific resource for a limited time period. It is also encapsulated in base64, and not encrypted either. The main difference between basic auth and token auth is the randomness the token adds.
The token provides not only authentication but also authorization. Authentication and authorization, while often used interchangeably, provide distinct information: authentication proves identity while authorization proves access rights.

With Postman

There are two steps to authenticating with Postman:

  • Getting a token using basic auth.
  • Making calls using the token.

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

2) 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

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

Here we assume the partner provides for an organization (that we'll call the client organization) and that the organization in question is the client of both the partner and Amilia. If you are a technology partner, you can ask your client organization to add the developer who acts as the API user to their organization with administrator access, as explained in section 'Getting a valid Amilia account' below. This will grant you API access to certain calls. These calls are marked with a [Partner] label. All of the partner calls require authentication. Note that the partner calls do not show the label [Must be authenticated] as the requirement to be authenticated is implicit for all partner calls.

Organizations

Calls that are only accessible to organizations are marked with a [Must be authorized for org] label. For organizations, only some endpoints require authentication, and they are marked with a [Must be authenticated] label. To have access to these endpoints you need a valid Amilia account (see below) and a token.

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

Getting a valid Amilia account (partners and organizations)

The account you create 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.

Follow the steps to add a new administrator and grant access to the API user.

Verify the email address by clicking on the confirmation link in an email you will receive from Amilia.

Make that account an administrator of the organization and give it the "Level 2 (Manager)" access level.

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!