This is a multi-page printable view. Click here to print.

API Library

Table of contents

1. Health Check
2. state-reader/FIND
3. state-reader/GET
4. state-reader/COUNT
5. state-writer/PUT

This section includes the four (4) Offer State API endpoints listed below. Each page includes a brief description and suggested use-case, as well as request and response body code samples.

API endpoints

Health Check

Test and confirm that the Offer State API is up and ready to process requests.

state-reader/FIND

Used to return all offers that a Collector has opted-into/saved.

state-reader/GET

Used to return only the opted-in/saved offers from a list of submitted offers.

state-reader/COUNT

Used to return the total number of offers a Collector has opted-into/saved.

state-writer/PUT

Used to update the Collector’s opt-in status for an AIR MILES offer.

Handling request/response messages

As described above, the RESTful specification defines a transaction as a pair of request and response messages that are used for information interchange.

Note

Mandatory parameters/properties will be marked with an asterisk (*) in the subsequent pages.

Message Type Description

Request All mandatory parameters MUST be included in each API call.
All other parameters are optional, unless stated otherwise.

Response Indicates which parameters/elements are always returned.
The “Response” Content-Type is specified in the Header (e.g., application/json.
A “Response” resulting in an ‘error condition’ will include an accompanying responseCode.
Partners are expected to verify and handle each Response Code as necessary.
All response values are NOT not case-sensitive.
Data elements that contain null or ‘empty’ values are automatically excluded from the response body.
The ‘POS’ terminal may use the response elements to display/print information for the customer.

Message Type	Description
Request	All mandatory parameters MUST be included in each API call. All other parameters are optional, unless stated otherwise.
Response	Indicates which parameters/elements are always returned. The “Response” `Content-Type` is specified in the Header (e.g., `application/json`. A “Response” resulting in an ‘error condition’ will include an accompanying `responseCode`. Partners are expected to verify and handle each Response Code as necessary. All response values are NOT not case-sensitive. Data elements that contain `null` or ‘empty’ values are automatically excluded from the response body. The ‘POS’ terminal may use the response elements to display/print information for the customer.

Response codes

Code	Description
`200`/`204`	Request Successful
`400`	Bad Request
`401`	Unauthorized
`404`	Record Not Found
`500`	Internal Server Error

1 - Health Check

Test and confirm that the Offer State API is up and ready to process requests.

GET /offers/state-reader/health

Take a look at our OpenAPI (Swagger-Spec) schema to learn more about the API calls.

This test endpoint ensures there are no known connectivity issues between AIR MILES and our partners. The HEALTH call functions similarly to a standard “ping” request, determining if a client or host is online and accessible.

Tip

It is highly recommended that all partners use the HEALTH endpoint upon starting their integration, to ensure both systems can communicate properly. Also at the partner’s discretion, we recommend performing periodic HEALTH tests at regular intervals to be notified immediately in the case of any unforeseen outages.

Sample request

curl -X GET \
  https://cert.airmilesapis.ca/offers/state-reader/health \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCI...' \
  --header 'Channel-Code: MOBAPP' \
  --header 'Accept-Language: EN'

Header parameters

Parameter	Description
Content-Type	Default value: `application/json`
Authorization	Token from authentication. Example: `Bearer <access_token>`
Channel-Code	Channel by which the transaction is called. The response will differ for different channels. Example: `MOBAPP`
Accept-Language	Language parameters, either “EN” for English or “FR” for French. Example: `EN`

Sample response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Mon, 29 Oct 2019 15:27:34 GMT
[
  {
    "healthy": true,
    "timestamp": "2022-08-18T19:00:53.151Z"
  }
]

2 - state-reader/FIND

Used to return all offers that a Collector has opted-into/saved.

GET /offers/state-reader/v1/find

Take a look at our OpenAPI (Swagger-Spec) schema to learn more about the API calls.

Used to return all offers that a Collector has opted-into/saved, for display within a “My Saved Offers” section of your mobile app or website.

Sample request

curl -X GET 
  https://uat.airmilesapis.ca/offers/state-reader/v1/find?state=SAVE:SAVED \
  --header 'Content-Type: application/json' \
  --header 'x-correlation-id: bcf529ae-0de0-4ded-90f5-e050ce2df0e3' \
  --header 'x-origin-client: external:partner:web' \
  --header 'x-local-time: 2021-07-07T16:59:00' \
  --header 'Authorization: Bearer LQoD0gWJK7l9znrmsGksWxbvIEx9a8zXkw...' \
  --data-raw ''

Request headers

Header	Description
`Content-Type`	Indicates the media type of the resource.
`x-correlation-id`	The unique ID for tracing the request across the system.
`x-origin-client`	Name of the Client and Channel. Example: `external:shell:web`
`x-local-time`	Local time of the client, excluding the timezone. Example: `2021-01-07T16.59:00`

Query parameters

Parameter	Description
`state`	The state types you want to retrieve. Example: `OPT_IN:OPTED_IN`
`partnerId`	The unique ID of the partner.
`region`	The Collector region.
`firstSortBy`	Level one, sort by type. Options: `displayPriority` `endDate` `mechanismPriority` (default)
`firstSortByDescending`	Level one, sort direction. Options: `true` (default) `false`
`secondSortBy`	Level two, sort type. Options: `displayPriority` `endDate` (default) `mechanismPriority`
`secondSortByDescending`	Level two, sort direction. Options: `true` (default) `false`
`pageNumber`	Page number of the results. Default: `1`
`pageSize`	How many offers listed on each page. Default: `20`

Sample response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Mon, 29 Oct 2018 15:27:34 GMT
{
    "offers": [
        {
            "offerId": "951d9a70-4cf8-41b1-a01e-7953f069f527",
            "collectorId": "80000000110",
            "states": [
                {
                    "name": "OPT_IN",
                    "value": "OPTED_IN",
                    "properties": {},
                    "updatedAt": "2021-07-07T20:55:26.276917Z"
                },
                {
                    "name": "SAVE",
                    "value": "SAVED",
                    "properties": {},
                    "updatedAt": "2021-07-07T20:55:26.276825Z"
                }
            ]
        },
        {
            "offerId": "e32f35ad-3d32-439d-94db-8c36a40ddbd1",
            "collectorId": "80000000110",
            "states": [
                {
                    "name": "OPT_IN",
                    "value": "OPTED_IN",
                    "properties": {},
                    "updatedAt": "2021-05-31T16:33:26.201783Z"
                },
                {
                    "name": "SAVE",
                    "value": "SAVED",
                    "properties": {},
                    "updatedAt": "2021-05-31T16:33:26.201759Z"
                }
            ]
        },
        {
            "offerId": "0095056b-b931-4431-8292-cd54f4986445",
            "collectorId": "80000000110",
            "states": [
                {
                    "name": "OPT_IN",
                    "value": "OPTED_IN",
                    "properties": {},
                    "updatedAt": "2021-05-21T14:53:47.293585Z"
                },
                {
                    "name": "SAVE",
                    "value": "SAVED",
                    "properties": {},
                    "updatedAt": "2021-05-21T14:53:47.293537Z"
                }
            ]
        }
    ],
    "returnedCount": 3
}

Response properties

Property	Description
`offerId`	The unique ID for the returned offers. Example: `"951d9a70-4cf8-41b1-a01e-7953f069f527"`
`collectorId`	The Collector’s AIR MILES account number. Example: `"80000000110"`
`states`	The opt-in/saved status of the offers found for an individual Collector. Usually offers will show both the “Saved” and “Opt-in” statuses, but in certain scenarios, the Collector may have unsaved an offer they opted-into earlier. Example: `[{"name": "SAVE","value": "SAVED"}]` name The name of the state being returned. e.g., `"SAVE"` value The current state value. e.g., `"SAVED"` properties An optional field which can be defined by the partner. (Note: This field is a string-to-any map which can map any string field to any value.) e.g., `{"timesUsedOffer":5,"savedOnChannel":"internal:amrp:mobile"}` updatedAt The date/time the offer state was last updated. (ISO-8601) e.g., `"2021-07-07T20:55:26.276825Z"`

Response codes

Code	Description
`200`	Request Successful
`400`	Bad Request
`401`	Unauthorized
`404`	Record Not Found
`500`	Internal Server Error

3 - state-reader/GET

Used to return only the opted-in/saved offers from a list of submitted offers.

GET /offers/state-reader/v1/get

Take a look at our OpenAPI (Swagger-Spec) schema to learn more about the API calls.

Used to return only the opted-in/saved offers from a list of submitted offers. This is used to label which offers a Collector has opted-into/saved when displaying a full page of offers (which would includes both opted-in and non opted-in offers).

Sample request

curl -X GET 
  https://uat.airmilesapis.ca/offers/state-reader/v1/get?offerId=951d9a70-4cf8-41b1-a01e-7953f069f527&offerId=e32f35ad-3d32-439d-94db-8c36a40ddbd1&offerId=ebaa71b8-40d4-48dc-95e6-824dfffa1c4c \
  --header 'Content-Type: application/json' \
  --header 'x-correlation-id: bcf529ae-0de0-4ded-90f5-e050ce2df0e3' \
  --header 'x-origin-client: external:partner:web' \
  --header 'x-local-time: 2020-05-30T23:59:59' \
  --header 'Authorization: Bearer LQoD0gWJK7l9znrmsGksWxbvIEx9a8zXkw...' \
  --data-raw ''

Request headers

Header	Description
`Content-Type`	Indicates the media type of the resource.
`x-correlation-id`	The unique ID for tracing the request across the system.
`x-origin-client`	Name of the Client and Channel. Example: `external:shell:web`
`x-local-time`	Local time of the client, excluding the timezone. Example: `2021-01-07T16.59:00`

Query parameters

Parameter	Description
`offerId`	The unique offer ID’s for all offers submitted. Example: `?offerId={OFFER_ID_1}&offerId={OFFER_ID_2}…`

Sample response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Mon, 29 Oct 2018 15:27:34 GMT
{
    "offers": [
        {
            "offerId": "951d9a70-4cf8-41b1-a01e-7953f069f527",
            "collectorId": "80000000110",
            "states": [
                {
                    "name": "OPT_IN",
                    "value": "OPTED_IN",
                    "properties": {},
                    "updatedAt": "2021-07-07T20:55:26.276917Z"
                },
                {
                    "name": "SAVE",
                    "value": "SAVED",
                    "properties": {},
                    "updatedAt": "2021-07-07T20:55:26.276825Z"
                }
            ]
        },
        {
            "offerId": "e32f35ad-3d32-439d-94db-8c36a40ddbd1",
            "collectorId": "80000000110",
            "states": [
                {
                    "name": "OPT_IN",
                    "value": "OPTED_IN",
                    "properties": {},
                    "updatedAt": "2021-05-31T16:33:26.201783Z"
                },
                {
                    "name": "SAVE",
                    "value": "SAVED",
                    "properties": {},
                    "updatedAt": "2021-05-31T16:33:26.201759Z"
                }
            ]
        }
    ],
    "requestedCount": 3,
    "returnedCount": 2
}

Response properties

Parameter	Description
`offerId`	The unique ID for the offers returned by the `find` call. Example: `"951d9a70-4cf8-41b1-a01e-7953f069f527"`
`collectorId`	The Collector’s AIR MILES account number. Example: `"80000000110"` (Must be 11 digits in length and must start with an 8)
`states`	The opt-in/saved status of the offers found for an individual Collector. Example: `[{"name": "SAVE","value": "SAVED"}]` name The name of the state being returned. e.g., `"SAVE"` value The current state value. e.g., `"SAVED"` properties An optional field which can be defined by the partner. (Note: This field is a string-to-any map which can map any string field to any value.) e.g., `{"timesUsedOffer":5,"savedOnChannel":"internal:amrp:mobile"}` updatedAt The date/time the offer state was last updated. (ISO-8601) e.g., `"2021-07-07T20:55:26.276825Z"`

Response codes

Code	Description
`200`	Request Successful
`400`	Bad Request
`401`	Unauthorized
`404`	Record Not Found
`500`	Internal Server Error

4 - state-reader/COUNT

Used to return the total number of offers a Collector has opted-into/saved.

GET /offers/state-reader/v1/count

Take a look at our OpenAPI (Swagger-Spec) schema to learn more about the API calls.

Used to return the total number of offers a Collector has opted-into/saved. This is used for displaying a small numerical icon on a label or button within your website or mobile app.

Sample request

curl -X GET 
  https://cert.airmilesapis.ca/offers/state-reader/v1/count \
  --header 'Content-Type: application/json' \
  --header 'x-correlation-id: acd31d3c-f486-4092-9c07-1b82632829ed' \
  --header 'x-origin-client: external:partner:web' \
  --header 'x-local-time: 2021-07-07T23:59:59' \
  --header 'Authorization: Bearer LQoD0gWJK7l9znrmsGksWxbvIEx9a8zXkw...' \
  --data-raw ''

Query parameters

Parameter	Description
`state`	The state types you want to retrieve. Example: `OPT_IN:OPTED_IN`
`partnerId`	The unique ID of the partner.
`region`	The Collector region.

Sample response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Mon, 29 Oct 2018 15:27:34 GMT
{
    "count": 3
}

Response properties

Property	Description
`count`	The total number of offers a Collector has opted-into/saved. Example: `3`

Response codes

Code	Description
`200`	Request Successful
`400`	Bad Request
`401`	Unauthorized
`404`	Record Not Found
`500`	Internal Server Error

5 - state-writer/PUT

Used to update the Collector’s opt-in status for an AIR MILES offer.

PUT /offers/state-reader/v1/put

Take a look at our OpenAPI (Swagger-Spec) schema to learn more about the API calls.

Used to update the Collector’s opt-in status for an AIR MILES offer selected within your website or mobile app. This ensures that the Collector’s opt-in status is synchronized between your list of offers and the AIR MILES system.

Sample request

curl -X PUT 
  https://uat.airmilesapis.ca/offers/state-writer/v1/put \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'x-correlation-id: bcf529ae-0de0-4ded-90f5-e050ce2df0e3' \
  --header 'x-origin-client: external:partner:web' \
  --header 'Authorization: Bearer LQoD0gWJK7l9znrmsGksWxbvIEx9a8zXkw...' \
  --data-raw '{
    "stateChanges": [
        {
            "offerId": "951d9a70-4cf8-41b1-a01e-7953f069f527",
            "states": [
                {
                    "name": "SAVE",
                    "value": "SAVED"
                },
                {
                    "name": "OPT_IN",
                    "value": "OPTED_IN"
                }
            ]
        }
    ]
}'

Request headers

Header	Description
`Content-Type`	Indicates the media type of the resource.
`x-correlation-id`	The unique ID for tracing the request across the system.
`x-origin-client`	Name of the Client and Channel. Example: `external:shell:web`
`x-local-time`	Local time of the client, excluding the timezone. Example: `2021-01-07T16.59:00`

Request properties

* Required field

Property Description

Property	Description
`offerId`*	The unique ID for the offer being updated. Example: `"951d9a70-4cf8-41b1-a01e-7953f069f527"`
`states`*	The states being updated in the API `PUT` request. Example: `[{"name": "SAVE","value": "SAVED"}]` name* The name of the state being updated. e.g., `"SAVE"` value* The new state value being applied. e.g., `"SAVED"` properties An optional field which can be defined by the partner. (Note: This field is a string-to-any map which can map any string field to any value.) e.g., `{"timesUsedOffer":5,"savedOnChannel":"internal:amrp:mobile"}`

offerId*

The unique ID for the offer being updated.

Example: "951d9a70-4cf8-41b1-a01e-7953f069f527"

states*

The states being updated in the API PUT request.

Example:

[{"name": "SAVE","value": "SAVED"}]

name*: The name of the state being updated.; e.g., "SAVE"
value*: The new state value being applied.; e.g., "SAVED"
properties: An optional field which can be defined by the partner.
(Note: This field is a string-to-any map which can map any string field to any value.); e.g., {"timesUsedOffer":5,"savedOnChannel":"internal:amrp:mobile"}

Sample response

HTTP/1.1 200 OK

Response codes

Code	Description
`204`	Request Successful
`400`	Bad Request
`401`	Unauthorized
`404`	Record Not Found
`500`	Internal Server Error