Introduction
This documentation describes the technical and functional use of the Accengage API.
This documentation can be separated in three main categories:
- General information includes the following sections: Generic headers, Error handling and Paginated requests, which describes generic information about the API calls;
- Access token, which is the entry point of the API;
- Available requests, defined after the access token section.
The API routes defined in this documentation use, unless explicitly stated, url-encoded
formatting for query parameters (for GET
and DELETE
requests) and JSON
formatting for both body content (for POST
, PUT
requests) and return values. Don't forget to include the Content-type: application/json
header when posting a JSON body!
Postman Collection
If needed, here is our Postman Collection.
This gathers most of available API calls in this documentation. You can download it and import it in your Postman to test our API calls.
Accessing the API
The production API service is located at api.accengage.com
. API routes defined in this documentation present only the route path for
simplicity. Obviously, if you need to call an API route, you need to concatenate the protocol, the host and the route to form a full URL.
HTTP(S) load balancing does not support HTTP/1.1 100 Continue response. This might affect multipart POST.
To make your application(s) queryable via the API, please contact Accengage team.
They will then open access to our API on each of your environments. You may then configure the access per user.
To allow a user to access the API, first go the the Administration
/ Administration
menu.
Click the edit button next to the user row to access your application options.
On the page, search for the Managed application(s)
/ Application(s) gérée(s)
field and ensure your application is in the list.
Finally, at the bottom of the page, click the Generate a key
/ Générer une clé API
button to get your own API key (the one that will be included in the Accengage-Signature
header)!
Partner ID
After receiving an access token, you are granted access to the /v1/me/apps/...
routes. Beyond this point, the partner ID of the app must be included with subsequent requests (defined in the following form in this
documentation: /v1/me/apps/:partnerId/...
, where :partnerId
must be replaced with the app partner ID).
For example, for a given partner ID "12345678", the resulting API URL
will be /v1/me/apps/12345678/...
.
Each request must include two specific headers, Accengage-Signature and Accengage-Time:
Name | Content | Description |
---|---|---|
Accengage-Signature | SHA1 string of (raw POST body + API key + time) | Concatenation of the raw POST body (in case of a POST or PUT request; for a GET or DELETE), your API key and the actual time in seconds since epoch (either your local time or UTC time) |
Accengage-Time | time | Actual time in seconds since epoch (either your local time or UTC time) |
The time value corresponds to the number of elapsed seconds since the epoch.
An additional header must be included after getting an access token. See the section for more information.
When an error occurs on the server (either an unforeseeable error or an error resulting from user input), the server will return an array of errors in the following format:
[{
errors: [
{
label: "String"
message: "String"
}
]
}]
The label string defines the general type of error. The message string contains the actual content of the error. Note that the server will try, as much as possible, to go on with the processing even though an error has occurred, until it can't keep on going because of erroneous data.
Here are a few examples:
HTTP code | Body | Reason |
---|---|---|
404 |
|
The requested URL does not exist on the server. Here, you can see the URL is spelled wrong ("acess" instead of "access"). |
400 |
|
Here, there are several formatting errors in the given body of the request. Since it's easier for a developer to get all the formatting errors at the same time, they are returned as an array. Note that not all routes follow this rule, as keeping on processing a request beyond failure may be complex. |
Generic errors
There are a few generic errors that may happen, in case of a service error for example. The message given with these errors may change but the following HTTP code and label pairs will always define the corresponding error.
HTTP code | Label | Reason |
---|---|---|
400 | API_ERR_TOKEN | The given access token is invalid, a new one must be generated. See the section for more information. |
400 | API_ERR_SIGNATURE | The given Accengage-Signature header is missing, empty or invalid. |
401 | API_ERR_TOKEN | The access token has expired and must be regenerated. See the section for more information. |
403 | API_ERR_TOKEN | You are trying to access an API route that requires an access token. See the section for more information. |
403 | API_ERR_FORBIDDEN | You are trying to access an API route that you have no rights for. |
500 | API_ERR_DB | An error occurred when requesting the server database. This can be due either to an erroneous request (e.g. an SQL injection attempt, or a malformed input parameter) or to a service interruption on the database part. In either case, such an error should be reported to the administrators. |
500 | API_ERR_CACHE | Same as 500 API_ERR_DB, but with the cache system. Please report the error ASAP to an administrator, as such an error can lead to corrupted cache, affecting the entire server. |
500 | API_ERR_SERVICE | Same as 500 API_ERR_DB, but with another service. Please report the error to an administrator. |
500 | API_ERR_UTIL | Same as 500 API_ERR_DB, but with an internal utility. Please report the error to an administrator. |
500 | API_ERR_SUPPORT | An error occurred with the support account associated with the requests. Please report this error to an administrator. |
500 | API_ERR_UNKNOWN | An unhandled error occurred on the server, and could neither be caught nor saved. In this situation, please contact an administrator and provide him with the request information and the resulting error. |
Some listing requests are paginated, meaning you may need to call the API route several times in a row to get all the information. Except when explicitly specified, paginated requests return 100 elements per page, although this is not a golden rule.
When requesting a paginated API route, you may include a page GET parameter to request a specific portion of the information, and the response contains a Link header and a link body field for requesting subsequent information.
Paginated Requests
Link header
The Link header is formatted as follows:
Link: <link1>; rel="rel1", <link2>; rel="rel2", ...
with both link1 and link2 being URL string with pre-filled query parameters from the original request, and rel1 and rel2 one of the following:
- first: URL to access the first page of results
- prev: URL to access the previous page of results
- next: URL to access the next page of results
The first link is always present in the response. The prev link is present above page 1 (pages start at 1). The next link is present if there are (or, in corner cases, may be) resources left to list.
As a general rule, You should keep on querying the paginated request if a next link is present in this header even if the page is empty
.
Example header
Link: <https://api.accengage.com/v1/me/apps/partnerId/devices?lastOpen=2020-02-02>; rel="first", <https://api.accengage.com/v1/me/apps/partnerId/devices?lastOpen=2020-02-02&lastId=BF37FJYQNIAQAAASA4EAAEEAQCAAKGQGBDUAOEHIA4QLBLQV>; rel="next"
links body field
For simplicity, a link body field was added to the returned JSON body of the response.
{
links: {
first: "URL string"
prev: "URL string", optional
next: "URL string", optional
}
}
The same rules as the Link header apply.
Example body field
{
"links": {
"first": "https://api.accengage.com/v1/me/apps/partnerId/devices?lastOpen=2020-02-02",
"next": "https://api.accengage.com/v1/me/apps/partnerId/devices?lastOpen=2020-02-02&lastId=BF37FJYQNIAQAAASA4EAAEEAQCAAKGQGBDUAOEHIA4QLBLQV"
}
}
Page GET parameter
When requesting for a list of resource, you may include the page GET parameter in the following form: ?page=Number
If a next link is available, you must use the next link.
Pagination starts at 1. Values under 1 or above the last page return an empty set.
Example parameter in the request
https://api.accengage.com/v1/me/apps/partnerId/campaigns?page=4