Skip to end of metadata
Go to start of metadata

 

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/....


Generic headers

Each request must include two specific headers, Accengage-Signature and Accengage-Time:

NameContentDescription
Accengage-SignatureSHA1 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-TimetimeActual 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 Access token section for more information.


Error handling

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:

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 codeBodyReason
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 codeLabelReason
400API_ERR_TOKENThe given access token is invalid, a new one must be generated. See the Access token section for more information.
400API_ERR_SIGNATUREThe given Accengage-Signature header is missing, empty or invalid.
401API_ERR_TOKENThe access token has expired and must be regenerated. See the Access token section for more information.
403API_ERR_TOKENYou are trying to access an API route that requires an access token. See the Access token section for more information.
403API_ERR_FORBIDDENYou are trying to access an API route that you have no rights for.
500API_ERR_DBAn 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.
500API_ERR_CACHESame 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.
500API_ERR_SERVICESame as 500 API_ERR_DB, but with another service. Please report the error to an administrator.
500API_ERR_UTILSame as 500 API_ERR_DB, but with an internal utility. Please report the error to an administrator.
500API_ERR_SUPPORTAn error occurred with the support account associated with the requests. Please report this error to an administrator.
500API_ERR_UNKNOWNAn 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.


Paginated requests

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:

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

Example parameter in the request

Link header

The Link header is formatted as follows:

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:

  • firstURL to access the first page of results
  • prevURL 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

links body field

For simplicity, a link body field was added to the returned JSON body of the response.

The same rules as the Link header apply.

Example body field


Access token

Generates an access token for accessing the rest of the API. This call is mandatory for accessing other routes.

 

This route generates a unique token that must be included in all headers of subsequent API calls in the following way:

This token will expire after 24h. You can automate its regeneration if a 401 API_ERR_TOKEN  error is returned.

Operations

POST

/v1/access_token

ParameterModel
headers

Generic Accengage headers

body
Access token
Response
CodeReasonModelHeaders

200

The access token has been generated successfully.
400The given body does not correspond to any known access token format.
404We could not find the given user e-mail in the database.
500An unhandled error has occured.See generic errors

Examples

RequestCodeResponseReason

POST /v1/access_token

200

Both the token_type and access_token are used to generate the Authorization header defined before, in the following manner:

Authorization: ${token_type} ${access_token}

POST /v1/access_token

404
Here, the user could not be found, so no access token has been generated.

Since an access token is given per user and can expire, you cannot use the same access token for multiple users or store it. When requesting the server, you should always handle the case where the access token expired and must be regenerated.


Me

Returns the "Welcome" in text/plain. It is used for new developers to ensure they have access to the API. Calling this route requires having fetched an access token.

Operations

GET

/v1/me

ParameterModel
No parameters
Response
CodeReasonModelHeaders

200

OK

"Welcome"

This API call cannot fail

Examples

RequestCodeResponseReason

GET /v1/me

200

"Welcome"

 


Campaigns

List

This API call returns the full list of campaigns associated with the given partner ID.

Please note that this request is paginated. See Paginated requests for more information.

Operations

GET

/v1/me/apps/:partnerId/campaigns

ParameterModel
headersGeneric Accengage headers
URL

See Partner ID for the partnerId URL parameter

query

See query parameters in Paginated requests.

Response
CodeReasonModelHeaders

200

OK

Also includes links of paginated requests, see link response body field in Paginated requests

See Link response headers in Paginated requests.

See Generic errors for all-purpose errors

Examples

RequestCodeResponseReason

GET /v1/me/apps/myPartnerId/campaigns

200

with headers:

Returns the beginning of the campaigns list, orderered by ascending campaign ID.

Note the first and next links, enabling to pass through complete campaign list.

GET /v1/me/apps/myPartnerId/campaigns?page=2200

with headers:

This time, returns the next campaigns. Usually, listing API routes are capped to 100 items per page.

Create

This API call is used for creating campaigns.

Operations

POST

/v1/me/apps/:partnerId/campaigns

ParameterModel
headersGeneric Accengage headers
URL

See Partner ID for the partnerId URL parameter

body
Campaign
Response
CodeReasonModelHeaders

200

OK

See Generic errors for all-purpose errors

Dates are defined using the ISO 8601 format described in RFC 3339.

Examples

RequestCodeResponseReason

POST /v1/me/apps/myPartnerId/campaigns

200

The campaign has been successfully created, and the API call returned the technical ID of the campaign, which may be used in getting, updating and deleting the campaign.

Get

This API call returns the details of a specific campaign.

Operations

GET

/v1/me/apps/:partnerId/campaigns/:campaignId

ParameterModel
HeadersGeneric Accengage headers
URL

See Partner ID for the partnerId URL parameter

Response
CodeReasonModelHeaders

200

OK

400The given campaign ID does not comply with the requested format (must be a number)
404Campaign with given ID could not be found
See Generic errors for all-purpose errors

Examples

RequestCodeResponseReason

GET /v1/me/apps/myPartnerId/campaigns/91

200

The campaign with ID 91 has been successfully retrieved.

GET /v1/me/apps/myPartnerId/campaigns/cmp

400
"cmp" is not a valid campaign ID, the server refuses to go on with the request.

Update

This API call is used for updating an existing campaign.

Operations

PUT

/v1/me/apps/:partnerId/campaigns/:campaignId

ParameterModel
headers

Generic Accengage headers

URL

See Partner ID for the partnerId URL parameter

body
Campaign
Response
CodeReasonModelHeaders

200

OK

400Much like for the Campaign GET request, happens if the campaign ID given in the request does not match the expected format
See Generic errors for all-purpose errors

Dates are defined using the ISO 8601 format described in RFC 3339.

Examples

RequestCodeResponseReason

PUT /v1/me/apps/myPartnerId/campaigns/91

200

The campaign has been successfully updated.

Delete

This API calls is used for permanently deleting a campaign.

Operations

DELETE

/v1/me/apps/:partnerId/campaigns/:campaignId

ParameterModel
headersGeneric Accengage headers
URL

See Partner ID for the partnerId URL parameter

Response
CodeReasonModelHeaders

200

OK

400Much like for the Campaign GET request, happens if the campaign ID given in the request does not match the expected format
404Resource not found; note that this can also mean you have no access over the specified campaign (it may belong to another app and will therefore not be found by the server in the list of campaigns that you possess)

This request is not idempotent, as it may return a 404 error in case the resource is not found.

Examples

RequestCodeResponseReason

DELETE /v1/me/apps/myPartnerId/campaigns/91

200

The campaign with ID 91 was successfully deleted.

DELETE /v1/me/apps/myPartnerId/campaigns/123

404
In this case, since the campaign with ID 123 does not exist, the server returns a 404. This API call is not idempotent to ensure transparent visibility over the actions taken by the server.


Messages

List

This API call is used for listing messages associated with the given partner ID.

Please note that this request is paginated. See Paginated requests for more information.

Operations

GET

/v1/me/apps/:partnerId/messages

ParameterModel
headersGeneric Accengage headers
URL

See Partner ID for the partnerId URL parameter

query params
query

See query parameters in Paginated requests.

Response
CodeReasonModelHeaders

200

OK

 

 Android... Click to expand

 


 

AndroidMessage

 


 

AndroidButton

 


 

CustomParams

 


 

 iOS... Click to expand

 


 

iOSMessage

 


 

 

CustomParams

 


 

 Web... Click to expand

 


 

WebMessage

 


 

 

CustomParams
See Link response headers in Paginated requests.

Filters

You can filter the messages you get from the list using the externalId or title parameters.

If you want to search for messages containing a value, you can use the '%' caracter.

Example: to search for the messages whose externalId start with 'PushCampaign2017', you will use 'PushCampaign2017%'.

Be reminded that you must URL-encode your parameters.

Create

This API call is used for creating messages.

Operations

POST

/v1/me/apps/:partnerId/messages

ParameterModel
headersGeneric Accengage headers
URLSee Partner ID for the partnerId URL parameter
body
 Android... Click to expand
Message

 


 

AndroidMessage

 


 

AndroidButton

 


 

CustomParams

 


 

Information

action, if defined in AndroidButton, must have a value in ["browser", "email", "phone", "store", "sms", "urlscheme", "webview", "request", "close"].

Its default value is "close".

 


 

 iOS... Click to expand
Message

 


 

iOSMessage

 


 

iOSButton

 


 

CustomParams

 


 

Information

action, if defined in iOSButton, must have a value in ["browser", "email", "phone", "store", "sms", "urlscheme", "webview", "request", "close"].

Its default value is "close".

 


 

 Web... Click to expand
Message

 


 

WebMessage

 


 

CustomParams
Response
CodeReasonModelHeaders

200

OK

400

Validation failed for the given message

 

400Unknown campaign given
404Unknown collapse key given
404Invalid template for buttons

Examples

RequestCodeResponseReason

POST /v1/me/apps/myPartnerId/messages

200

The message has been created successfully.

POST /v1/me/apps/myPartnerId/messages

200
The message has been created successfully with English and French translations.

POST /v1/me/apps/myPartnerId/messages


 
 The message has been created with interactive buttons, linked to one test segment and two campaigns segments.

POST /v1/me/apps/myPartnerId/messages

400
Since the campaign with ID -1 does not exist, the message has not been created.

Get

This API call returns the details of a specific message.

Operations

GET

/v1/me/apps/:partnerId/messages/:messageId

ParameterModel
headersGeneric Accengage headers
URL

See Partner ID for the partnerId URL parameter

Response
CodeReasonModelHeaders

200

OK

 Android... Click to expand

 


 

AndroidMessage

 


 

AndroidButton

 


 

CustomParams

 


 

 iOS... Click to expand

 


 

iOSMessage

 


 

 

CustomParams

 


 

 Web... Click to expand

 


 

WebMessage

 


 

 

CustomParams
400Message ID is not a positive integer
404Message with given ID not found

Examples

RequestCodeResponseReason

GET /v1/me/apps/myPartnerId/messages/2157

200

Message 2157 successfully retrieved.

GET /v1/me/apps/myPartnerId/messages/2159

404
Could not find the message with ID 2159 because it doesn't exist

Update

This API call is used for updating an existing message.

Operations

PUT

/v1/me/apps/:partnerId/messages/messageId

ParameterModel
headersGeneric Accengage headers
URL

See Partner ID for the partnerId URL parameter

body
Response
CodeReasonModelHeaders

200

OK

400Much like for the Message GET request, happens if the campaign ID given in the request does not match the expected format

Examples

RequestCodeResponseReason

PUT /v1/me/apps/myPartnerId/campaigns/1613

200

The message has been successfully updated.

Delete

This API calls is used for permanently deleting a message.

Operations

 

DELETE

/v1/me/apps/: partnerId/messages/:messageId

ParameterModel
headersGeneric Accengage headers
URL

See Partner ID for the partnerId URL parameter

Response
CodeReasonModelHeaders

200

OK

400Much like for the Message GET request, happens if the campaign ID given in the request does not match the expected format
404Resource not found; note that this can also mean you have no access over the specified message (it may belong to another app and will therefore not be found by the server in the list of messages that you possess)

This request is not idempotent, as it may return a 404 error in case the resource is not found.

Examples

RequestCodeResponseReason

DELETE /v1/me/apps/myPartnerId/messages/1613

200

The message with ID 1613 was successfully deleted.

DELETE /v1/me/apps/myPartnerId/messages/456

404
In this case, since the message with ID 456 does not exist, the server returns a 404. This API call is not idempotent to ensure transparent visibility over the actions taken by the server.


List actions

This API enables you to list the possible actions id and details for a specific message. Please note that this request is paginated. See Paginated requests for more information.

Operations

GET

/v1/me/apps/:partnerId/messages/:messageId/actions

ParameterModel
headersGeneric Accengage headers
URL

See Partner ID for the partnerId URL parameter

query

See query parameters in Paginated requests.

Response
CodeReasonModelHeaders

200

OK

 

Also includes links of paginated requests, see link response body field in Paginated requests

See Link response headers in Paginated requests.
See Generic errors for all-purpose errors

Examples

RequestCodeResponseReason

GET /v1/me/apps/myPartnerId/messages/1613/actions

200

Returned the list of actions of the given message


Instant messages

By application

This API enables you to trigger an existing message on Accengage for specific users or a static list. Any parameter defined in the API will overload the parameter defined in the message on our dashboard. 

Behavior: A successfull return of the call means we handled your request. We will then proceed to the delivery for the targeted devices.

Customization: In the message (on the dashboard or in the 'text' parameter of the API call, you can define custom fields with a specific value defined at the target level. It enables you to customize the final message at a device level with data coming from your system without having to store this data in our database.

Use case example: Order delivery message.

  1. The Marketing team can create a message template in the Accengage dashboard with the following content: Hi ${firstname}, your order number ${order_id} will be delivered the ${delivery_date}.
  2. A Send Instant Message API call is triggered on this message every time a user gets eligible. It targets a specific Client Id (already tracked in Accengage) and specifies the values of order_id and delivery_date for the user.

Using a web application ?

If you are using this API to target web users, please note that your message can only be delivered to devices with the "sw_version" field greater than or equal to "b3.1.0"

Operations

POST

/v1/me/apps/:partnerId/send

ParameterModel
headersGeneric Accengage headers
URL

See Partner ID for the partnerId URL parameter

body
InstantMessage

 


 

MessageData

 


 

AndroidButton

 


 

iOSButton

 


 

Target

 


 

action, if defined in AndroidButton or iOSButton, must have a value in ["browser", "email", "phone", "store", "sms", "urlsheme", "webview", "request", "close"].

Its default value is "close".

Please note : marketing pressure does not apply for instant message calls.

Either parentMessageId or parentMessageExternalId must be defined.

Response
CodeReasonModel

200

OK

 

400

Invalid format

The precise reason will be given in the error message

400Using segments, lists and/or filters in the same Instant Message
400Unmatched template parameter(s)
400

Using non indexed criterions to query.

See if the "clientId" option is checked on your database scheme

404

Resource not found

The precise resource will be given in the message of the error

In the target object, you have to use at least your client id, the token, the deviceId field, or any indexed field (a field marked as "client Id" in you database scheme) with an "=" operator. You just have to use the name of the field in the database scheme of the application. See examples.

The data field of the targets is used if you want to send custom informations for the user(s).

Please note that at least one target must be valid.

Examples

RequestCodeResponseReason

POST /v1/me/apps/:myPartnerId/send

Here, are different examples of targets. The first and the second one both use indexed fields only, using two different formats, while the third target combines indexed fields and queries on non indexed fields.

200

The instant message has been sent to the targets.

You can have up to 100 targets in a single instant message request, resulting in the fastest instant messages possible.


Multiple applications

With this route you can do the same as an Instant message for an application, but for several applications at the same time if you have a common target to several apps. an iOS and Android app for instance.

This API enables you to trigger an exisiting message on Accengage for specific users or a static list. Any parameter defined in the API will overload the parameter defined in the message on our dashboard. 

Behavior: A successfull return of the call means we handled your request. We will then proceed to the delivery for the targeted devices on the targeted apps.

Customization: In the message (on the dashboard or in the 'text' parameter of the API call, you can define custom fields with a specific value defined at the target level. It enables you to customize the final message at a device level with data coming from your system without having to store this data in our database.

Use case example: Order delivery message.

  1. The Marketing team can create a message template on each app in the Accengage dashboard with the following content: Hi ${firstname}, your order number ${order_id} will be delivered the ${delivery_date}.
  2. Note that using the external Message Id enables you to define the same External Id for each app. 
  3. A Send Instant Message API call is triggered on these messages every time a user gets eligible. It targets a specific Client Id (already tracked in Accengage) and specify the values of order_id and delivery_date for the user.

Operations

POST

/v1/me/send

ParameterModel
headersGeneric Accengage headers
URL

body
InstantMessage

 


 

MessageData

 


 

AndroidButton

 


 

iOSButton

 


 

Targets

 


 

 

The apps object uses your partner ids as keys. See examples below.

action, if defined in AndroidButton or iOSButton, must have a value in ["browser", "email", "phone", "store", "sms", "urlsheme", "webview", "request", "close"].

Its default value is "close".

Please note : marketing pressure does not apply for instant message calls.

Either parentMessageId or parentMessageExternalId must be defined for each application object.

Response
CodeReasonModel

200

OK

 

400

Invalid format

The precise reason will be given in the error message

In the target object, you have to use at least your client id, the token, the deviceId field, or any indexed field (a field marked as "client Id" in you database scheme) with an "=" operator. You just have to use the name of the field in the database scheme of the application. See examples.

The data field of the targets is used if you want to send custom informations for the user(s).

Use the "$eq" parameter for equal comparison, "$lt" for less than, "$gte" for greater or equal than, and so on...

Please note that at least one target must be valid.

Examples

RequestCodeResponseReason

POST /v1/me/send

In the response, you will have the detail for each application. A status code 200 means the messages have been sent. With any other status code, a body explaining the error will be given. These errors are the same as in the Instant Message for one application.

200

The instant messages have been sent to the targets for application mySecondPartnerId.

POST /v1/me/send


400
You need to have an apps object in your body.

POST /v1/me/send


 400
You need to have an targets object in your body.


Schedule

Create

This route allows you to create a schedule for a message.

Operations

POST

/v1/me/apps/:partnerId/messages/:messageId/schedules

ParameterModel
headersGeneric Accengage headers
URL

See Partner ID for the partnerId URL parameter

See Message ID for the messageId URL parameter

Request
body
Schedule

Please note that the timezone is strictly indicative. If you want to use a specific timezone, specify it in the nextSendingDate, using the ISO format.

Return code
returnCodeDescription

200

OK

400Validation failed for body param(s)
400Next sending date is outdated
403Schedule already exists for message

Examples

RequestBodyResponseHttp Code

POST /v1/me/apps/myPartnerId/messages/123/schedules

Body


200
POST /v1/me/apps/myPartnerId/messages/123/schedules
Body
Response  Expand source
400
POST /v1/me/apps/myPartnerId/messages/123/schedules
Body
Response  Expand source
403

Read

This route allows you to request the information on the schedule of the message.

Operations

GET

/v1/me/apps/:partnerId/messages/:messageId/schedules

ParameterModel
headersGeneric Accengage headers
URL

See Partner ID for the partnerId URL parameter

See Message ID for the messageId URL parameter

body


Response
body
Schedule

Please note that the timezone is strictly indicative. If you want to use a specific timezone, specify it in the nextSendingDate, using the ISO format.

Return code
returnCodeDescription

200

OK

404No schedule for messageId

Examples

RequestBodyResponseHttp Code

GET /v1/me/apps/myPartnerId/messages/123/schedules


Response
200
GET /v1/me/apps/myPartnerId/messages/1234/schedules

Response
404

Update

This route allows you to update a message's schedule.

Operations

PUT

/v1/me/apps/:partnerId/messages/:messageId/schedules

ParameterModel
headersGeneric Accengage headers
URL

See Partner ID for the partnerId URL parameter

See Message ID for the messageId URL parameter

body
Schedule
Response
body

Return code
returnCodeDescription

200

OK

400Validation failed for body param(s).
403Next sending date is outdated
404Schedule already exists for message

Examples

RequestBodyResponseHttp Code

PUT /v1/me/apps/myPartnerId/messages/123/schedules

Body


200
PUT /v1/me/apps/myPartnerId/messages/123/schedules
Body
Response  Expand source
404
PUT /v1/me/apps/myPartnerId/messages/123/schedules
Body
Response  Expand source
400

Delete

This route allows you to delete a message's schedule.

Operations

DELETE

/v1/me/apps/:partnerId/messages/:messageId/schedules

ParameterModel
headersGeneric Accengage headers
URL

See Partner ID for the partnerId URL parameter

See Message ID for the messageId URL parameter

body

Response
body

Return code
returnCodeDescription

200

OK

404No schedule for message

Examples

RequestBodyResponseHttp Code

DELETE /v1/me/apps/myPartnerId/messages/123/schedules

200


Schedule Exclusions

Create

This route allows you to create a schedule exclusion for a message.

Operations

POST

/v1/me/apps/:partnerId/messages/:messageId/schedules/exclusions

ParameterModel
headersGeneric Accengage headers
URL

See Partner ID for the partnerId URL parameter

See Message ID for the messageId URL parameter

body
ScheduleExclusion

days field is a string formated like an array of Numbers representing the day of the week.

1: Monday

2: Tuesday

3: Wednesday

4: Thursday

5: Friday

6: Saturday

7: Sunday

Schedule exclusion's startDate and endDate fields must be included between schedule's startDate and endDate.

Response
CodeReason

200

OK

400Schedule exclusion type "DAYS" already exists.
404Schedule not found
404Message Push not found
See Generic errors for all-purpose errors

Examples

RequestBodyResponseCodeReason

POST /v1/me/apps/myPartnerId/messages/10/schedules/exclusions

 

Body

200

A schedule exclusion is created excluding Mondays and wednesdays during schedule.

POST /v1/me/apps/myPartnerId/messages/10/schedules/exclusions

 

Body
Response
400

A schedule exclusion already exists for type "DAYS"

There can only be one schedule exclusion for this type

POST /v1/me/apps/myPartnerId/messages/17/schedules/exclusions

 

Body
Response
404
Message could not be found or is not a push.

POST /v1/me/apps/myPartnerId/messages/7/schedules/exclusions

 

Body
Response
404
The message must be scheduled to use schedule exclusions.

Read

This route allows you to request the information on the schedule exclusions of the message.

Operations

GET

/v1/me/apps/:partnerId/messages/:messageId/schedules/exclusions

ParameterModel
headersGeneric Accengage headers
URL

See Partner ID for the partnerId URL parameter

See Message ID for the messageId URL parameter

body

Response
body
ScheduleExclusion
Return code
CodeReason

200

 

OK

404Message not found
404Message not scheduled
See Generic errors for all-purpose errors

 

 

Examples

RequestCodeResponseReason

GET /v1/me/apps/myPartnerId/messages/10/schedules/exclusions

200
Response

 

 

GET /v1/me/apps/myPartnerId/messages/123/schedules/exclusions

404
Response
Message not found or is not a push.

GET /v1/me/apps/myPartnerId/messages/123/schedules/exclusions

404
Response
The message must be scheduled to have schedule exclusions.

 

 

Delete

This route allows you to delete a message's schedule exclusions

Operations

DELETE

/v1/me/apps/:partnerId/messages/:messageId/schedules/exclusions

ParameterModel
headersGeneric Accengage headers
URL

See Partner ID for the partnerId URL parameter

See Message ID for the messageId URL parameter

query

body

Response
CodeReasonModelHeaders

200

 

OK

 

See Generic errors for all-purpose errors



Examples

RequestCodeResponseReason

DELETE /v1/me/apps/myPartnerId/messages/10/schedules/exclusions

200

Schedule exclusions have been deleted


Send

Create

This route allows you to send a message, both for test or campaign sends.

Operations

POST

/v1/me/apps/:partnerId/messages/:messageId/send[?test=true]

 
ParameterModel
headersGeneric Accengage headers
URL

See Partner ID for the partnerId URL parameter

See Message ID for the messageId URL parameter

The test param is optional, and must equal true (in lower cases) if you want your send to be a test.

Request
body

Return code
returnCodeDescriptionLabel

200

OK

400The message is already being sentAPI_ERR_MESSAGE_SENDING
400The message has already been sentAPI_ERR_MESSAGE_SENT
400The message was already sent, and the send failedAPI_ERR_MESSAGE_FAILED

Examples

RequestBodyResponseHttp Code

POST /v1/me/apps/myPartnerId/messages/123/send

200
POST /v1/me/apps/myPartnerId/messages/123/send

Response  Expand source
400
POST /v1/me/apps/myPartnerId/messages/123/send

Response  Expand source
400
POST /v1/me/apps/myPartnerId/messages/123/send
Response  Expand source
400


Devices

List

For a given app, the list of associated devices can be queried by the following API route.

This request returns 10,000 devices per call, meaning only a small portion of the results will be returned by an API call. To recuperate the complete list of results, links to the next results are given in the resulting Link header.

Operations

GET

/v1/me/apps/:partnerId/devices

ParameterModel
headersGeneric Accengage headers
URL

See Partner ID for the partnerId URL parameter

query
Response
CodeReasonModelHeaders

200

OK

CSV body

400At least one of the given fields does not exist on the application.
See Generic errors for other errors

If firstOpen is set and encompasses a range (Date '|' Date format), returns results matching leftDate <= device.firstOpen < rightDate. Otherwise, if set, but not as a range, returns results matching date <= device.firstOpen.

If lastOpen is set, returns results matching date <= device.lastOpen.

Note that dates are given in the ISO 9601 (RFC 3339) format.

Examples

RequestCodeResponseReason

GET /v1/me/apps/myPartnerId/devices?lastOpen=2014-06-08%2012%3A34%3A56

200CSV bodyReturns the list of devices where 2014-06-08 12:34:56 < device.lastOpen
GET /v1/me/apps/myPartnerId/devices?fields%5B1%5D=UDID&fields%5B2%5D=IDFA200CSV bodyReturns the list of devices with only the UDID and IDFA fields.

This API call allows to search for a device using various filters. It returns the first result matching the given filter. To ensure getting the precise device you're searching for, you may use as much filters as possible.

Note that, for performance reasons, only indexed fields may be queried.

Operations

GET

/v1/me/apps/:partnerId/devices/search/by

ParameterModel
headersGeneric Accengage headers
URL

See Partner ID for the partnerId URL parameter

query
Response
CodeReasonModelHeaders

200

OK

400Either there were no filters in the request, or some filters have been rejected because the matching fields are not indexed
404No result found
See Generic errors for all-purpose errors

The * in the request query denotes any indexed field in the user base.

The data field here is not defined because its content may differ between apps. You are however assured to receive a UDID field with the user, to ensure you queried the right user.

Examples

RequestCodeResponseReason

GET /v1/me/apps/myPartnerId/devices/search/by?UDID=F31548D3-F93E-498F-8E01-F18CC4EB2F5F

200

The device could be found and has been returned successfully

GET /v1/me/apps/myPartnerId/devices/search/by?token=AB5F200
Same device as before, this time filtered by token (which is an indexed field)

GET /v1/me/apps/myPartnerId/devices/search/by

400
There were no filters at all in the request
GET /v1/me/apps/myPartnerId/devices/search/by?nonIndexedField=1400
This time, the given filter could not be found in the list of indexed fields, so the server refused to query the database with it
GET /v1/me/apps/myPartnerId/devices/search/by?UDID=A404
No device could be found using the given filters

Update

This API call allows for updating a device.

Operations

PUT

/v1/me/apps/:partnerId/devices/:udid

ParameterModel
headersGeneric Accengage headers
URL

See Partner ID for the partnerId URL parameter

body
DeviceDataToUpdate
Response
CodeReasonModelHeaders

200

OK

204Nothing to do
400Trying to update a field you cannot update (id, UDID)
See Generic errors for all-purpose errors

Note that a database error may occur, indicating the field you are trying to update does not exist.

Examples

RequestCodeResponseReason

PUT /v1/me/apps/myPartnerId/devices/F31548D3-F93E-498F-8E01-F18CC4EB2F5F

200

Successfully changed the token field of the device F31548D3-F93E-498F-8E01-F18CC4EB2F5F.

PUT /v1/me/apps/myPartnerId/devices/F31548D3-F93E-498F-8E01-F18CC4EB2F5F

204Nothing to do since no field has been included with the request.

PUT /v1/me/apps/myPartnedId/devices/F31548D3-F93E-498F-8E01-F18CC4EB2F5F

400
Since the UDID is a primary field used for determining the device, it cannot be modified.

Update by group

This API call allows for updating a list of devices.

Operations

PUT

/v1/me/apps/:partnerId/devices

ParameterModel
headersGeneric Accengage headers
URL

See Partner ID for the partnerId URL parameter

body

 


 

 

 

 

 

OR

 

 

 

 

Response
CodeReasonModelHeaders

200

OK

400Users must be an array.
400Can not update more than X users.
400Users are not well formated. The index of the user and the reason will be given.
400Invalid matching key(s) given.
400The field(s) do(es) not exist for this application.
 
403Can not update fields (like id or UDID).
 
See Generic errors for all-purpose errors

As for now, you can update up to 100 users at once.

Examples

RequestCodeResponseReason

PUT /v1/me/apps/myPartnerId/devices

200

Successfully changed the model field of the devices.

.

PUT /v1/me/apps/myPartnedId/devices

400
 Expand source
Since no matching key is given, can not update.


Static lists

A static list encapsulates a list of users that can be programmatically manipulated and modified. When sending a message, a static list can be associated with it to send the given message to the user's devices.

Due to it fanning lots and lots of device profiles, static lists have been designed around a queuing system. Pragmatically, this means modifications applied to a static list (insertion or deletion) are managed by a queue system that may take a little time to process the data. When working with static segments, especially when sending messages, you should make sure you update the static list a little before the message.

 

If your list uses custom-fields, you need can customize messages with the attached values at a user lever. You need to use ${a4p_fieldname} in the message form. It is compatible with push notifications, in-app messages and scheduled alarms.

Note that the customization fields will only be available if the list is directly targeted. If you combine the list with other criteria in a segment, the personnalisation will no longer be available.

There is currently no solution to update or delete a static list. The PUT and DELETE requests defined below may be used for upserting and removing devices to the static list, but updating and deleting the list require a manual administrator action.

 

List

This API call returns the list of static lists associated with the given partner ID.

Please note that this request is paginated. See Paginated requests for more information.

Operations

GET

/v1/me/apps/:partnerId/lists

ParameterModel
headersGeneric Accengage headers
URL

See Partner ID for the partnerId URL parameter

Response
CodeReasonModelHeaders

200

OK

See Generic errors for all-purpose errors

Examples

RequestCodeResponseReason

GET /v1/me/apps/myPartnerId/lists

200

Returns the beginning of the static list, ordered by ascending static list ID.

Create

This API is used for creating static lists.

Operations

POST

/v1/me/apps/:partnerId/lists

ParameterModel
headersGeneric Accengage headers
URLSee Partner ID for the partnerId URL parameter
body
StaticList
Response
CodeReasonModelHeaders

200

OK

400Missing or malformed field in body
409A static list with the given listId already exists
See Generic errors for all-purpose errors

The listId field can be used for inputting your own, custom list integer ID (for an ID mapping purpose). The externalId field can be used for having a custom list string ID, and is required for adding and removing a device from a list via the mobile SDKs.

Examples

RequestCodeResponseReason

POST /v1/me/apps/myPartnerId/lists

200

A new list with name "My list" and ID 1234 was successfully created

POST /v1/me/apps/myPartnedId/lists

200
Here, the server has generated an automatic ID (1235) and assigned it to the list

POST /v1/me/apps/myPartnedId/lists

 

200
A new list has been created with the external ID myExternalId; this external ID may be used with the SDK to add users to the list

POST /v1/me/apps/myPartnedId/lists

409
Now, since the list with ID 1235 already exists, the server refused to create the list because it would result in a conflict

Get

This API call returns the list of devices included in a static list.

Since there may be many devices in a list, this API call is paginated. See Paginated requests for more information.

Operations

GET

/v1/me/apps/:partnerId/lists/:listId

ParameterModel
headersGeneric Accengage headers
URL

See Partner ID for the partnerId URL parameter

Response
CodeReasonModelHeaders

200

OK

Also includes links of paginated requests, see link response body field in Paginated requests

See Link response headers in Paginated requests.
See Generic errors for all-purpose errors

The deviceId field corresponds to the UDID of the device.

Examples

RequestCodeResponseReason

GET /v1/me/apps/myPartnerId/lists/1235

200

 

GET /v1/me/apps/myPartnerId/lists/9000

200
Here, the associated list does not exist. For performance reasons, this API call still returns 200, but with no content.

Upsert device

This API call is used for upserting new devices in a static list.

If the device is already in the list, it will be updated with the new expireAt value.

Operations

PUT

/v1/me/apps/:partnerId/lists/:listId

ParameterModel
headersGeneric Accengage headers
URL

See Partner ID for the partnerId URL parameter

body
User
Device
OR
Device
Response
CodeReasonModelHeaders

200

OK

400The field users is missing from the body.
400The given field cannot be found for devices of the app.
404There are no associated table with the given list. This error happens when the static list doesn't exist for the server.
See Generic errors for all-purpose errors

There are two ways to use this feature:

  • by device ID: select the user to add by UDID
  • by custom field: select the user to add with a custom app field; this field must be indexed, please contact an administrator for more information

 

The expireAt field is a JavaScript-compatible date and is used for removing the device from the list automatically when the date is reached.

Examples

RequestCodeResponseReason

PUT /v1/me/apps/myPartnerId/lists/1235

200

The users (one with UDID "1A2B3C4D-5E6F-7A8B-9C0D-1E2F3A4B5C6D" and one with myCustomField=value) exist and have been successfully added to the static list processing queue.

PUT /v1/me/apps/myPartnerId/lists/1235

400
There's no user to add in the body as the users field is missing.

PUT /v1/me/apps/myPartnerId/lists/1235


 400
Since there is no flagada custom field associated with the devices, the system cannot successfully find a device from it.

PUT /v1/me/apps/myPartnerId/lists/9000

404
Since the static list with ID 9000 does not exist, the server cannot insert the users to add in the specified static list.

Remove device

This API call is used for removing devices from a static list.

Operations

DELETE

/v1/me/apps/:partnerId/lists/:listId

See Static lists - Upsert device for more information.

This API call is similar to the Static lists - Upsert device API route in its usage.


Clicks

These API call returns information about the devices who reacted to campaigns. These clicks can be selected by campaign ID or by message ID. 

In case of Inapp campaigns or reccuring push campaigns, we recommend to query a specific period. It is possible to request additional custom device data (the Customer_Id for instance) in the response of the call by adding the 'data' object in the query.

Clicks by campaign ID

Please note that this request is paginated. See Paginated requests for more information.

Operations

GET

/v1/me/apps/:partnerId/campaigns/:campaignId/clicks

ParameterModel
headersGeneric Accengage headers
URL

See Partner ID for the partnerId URL parameter

query

See query parameters in Paginated requests.

Response
CodeReasonModelHeaders

200

OK

Also includes links of paginated requests, see link response body field in Paginated requests

See Link response headers in Paginated requests.
400The format of the given campaign ID is wrong; must be a positive integer number.
403The campaign could be found but was not associated with the given partner ID. You may be using the wrong partner ID.
404Could not find the campaign with the given ID.
See Generic errors for all-purpose errors

Note that dates are given in the ISO 9601 (RFC 3339) format, i.e. YYYY-MM-DD or YYYY-MM-DD hh:mm:ss. All results down to startDate will be included if startDate is present, and up to endDate if endDate is present. If both fields are defined, results will be given in the range startDate <= date <= endDate.

Please note that if no button or rich display URL is set from the message, the reaction will not have the actionId property.

Examples

RequestCodeResponseReason

GET /v1/me/apps/myPartnerId/campaigns/91/clicks

200

with headers:

Note the first and next links, enabling to pass through complete list.

Clicks by message ID

Please note that this request is paginated. See Paginated requests for more information.

Operations

GET

/v1/me/apps/:partnerId/messages/:messageId/clicks

headersGeneric Accengage headers
URL

See Partner ID for the partnerId URL parameter

query

 

See query parameters in Paginated requests.

See Clicks by campaign ID for more information.

This API call is similar, both in call format, response and functionality to Clicks by campaign ID. The only difference lies in the URL and the given ID (message instead of campaign). For more information, see Clicks by campaign ID.


 

Targets

These API call enables you to list information about the devices targeted/exposed to a campaign. These targets can be selected by campaign ID or by message ID.

In case of Inapp campaigns or reccuring push campaigns, we recommend to query a specific period. It is possible to request additional custom device data (the Customer_Id for instance) in the response of the call by adding the 'data' object in the query.

Please note that sending targets are stored 3 months after sending in our database. Beyond this limit, targets won't appear in API response.

Targets by campaign ID

Please note that this request is paginated. See Paginated requests for more information.

Operations

GET

/v1/me/apps/:partnerId/campaigns/:campaignId/targets

ParameterModel
headersGeneric Accengage headers
URL

See Partner ID for the partnerId URL parameter

query

See query parameters in Paginated requests.

Response
CodeReasonModelHeaders

200

OK

Also includes links of paginated requests, see link response body field in Paginated requests

See Link response headers in Paginated requests.
400The format of the given campaign ID is wrong; must be a positive integer number.
403The campaign could be found but was not associated with the given partner ID. You may be using the wrong partner ID.
404Could not find the campaign with the given ID.
See Generic errors for all-purpose errors

Note that dates are given in the ISO 9601 (RFC 3339) format, i.e. YYYY-MM-DD or YYYY-MM-DD hh:mm:ss. All results down to startDate will be included if startDate is present, and up to endDate if endDate is present. If both fields are defined, results will be given in the range startDate <= date <= endDate.

Examples

RequestCodeResponseReason

GET /v1/me/apps/myPartnerId/campaigns/91/targets?data[]=clientId&data[]=bundleversion

200

with headers:

Note the first and next links, enabling to pass through complete list.

Targets by message ID

Please note that this request is paginated. See Paginated requests for more information.

Operations

GET

/v1/me/apps/:partnerId/messages/:messageId/targets

headersGeneric Accengage headers
URL

See Partner ID for the partnerId URL parameter

query

 

See query parameters in Paginated requests.

See Targets by campaign ID for more information.

This API call is similar, both in call format, response and functionality to Targets by campaign ID. The only difference lies in the URL and the given ID (message instead of campaign). For more information, see Targets by campaign ID.


Statistics

This API call returns daily statistics much in the same way as the dashboard on the Accengage interface.

Note that the server does not fill empty results, meaning you may get time gaps between results (ordered by ascending date).

Operations

GET

/v1/me/apps/:partnerId/stats

ParameterModel
headersGeneric Accengage headers
URLSee Partner ID for the partnerId URL parameter
query

See query parameters in Paginated requests.

Response
CodeReasonModelHeaders

200

OK

See Link response headers in Paginated requests.

If startDate is defined, returns statistics matching startDate <= stat.date <= endDate. If endDate is not defined, returns statistics matching startDate <= stat.date <= now.

Otherwise, if date is defined, returns statistics matching date == stat.date.

If no date or startDate is defined, returns all statistics about the app. Depending on the volume of the result, such API call may result in an HTTP timeout.


Note that, for this particular API call, Dates are defined in the YYYY-MM-DD format.

Also, startDate and endDate take precedence over date in case all these fields are defined.

Examples

RequestCodeResponseReason

GET /v1/me/apps/myPartnerId/stats

200
Successfully returned statistics since the beginning of time

GET /v1/me/apps/myPartnerId/stats?date=2015-01-01

200
Returned a single result with statistics for date 2015-01-01


Geofences

 

List

This API call returns the list of geofences associated with the given partner ID.

Please note this request is paginated. See Paginated requests for more information.

Operations

GET

/v1/me/apps/:partnerId/geofences

ParameterModel
headersGeneric Accengage headers
URLSee Partner ID for the partnerId URL parameter
Response
CodeReasonModelHeaders

200

OK

See Generic errors for all-purpose errors

Examples

RequestCodeResponseReason

GET /v1/me/apps/myPartnerId/geofences

200

with headers:

Returned the first set of geofences for the given partner ID.

 

 

Create

This API call is used for creating geofences.

Operations

POST

/v1/me/apps/:partnerId/geofences

ParameterModel
headersGeneric Accengage headers
URL

See Partner ID for the partnerId URL parameter

body
Geofence
Response
CodeReasonModelHeaders

200

geofence created successfully

400Validation failed for the given body
See Generic errors for all-purpose errors

Examples

RequestCodeResponseReason

POST /v1/me/apps/myPartnerId/geofences

200

The given geofence has been successfully created with the ID 404.

POST /v1/me/apps/myPartnerId/geofences

400
Since a geofence cannot be created without the info object, the server refused to create the geofence.

Get

This API call is used for getting a geofence.

Operations

GET

/v1/me/apps/:partnerId/geofences/:geofenceId

ParameterModel
headersGeneric Accengage headers
URL

See Partner ID for the partnerId URL parameter

Response
CodeReasonModelHeaders

200

OK

404Resource not found
See Generic errors for all-purpose errors

Examples

RequestCodeResponseReason

GET /v1/me/apps/myPartnerId/geofences/404

200

The geofence with ID 404 was returned successfully.

GET /v1/me/apps/myPartnerId/geofences/405

404
The geofence with ID 405 does not exist for this application.

Update

This API call is used for creating geofences.

Operations

PUT

/v1/me/apps/:partnerId/geofences/:geofenceId

ParameterModel
headersGeneric Accengage headers
URL

See Partner ID for the partnerId URL parameter

body
Geofence
Response
CodeReasonModelHeaders

200

geofence created successfully

400Validation failed for the given body
See Generic errors for all-purpose errors

Examples

RequestCodeResponseReason

POST /v1/me/apps/myPartnerId/geofences/404

200

The given geofence has been successfully updated.

PUT /v1/me/apps/myPartnerId/geofences/404

400
Since a geofence cannot be updated without the info object, the server refused to update the geofence.


Beacons

List

This API call returns the list of beacons associated with the given partner ID.

Please note this request is paginated. See Paginated requests for more information.

Operations

GET

/v1/me/apps/:partnerId/beacons

ParameterModel
headersGeneric Accengage headers
URLSee Partner ID for the partnerId URL parameter
Response
CodeReasonModelHeaders

200

OK

See Generic errors for all-purpose errors

Examples

RequestCodeResponseReason

GET /v1/me/apps/myPartnerId/beacons

200

with headers:

Returned the first set of beacons for the given partner ID.

 

 

Create

This API call is used for creating beacons.

Operations

POST

/v1/me/apps/:partnerId/beacons

ParameterModel
headersGeneric Accengage headers
URL

See Partner ID for the partnerId URL parameter

body
Beacon
Response
CodeReasonModelHeaders

200

Beacon created successfully

400Validation failed for the given body
See Generic errors for all-purpose errors

Examples

RequestCodeResponseReason

POST /v1/me/apps/myPartnerId/beacons

200

The given beacon has been successfully created with the ID 404.

POST /v1/me/apps/myPartnerId/beacons

400
Since a beacon cannot be created without the info object, the server refused to create the beacon.

Get

This API call is used for getting a beacon.

Operations

GET

/v1/me/apps/:partnerId/beacons/:beaconId

ParameterModel
headersGeneric Accengage headers
URL

See Partner ID for the partnerId URL parameter

Response
CodeReasonModelHeaders

200

OK

404Resource not found
See Generic errors for all-purpose errors

Examples

RequestCodeResponseReason

GET /v1/me/apps/myPartnerId/beacons/404

200

The beacon with ID 404 was returned successfully.

GET /v1/me/apps/myPartnerId/beacons/405

404
The beacon with ID 405 does not exist for this application.

Update

This API call is used for creating beacons.

Operations

PUT

/v1/me/apps/:partnerId/beacons/:beaconId

ParameterModel
headersGeneric Accengage headers
URL

See Partner ID for the partnerId URL parameter

body
Beacon
Response
CodeReasonModelHeaders

200

Beacon created successfully

400Validation failed for the given body
See Generic errors for all-purpose errors

Examples

RequestCodeResponseReason

POST /v1/me/apps/myPartnerId/beacons/404

200

The given beacon has been successfully updated.

PUT /v1/me/apps/myPartnerId/beacons/404

400
Since a beacon cannot be updated without the info object, the server refused to update the beacon.


Geogroups

Create

This API call allows for creating a new group of geolocations.

Operations

POST

/v1/me/apps/:partnerId/geogroups

ParameterModel
headersGeneric Accengage headers
body
Geogroup
Response
CodeReasonModelHeaders

200

OK

Links: ...
See Generic errors for all-purpose errors

Examples

RequestCodeResponseReason

POST /v1/me/apps/myPartnerId/geogroups

200

The group was created successfully.

POST /v1/me/apps/myPartnerId/geogroups

200

The group was created successfully with an external ID.

List

This API call is used for listing groups of geolocations.

Please note that this request is paginated. See Paginated requests for more information.

Operations

GET

/v1/me/apps/:partnerId/geogroups

ParameterModel
headersGeneric Accengage headers
URLSee Partner ID for the partnerId URL parameter
Response
CodeReasonModelHeaders

200

OK

See Generic errors for all-purpose errors

Examples

RequestCodeResponseReason

GET /v1/me/apps/myPartnerId/geolocation

200
 

Add beacon / geofence to geogroup

This API calls allows for adding beacons and geofences to a geogroup.

Operations

POST

/v1/me/apps/:partnerId/geogroups/:geogroupId/beacons
/v1/me/apps/:partnerId/geogroups/:geogroupId/geofences

ParameterModel
headersGeneric Accengage headers
URL
body
ObjectTechnicalType
Response
CodeReasonModelHeaders

200

OK

400The id field was not given in the request body
See Generic errors for all-purpose errors

The id field in the body corresponds to the beacon ID or the geofence ID to add to the geogroup.

Examples

RequestCodeResponseReason

POST /v1/me/apps/myPartnerId/geogroups/422/beacons

200

Adds the beacon with ID 404 to the geogroup with ID 422.

POST /v1/me/apps/myPartnerId/geogroups/ext:myGeogroupExternalId/beacons


200 Adds the same beacon as before to the geogroup with ID 422.

POST /v1/me/apps/myPartnerId/geogroups/ext:myGeogroupExternalId/geofences


200 Adds the geofence with ID 479 to the geogroup with ID 422.

POST /v1/me/apps/myPartnerId/geogroups/ext:myGeogroupExternalId/beacons

400
Missing id field in the given body.

Remove beacon / geofence from geogroup

This API calls allows for removing beacons and geofences from a geogroup.

Operations

DELETE

/v1/me/apps/:partnerId/geogroups/:geogroupId/beacons
/v1/me/apps/:partnerId/geogroups/:geogroupId/geofences

ParameterModel
headersGeneric Accengage headers
URL
body
ObjectTechnicalType
Response
CodeReasonModelHeaders

200

OK

400The id field was not given in the request body
See Generic errors for all-purpose errors

The id field in the body corresponds to the beacon ID or the geofence ID to remove from the geogroup.

Examples

RequestCodeResponseReason

DELETE /v1/me/apps/myPartnerId/geogroups/422/beacons

200

 

Removes the beacon with ID 404 from the geogroup with ID 422.

DELETE /v1/me/apps/myPartnerId/geogroups/ext:myGeogroupExternalId/beacons


200 Removes the same beacon as before from the geogroup with ID 422.

DELETE /v1/me/apps/myPartnerId/geogroups/ext:myGeogroupExternalId/geofences


200 Removes the geofence with ID 479 from the geogroup with ID 422.

DELETE /v1/me/apps/myPartnerId/geogroups/ext:myGeogroupExternalId/beacons

400
Missing id field in the given body.


In-Apps

List

This API call is used for listing inApp messages associated with the given partner ID.

Please note that this request is paginated. See Paginated requests for more information.

Operations

GET

/v1/me/apps/:partnerId/inapps

ParameterModel
headersGeneric Accengage headers
URL

See Partner ID for the partnerId URL parameter

query

See query parameters in Paginated requests.

Response
CodeReasonModelHeaders

200

OK

 

See Link response headers in Paginated requests.

See InAppObject in the Get route.

Create

You can create InApp messages with this API call.

Operations

POST

/v1/me/apps/:partnerId/inapps

ParameterModel
headers
Generic Accengage headers
partnerId
See Partner ID for the partnerId URL parameter
body
Inapp

 


 

List

 


 

Segments

 


 

Triggers

 


 

Geolocation

 


 

Beacon

 

 


 

State

 


 

CustomParams

 


 

InAppMessage

 


 

PopupTemplate

 


 

Button

 


 

BrowserTemplate - Only iOS

 


 

CustomTemplate

 


 

Action

 

For the Action and CustomTemplate objects, the templateValue is the value of the Inapp Templates, available in the settings section on the interface. The mandatory keys of the API call depends on the type of this template.

Note that in case of multilingual messages, the templates for each messages must be the same.

Response
body
Return code
returnCodeDescription

200

The API call was a success, and the message was created.

 

400The provided body does not match the expected schema. The precise reason will be given in the body of the response.
404The ressource (template, geolocation, beacon...) given does not exist.

Examples

RequestBodyResponse
/v1/me/apps/:partnerId/inapps
/v1/me/apps/:partnerId/inapps

Get

This API call returns a message.

Operations

GET

/v1/me/apps/:partnerId/inapps/:inappId

OR

/v1/me/apps/:partnerId/inapps/external/:externalId

ParameterModel
headersGeneric Accengage headers
URL

 

 

See Partner ID for the partnerId URL parameter

Response
CodeReasonModelHeaders

200

OK

 


 

List

 


 

Triggers

 


 

Geolocation

 


 

Beacon

 


 

State
InAppMessage

 


 

PopupTemplate

 


 

Button

 


 

BrowserTemplate

 


 

CustomTemplate

 


 

Action

 


 

CustomParams

 


 

Segments
400InApp ID is not a positive integer
404InApp with given ID not found

Examples

RequestCodeResponseReason

GET /v1/me/apps/myPartnerId/inapps/2157

200

Message 2157 successfully retrieved.

GET /v1/me/apps/myPartnerId/inapps/2159

404
Could not find the inApp message with ID 2159 because it doesn't exist

Update

You can update InApp messages with this API call.

Operations

PUT

/v1/me/apps/:partnerId/inapps/:inAppId

OR

/v1/me/apps/:partnerId/inapps/external/:externalId

ParameterModel
headers

inAppId: Number

externalId: String

 

Generic Accengage headers

partnerId
See Partner ID for the partnerId URL parameter
body

See Create. Please also note that the template type of an InApp message can not be changed.

Return code
returnCodeDescription

200

The API call was a success, and the message was updated.

 

400The provided body does not match the expected schema. The precise reason will be given in the body of the response.
404The ressource (template, geolocation, beacon...) given does not exist.

Examples

RequestBodyResponse Code
/v1/me/apps/:partnerId/inapps/123

200

Status

This API call set the status of an In-App message to active or unactive.

Please note that if you active the In-App, but its date restrictions are not matched, the In-App will still be considered as inactive.

Operations

PUT

/v1/me/apps/:partnerId/inapps/:inAppId/status

OR

/v1/me/apps/:partnerId/inapps/external/:externalId/status

ParameterModel
header
inAppId: Number
externalId: String

 

See Partner ID for the partnerId URL parameter

body
Status
Response

Code

Response

Reason
200
ØThe status has been changed.
204
ØThe status was already the one you wanted.
404

 

 

The provided inAppId was not found.

 


Alarms

List

This API call is used for listing alarms associated with the given partner ID.

Please note that this request is paginated. See Paginated requests for more information.

Operations

GET

/v1/me/apps/:partnerId/alarms

ParameterModel
headers

Generic Accengage headers

URL
See Partner ID for the partnerId URL parameter
query
See query parameters in Paginated requests.
Response
body
Alarms

 


 

Settings

 


 

ExclusionRanges

 


 

Segments

 


 

List

 


 

Triggers

 


 

Geolocation

 


 

Beacon

 


 

State

 


 

CustomParams

 


 

Programmation

 


 

 

AndroidMessage
AndroidButton

 

 

iOSMessage
iOSButton

 

 

Create

This API route is used to create a Scheduled Alarm.

Operations

POST

/v1/me/apps/:partnerId/alarms

ParameterModel
headers
Generic Accengage headers
partnerId
See Partner ID for the partnerId URL parameter
body
Alarms

 


 

List

 


 

Settings

 


 

ExclusionRanges

 


 

Segments

 


 

Triggers

 


 

Geolocation

 


 

Beacon

 


 

State

 


 

CustomParams

 


 

Programmation

 


 

 

AndroidMessage

 


 

AndroidButton

 

 

iOSMessage

 


 

iOSButton

 

For events objects, the expected identifier is the "code" of the event (available in advanced settings on the interface).

For views objects, the expected identifier is the "value" of the View (available in advanced settings on the interface).

You can give any custom field by using the ${:yourCustomField} in your String (field name in DB between "${" and "}")

Response
returnCodeDescriptionModelHeaders

200

 

OK

400

Validation failed for the given message

Webservice can only be used for Android or iOS messages

The template must be the same for each message

   404

Can not find [ressource] with id ...

The geolocation, event, view, beacon, or state could not be found for this application

Examples

RequestBodyCodeResponseReason

POST /v1/me/apps/:myPartnerId/alarms

 200
The message has been successfully created.

Get

This API call returns an alarm.

Operations

GET

/v1/me/apps/:partnerId/alarms/:alarmId

OR

/v1/me/apps/:partnerId/alarms/external/:externalId

ParameterModel
headersGeneric Accengage headers

 

URL
alarmId: Integer
externalId: String

 

See Partner ID for the partnerId URL parameter

Response
body
Alarms

 


 

List

 


 

Settings

 


 

ExclusionRanges

 


 

Segments

 


 

Triggers

 


 

Geolocation

 


 

Beacon

 


 

State

 


 

CustomParams

 


 

Programmation

 


 

 

AndroidMessage
AndroidButton

 

 

iOSMessage
iOSButton

 

 

 

 

Examples

RequestCodeResponseReason
/v1/me/apps/:myPartnerId/alarms/123456
200

{
  "id": 12345,
  "name": "My Alarm",
  "messages": [{
    "title": "My message title",
    "sound": {
      "sound": "default"
    },
    "openRichPushIn": "webview",
    "delayTimerForAppliOff": true,
    "text": "Here you go",
    "clickCustomParams": {
        "Key1": "Value1"
    },
    "displayCustomParams": {
      "Key2": "Value2"
    }
  }],
  "triggers": {
    "displayCapping": 30,
    "globalClickCapping": 0,
    "sessionClickCapping": 0,
    "priority": 3,
    "cappingDelay": 0,
    "offlineDisplay": false,
    "geolocations": {},
    "beacons": {},
    "usePressure": false,
    "useDelay": false,
    "timer": {
      "duration": 0,
      "type": "lifetime"
    },
    "events": {
      "displayOnceByEvent": true
    },
    "views": {},
    "states": {
      "allStatesActive": true,
      "inclusion": [{
        "name": "myState",
        "contains": "BlueSky"
      }]
    }
  },
  "segments": {},
  "settings": {
    "programmation": {
      "useLocalDate": false,
      "type": "timer",
      "duration": 518400
    },
    "exclusionRanges": []
  },
  "isActive": false
}

Alarm 123456 successfully retrieved.
/v1/me/apps/:myPartnerId/alarms/123458
404
{
  "errors": [
    {
      "label""API_ERR_DATA",
      "message""Type, application and message ID mismatch"
    }
  ]
}

Message 123458 does not exists for this application, or is not an alarm.

Update

This API route is used to update an existing Scheduled Alarm.

Operations

PUT

/v1/me/apps/:partnerId/alarms/:alarmId

OR

/v1/me/apps/:partnerId/alarms/external/:externalId

ParameterModel
headers

alarmId: Number

externalId: String

Generic Accengage headers

partnerId
See Partner ID for the partnerId URL parameter
body

See Create.

Response
returnCodeDescriptionModelHeaders

200

 

OK

400

Validation failed for the given message

Webservice can only be used for Android or iOS messages

The template is mandatory and must be the same for every language of the message

   404

Can not find [ressource] with id ...

The geolocation, event, view, beacon, or state could not be found for this application

Examples

RequestBodyCodeReason

POST /v1/me/apps/:myPartnerId/alarms/:alarmId

 200
The message has been successfully updated.

Status

This API call set the status of an alarm to active or unactive.

Please note that if you active the alarm, but its date restrictions are not matched, the alarm will still be considered as inactive.

Operations

PUT

/v1/me/apps/:partnerId/alarms/:alarmId/status

OR

/v1/me/apps/:partnerId/alarms/external/:externalId/status

ParameterModel
header
alarmId: Number
externalId: String

 

See Partner ID for the partnerId URL parameter

body
Status
Response

Code

Response

Reason
200
ØThe status has been changed.
204
ØThe status was already the one you wanted.
404

 

 

The provided alarmId was not found.

 


Inboxes

Create

You can create Inbox messages with this API call.

Operations

POST

/v1/me/apps/:partnerId/inboxes

ParameterModel
headers
Generic Accengage headers
partnerId
See Partner ID for the partnerId URL parameter
body
InboxMessages

 


 

InboxMessage

 


 

ContentObject

 


 

Button
Response
body
Return code
returnCodeDescription

200

The API call was a success, and the message was created.

 

400The provided body does not match the expected schema. The precise reason will be given in the body of the response.
404The given ressource (event, segment, list...) does not exist.

Examples

RequestBodyResponse
/v1/me/apps/:partnerId/inboxes


Update

You can update an inbox message with this API call. Please note that you can not update an already sent message.

Operations

PUT

/v1/me/apps/:partnerId/inboxes/:inboxId

OR

/v1/me/apps/:partnerId/inboxes/external/:externalId

ParameterModel
headers

inboxId: Number

externalId: String

 

Generic Accengage headers

partnerId
See Partner ID for the partnerId URL parameter
body

See the Create route.

Return code
returnCodeDescription

200

The API call was a success, and the message was updated.

 

400The provided body does not match the expected schema. The precise reason will be given in the body of the response.
404The ressource (event, segment, list...) given does not exist.

Examples

RequestBodyResponse Code
/v1/me/apps/:partnerId/inboxes/123

200


 

Status

This API call set the readDate and the archivedDate of an Inbox message for a user.

Operations

PUT

/v1/me/apps/:partnerId/inboxes/:inboxId/status

OR

/v1/me/apps/:partnerId/inboxes/external/:externalId/status

ParameterModel
header
inboxId: Number
externalId: String

 

See Partner ID for the partnerId URL parameter

UDID: String, mandatory, the user's UDID to update.

body
Status
Response

Code

Response

Reason
200
ØThe status has been changed.
400
No UDID given in query.

404

ØThis message is not available for this user.
404

 

 

The provided Inbox message was not found.

 


 


 

  • No labels