Introduction

This documentation describes the technical and functional use of the Accengage API.

This documentation can be separated in three main categories:

  1. General information includes the following sections: Generic headersError handling and Paginated requests, which describes generic information about the API calls;
  2. Access token, which is the entry point of the API;
  3. 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
{
 "errors": [
    {
    "label": "API_ERR_UNKNOW_ROUTE",
    "message": "Unsupported POST request : /v1/acess_token"
    }
  ]
}
The requested URL does not exist on the server. Here, you can see the URL is spelled wrong ("acess" instead of "access").
400
{
    "errors": [
        {
        "label": "API_ERR_FORMAT",
        "message": "Missing mandatory parameter `messageId`"
        },
        {
        "label": "API_ERR_FORMAT",
        "message": "Malformed application ID field `appId`"
        }
    ]
}
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.

Page GET parameter

When requesting for a list of resource, you may include the page GET parameter in the following form: ?page=Number

Pagination starts at 1. Values under 1 or above the last page return an empty set.

Example parameter in the request

http://api.accengage.com/v1/me/apps/partnerId/campaigns?page=4

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 may keep on querying the paginated request if a next link is present in this header.

Example header

Link: <http://api.accengage.com/v1/me/apps/partnerId/campaigns?page=1>; rel="first", <http://api.accengage.com/v1/me/apps/partnerId/campaigns?page=2>; 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": "http://api.accengage.com/v1/me/apps/partnerId/campaigns?page=1",
    "next": "http://api.accengage.com/v1/me/apps/partnerId/campaigns?page=2"
  }
}