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.

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 and 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

With jQuery AJAX

The two steps to authenticating with jQuery AJAX are the same as with Postman: getting a token and making calls using the token.

1) Getting a token

Open the developer console (press F12 in Chrome and Firefox).

Enter the authorization request url with a custom header. It will look like this:

var request = $.ajax({
    url: URL,
    type: "GET",
    headers: { 'Authorization': 'Basic ' + btoa("you@email.com" + ":" + "your_password") } 
});      

where the value of URL depends on the version according to the table below.

VersionURL
v3https://www.amilia.com/api/v3/authenticate
v2 & v1https://www.amilia.com/PublicApi/en/Authentication/Login

Send the request. The response will contain a responseJSON object which will contain a token. You can access it as request.responseJSON.Token in the console.

You will have to use this token with all the other calls.


2) Making a call using the token.

Send the call in the format below:

$.ajax({
    url: URL,
    type: "GET",
    headers: { 'Authorization' : 'Bearer ' + TOKEN } 
});       

where the previously obtained TOKEN is a string and URL depends on the version according to the table below.

VersionURL
v3https://www.amilia.com/api/v3/en/Keywords
v2 & v1https://www.amilia.com/PublicApi/usa-amilia-group/en/Programs

This call should yield a response.

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 (see How to authenticate with jQuery AJAX).

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 amiliaapi@acme.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.

Only authorized websites can make calls to the API. This prevents cross-domain attacks.
You can list authorized URLs at https://www.amilia.com/StoreAdmin/en/{rewriteUrl}/EmbedStore, where {rewriteUrl} has the value you set in your Amilia account under Account - Options.

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.