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 headers, Error 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:

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:

{
 "errors": [
    {
    "label": "API_ERR_UNKNOW_ROUTE",
    "message": "Unsupported POST request : /v1/acess_token"
    }
  ]
}

{
    "errors": [
        {
        "label": "API_ERR_FORMAT",
        "message": "Missing mandatory parameter `messageId`"
        },
        {
        "label": "API_ERR_FORMAT",
        "message": "Malformed application ID field `appId`"
        }
    ]
}

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.

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