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

API Library

Table of contents

1. Health Check
2. Collector Request
3. Sponsor Request

This section includes the three (3) Transaction History API endpoints listed below. Each page offers a brief summary of the API endpoint in question, common use-case scenarios, and sample request/response messages with response codes.

API endpoints

Health Check

Test and confirm that the Transaction History API is up and ready to process requests.

Collector Request

Retrieve the transaction history for a logged in Collector.

Sponsor Request

Retrieve the transaction history for a specified Collector number and filter by sponsor.

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

Status codes

Status Code	Description
`200`	The transaction was successful.
`401`	The Collector account is not active.
`408`	The transaction timed out.
`401`	The Collector number is invalid.
`400`	A mistake was made when submitting the request. Please correct the error and try again.
`503`	The system is unavailable due to scheduled maintenance. No requests can be sent.
`500`	An unknown error occurred
none	No valid Bearer token present. Please generate a valid Bearer token and submit to continue.

1 - Health Check

Test and confirm that the Transaction History API is up and ready to process requests.

GET /transaction-history/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.

Note

To receive a Bearer token and authorize your request, use the client_id and client_secret provided to you by AIR MILES.

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/transaction-history/health \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...' \
  --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
{
    "status": "up"
}

Status codes

Status Code	Description
`200`	The transaction was successful.
`408`	The transaction timed out.
`400`	A mistake was made when submitting the request. Please correct the error and try again.
`503`	The system is unavailable due to scheduled maintenance. No requests can be sent.
`500`	An unknown error occurred.
none	No valid Bearer token present. Please generate a valid Bearer token and submit to continue.

2 - Collector Request

Retrieve the transaction history for a logged in Collector.

GET /transaction-history/cards

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

Important

This API call is not intended for manual search queries, it only retrieves the transaction history for a Collector who is logged in.

This endpoint is used to retrieve the transaction history for a Collector who is logged in to the website or the mobile application. A date range must be provided (with a start and end-date), and this will return results for all sponsors the Collector has transacted with during this time period.

Note

The Collector number is embedded in the Bearer access token automatically and therefore does not need to be included in the request itself.

Sample request

curl -X GET \
  https://cert.airmilesapis.ca/transaction-history/cards?from=2018-01-01T00:16:45.052035Z&to=2019-10-01T00:16:45.052035Z&page=0&size=2&sort=transactionDate,desc&sort=sponsorCode,asc \
  --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`

Query parameters

Parameter	Description
`from`	The start of the search date range. Example: `2018-01-01T00:16:45.052035Z` (The date range is limited to 2 years)
`to`	The end of the search date range. Example: `2019-10-01T00:16:45.052035Z` (The date range is limited to 2 years)
`page`	The results page to start with. Example: `0`
`size`	The number of transactions per page. Example: `10`
`sort`	Sort by field, ascending or descending. You can include up to 3 sequential sort parameters. Example: `transactionDate,desc`

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
{
  "_embedded": {
    "genericActivityDtoList": [
      {
        "transactionId": "bfc52daa-b1ec-44fb-b8e2-babc6f93395e",
        "memberId": 80000000001,
        "cardNumber": "80000000001",
        "activityType": "ISSUANCE",
        "transactionDate": "2019-01-20T13:15:57.000Z",
        "postingDate": "2019-03-20T13:15:57.000Z",
        "transactionDescription": "P&S Goodwill",
        "transactionValue": 50,
        "cashMiles": 44,
        "dreamMiles": 6,
        "cashRatio": 0.88,
        "dreamRatio": 0.12,
        "externalReferenceNumber": "07753481468",
        "externalReferenceType": null,
        "channel": "ETS",
        "initiatorId": "ETSets_user",
        "sponsorCode": "AIRI",
        "sponsorDescriptionEnglish": "AIR MILE TRAVEL INSURANCE",
        "sponsorDescriptionFrench": "ASSURANCE VOYAGE AIR MILES",
        "offerClass": "BONUS",
        "offerCode": "GOODWILL",
        "offerDescriptionEnglish": "P&S Goodwill",
        "offerDescriptionFrench": "AJUSTEMENT",
        "locationCode": "",
        "locationDescription": "",
        "redemptionStatus": null
      },
      {
        "transactionId": "a27c7827-a865-4425-a407-d1969b3ddfc5",
        "memberId": 80000000001,
        "cardNumber": "80000000001",
        "activityType": "ISSUANCE",
        "transactionDate": "2019-01-07T17:03:49.000Z",
        "postingDate": "2019-03-01T17:03:49.000Z",
        "transactionDescription": "AIR MILES Travel Insurance",
        "transactionValue": 50,
        "cashMiles": 14,
        "dreamMiles": 36,
        "cashRatio": 0.29,
        "dreamRatio": 0.71,
        "externalReferenceNumber": "96561512670",
        "externalReferenceType": null,
        "channel": "ETS",
        "initiatorId": "ETSets_user",
        "sponsorCode": "AIRI",
        "sponsorDescriptionEnglish": "AIR MILE TRAVEL INSURANCE",
        "sponsorDescriptionFrench": "ASSURANCE VOYAGE AIR MILES",
        "offerClass": "BONUS",
        "offerCode": "TSRTRIPC",
        "offerDescriptionEnglish": "AIR MILES Travel Insurance",
        "offerDescriptionFrench": "RECLAMATION D'ASSURANCE",
        "locationCode": "",
        "locationDescription": "",
        "redemptionStatus": null
      }
    ]
  },
  "_links": {
    "first": {
      "href": "https://cert.airmilesapis.ca/transaction-history/cards?from=2018-01-01T00:16:45.052035Z&to=2019-10-01T00:16:45.052035Z&page=0&size=2&sort=transactionDate,desc&sort=sponsorCode,asc"
    },
    "self": {
      "href": "https://cert.airmilesapis.ca/transaction-history/cards?from=2018-01-01T00:16:45.052035Z&to=2019-10-01T00:16:45.052035Z&page=0&size=2&sort=transactionDate,desc&sort=sponsorCode,asc"
    },
    "next": {
      "href": "https://cert.airmilesapis.ca/transaction-history/cards?from=2018-01-01T00:16:45.052035Z&to=2019-10-01T00:16:45.052035Z&page=1&size=2&sort=transactionDate,desc&sort=sponsorCode,asc"
    },
    "last": {
      "href": "https://cert.airmilesapis.ca/transaction-history/cards?from=2018-01-01T00:16:45.052035Z&to=2019-10-01T00:16:45.052035Z&page=22&size=2&sort=transactionDate,desc&sort=sponsorCode,asc"
    }
  },
  "page": {
    "size": 2,
    "totalElements": 45,
    "totalPages": 23,
    "number": 0
  }
}

Status codes

Status Code	Description
`200`	The transaction was successful.
`401`	The Collector account is not active.
`408`	The transaction timed out.
`401`	The Collector number is invalid.
`400`	A mistake was made when submitting the request. Please correct the error and try again.
`503`	The system is unavailable due to scheduled maintenance. No requests can be sent.
`500`	An unknown error occurred.
none	No valid Bearer token present. Please generate a valid Bearer token and submit to continue.

3 - Sponsor Request

Retrieve the transaction history for a specified Collector number and filter by sponsor.

GET /transaction-history/sponsors

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

This endpoint is used to retrieve the transaction history for a specified Collector and filtered by sponsor. A date range must be provided (with a start and end-date), and at least one sponsor and a single Collector number. This will return the Collector’s transaction history at the sponsor, for the time period specified above.

Note

To receive a Bearer token and authorize your request, use the client_id and client_secret provided to you by AIR MILES.

Sample request

curl -X GET \
  https://cert.airmilesapis.ca/transaction-history/sponsors?from=2018-01-01T00:16:45.052035Z&to=2019-10-01T00:16:45.052035Z&page=0&size=2&sort=transactionDate,desc&sort=sponsorCode,asc&sponsorList=ABC,CBA&collectorNumber=80000000001 \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCI...' \
  --header 'Channel-Code: MOBAPP' \
  --header 'Accept-Language: EN'

Header parameters

Parameter	Description
Content-Type	Default: `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`

Query parameters

Parameter	Description
`from`	The start of the search date range. Example: `2018-01-01T00:16:45.052035Z` (The date range is limited to 2 years)
`to`	The end of the search date range. Example: `2019-10-01T00:16:45.052035Z` (The date range is limited to 2 years)
`page`	The results page to start with. Example: `0`
`size`	The number of transactions per page. Example: `10`
`sort`	Sort by field, ascending or descending. You can include up to 3 sequential sort parameters. Example: `transactionDate,desc`
`sponsorList`	The ID(s) of the sponsor(s) you wish to search by. Example: `ABC,CBA` (You may include multiple sponsors, comma delineated)
`collectorNumber`	The Collector number you wish to search for. Example: `80000000001`

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
{
  "_embedded": {
    "genericActivityDtoList": [
      {
        "transactionId": "a8354c14-6533-4550-b25d-b3e8c07340e3",
        "memberId": 80000000001,
        "cardNumber": "80000000001",
        "activityType": "ISSUANCE",
        "transactionDate": "2018-11-21T21:55:07",
        "postingDate": "2018-12-08T21:55:07",
        "transactionDescription": "MILLES DE RECOMPENSE EN PRIME",
        "transactionValue": 6,
        "cashMiles": 3,
        "dreamMiles": 3,
        "cashRatio": 0.56,
        "dreamRatio": 0.44,
        "externalReferenceNumber": "66367295746",
        "externalReferenceType": null,
        "channel": "WEB",
        "initiatorId": "WEB423672",
        "sponsorCode": "AMXJ",
        "sponsorDescriptionEnglish": "AMEX AIR MILES BUSINESS",
        "sponsorDescriptionFrench": "CARTE POUR ENTREPRISE AMEX",
        "offerClass": "BONUS",
        "offerCode": "MPOOL",
        "offerDescriptionEnglish": "WELCOME BONUS",
        "offerDescriptionFrench": "MILLES DE RECOMPENSE EN PRIME",
        "locationCode": "",
        "locationDescription": null,
        "redemptionStatus": null
      },
      {
        "transactionId": "2cd4b826-6f7a-4e93-87ac-82c215bd8fe5",
        "memberId": 80000000001,
        "cardNumber": "80000000001",
        "activityType": "ISSUANCE",
        "transactionDate": "2018-11-06T20:33:54",
        "postingDate": "2018-11-26T20:33:54",
        "transactionDescription": "GAGNANT(E) DU CONCOURS",
        "transactionValue": 6,
        "cashMiles": 2,
        "dreamMiles": 4,
        "cashRatio": 0.37,
        "dreamRatio": 0.63,
        "externalReferenceNumber": "14493747740",
        "externalReferenceType": null,
        "channel": "BATCH",
        "initiatorId": "BATCH707530",
        "sponsorCode": "AMRP",
        "sponsorDescriptionEnglish": "AIR MILES REWARD PROGRAM",
        "sponsorDescriptionFrench": "PROGRAMME DE RECOMPENSE AIR MILES",
        "offerClass": "BONUS",
        "offerCode": "4352932T",
        "offerDescriptionEnglish": "Contest Winner",
        "offerDescriptionFrench": "GAGNANT(E) DU CONCOURS",
        "locationCode": "0705",
        "locationDescription": "TRANSAT",
        "redemptionStatus": null
      }
    ]
  },
    "_links": {
    "first": {
      "href": "https://cert.airmilesapis.ca/transaction-history/sponsors?from=2018-01-01T00:16:45.052035Z&to=2019-10-01T00:16:45.052035Z&page=0&size=2&sort=transactionDate,desc&sort=sponsorCode,asc&sponsorList=ABC,CBA&collectorNumber=80000000001"
    },
    "self": {
      "href": "https://cert.airmilesapis.ca/transaction-history/sponsors?from=2018-01-01T00:16:45.052035Z&to=2019-10-01T00:16:45.052035Z&page=0&size=2&sort=transactionDate,desc&sort=sponsorCode,asc&sponsorList=ABC,CBA&collectorNumber=80000000001"
    },
    "next": {
      "href": "https://cert.airmilesapis.ca/transaction-history/sponsors?from=2018-01-01T00:16:45.052035Z&to=2019-10-01T00:16:45.052035Z&page=1&size=2&sort=transactionDate,desc&sort=sponsorCode,asc&sponsorList=ABC,CBA&collectorNumber=80000000001"
    },
    "last": {
      "href": "https://cert.airmilesapis.ca/transaction-history/sponsors?from=2018-01-01T00:16:45.052035Z&to=2019-10-01T00:16:45.052035Z&page=9&size=2&sort=transactionDate,desc&sort=sponsorCode,asc&sponsorList=ABC,CBA&collectorNumber=80000000001"
    }
  },
  "page": {
    "size": 2,
    "totalElements": 19,
    "totalPages": 10,
    "number": 0
  }
}

Status codes

Status Code	Description
`200`	The transaction was successful.
`401`	The Collector account is not active.
`408`	The transaction timed out.
`401`	The Collector number is invalid.
`400`	A mistake was made when submitting the request. Please correct the error and try again.
`503`	The system is unavailable due to scheduled maintenance. No requests can be sent.
`500`	An unknown error occurred.
none	No valid Bearer token present. Please generate a valid Bearer token and submit to continue.