API Library

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.

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