Retrieve Programme API Documentation

v1

The Retrieve Programme endpoint enables a Partner to retrieve programmes supported by the Avios currency. The endpoint returns programme information as part of successful response.

The objectives of this service are:

  • To retrieve the complete list of programmes supported by Avios currency.
  • To retrieve a programme by specifying the programme identifier.
  • To retrieve the list of programmes which belongs to provided location identifier.
  • To retrieve the list of programmes by specifying a membership identifier, e.g. return the list of programmes associated with a membership.

For Partners attempting to simply return the details of one programme, the only URI parameter that is required is the programme-identifier.

For Partners that want all programmes associated with a certain area code, they can include the specific area code in the endpoint.

Partners that want to return a list of programmes associated with a certain member, they simply include the membership-identifier in the endpoint.

Business Context

A summary of the process flow is as follows:

Retrieve Programme Flow

Retrieve Programmes Flow

  • The Partner calls the Retrieve Membership endpoint to retrieve membership details.
  • The details of the membership are returned along with additional links to retrieve associated programme information.
  • Partner clicks the provided link to retrieve programme information.
  • Retrieve Programme endpoint is called and the programme details are returned.

Important Technical Notes

  • All enumerated values must be upper case.

Pre-conditions

  • The partner must have a valid API key to access the Retrieve Programme API

Post-conditions

Success outcome: HTTP status code 200 is returned along with details of the programme.

Error outcome: An error is returned.

Service Details

URI Parameters

Production Endpoints:

Making a call to the API using only programme-identifier:

'GET https://api.avios.com/{version}/programmes/{programme-identifier}?api_key={api_key}'

Example

https://api.avios.com/v1/programmes/ATRP?api_key=abcdefabcdefabcdefabcdef

Making a call to the API using location-identifier to narrow the search:

'GET https://api.avios.com/{version}/programmes?location-identifier={location-identifier}&api_key={api_key}'

Example

https://api.avios.com/test/v1/programmes?location-identifier=GB&api_key=Abcdefabcdefabcdefabcdef

Making a call to the API using only the membership-identifier:

'GET https://api.avios.com/{version}/programmes?membership-identifier={membership-identifier}&api_key={api_key}'

Example

https://api.avios.com/v1/programmes?membership-identifier=3081470000000000&api_key=Abcdefabcdefabcdefabcdef
NameData typeDescriptionExample
version
Required
StringThe version of the API which will be confirmed during the on-boarding process.
Format: Alphanumeric v
v1
programme-identifier
Optional
StringThe identifier for the loyalty programme for which detailed information needs to be fetched.
Format: Alphabetic with max length: 20
ATRP, BAEC, IBP, PUNTO, AERCLUB
location-identifier
Optional
StringRepresents the location (Country), the programmes for which have to be retrieved. API doesn’t validate if country code conforms with ISO 3166 standard.
Format: Min length = 2 Max length = 2 ISO 3166 Country code
GB
membership-identifier
Optional
StringThe 16-digit membership number starting with 308147.
Format: Numeric only. Min length = 16 Max Length = 24
3081471234550241
api_key
Required
StringThe API key provided during the partner configuration which takes place as part of the partner on-boarding process.
Format: Alphanumeric only. Min length= 24, Max length= 24
abcdefabcdefabcdefabcdef

Request Headers

NameData typeDescriptionExample
Accept
Optional
StringThe Accept request header is used to specify media types which are acceptable for the response. Currently this API only supports application/json
Format: application/json
application/json
X-Forwarded-For
Optional
StringThe IP address of the end customer.
Format: Comma separated Valid IP addresses
172.17.1.1, 172.17.1.2

Response Message Elements

The following are examples of successful responses from the Retrieve Programme API:

{
  "name": "AVIOS AGL",
  "_links": {
    "self": {
      "href": "https://api.avios.com/test/v1/programmes/ATRP"
{
  "size": "2",
  "programmes": [
    {
      "identifier": "ATRP",

A response from the API containing only a singular programme will have the following response elements:

NameData typeDescription
name
Present
StringThe name of the loyalty programme. This element is present only when the retrieval of programme is based on programme identifier.
Format: Alphabets with space Max length: 100
programmePartner
Conditional
Complex Type 0..1Represents the partner associated with the programme. This element is present only when the retrieval of programme is based on programme identifier. This element won’t be visible if programme isn’t associated with any partner.
programmePartner.organisation
Present
Complex Type 1..1Represents the organisation information of the partner. This element is present only when the retrieval of programme is based on programme identifier
programmePartner.organisation.identifier
Present
StringPartner identifier
Format: Alphanumeric with max length 20
programmePartner.organisation.organisationName
Present
StringPartner organisation name
Format: Alphanumeric with max length 100
_
Present
Complex Type 1..1Represents the hateoas link
_
Present
Complex type 1..1Contains the self-link, the complete request URL
_
Present
StringContains link to self.
Format: Alphanumeric plus colon (:), oblique (/), dash (-), underscore (

And for responses containing multiple programmes:

NameTypeDescription
programmes
Present
Array of Complex Type 1..nRepresents the programme information. This element is present when all programmes are retrieved or programmes are retrieved based on location identifier and/or membership identifier.
programmes.identifier
Conditional
StringThe identifier of the loyalty programme. Possible values could be: ATRP BAEC IBPL AERCLUB PUNTO ISSLP Won’t be visible if not existing location identifier was passed in request or there aren’t any programmes associated with that country or programme isn’t associated with membership identifier.
Format: Enumeration
programmes.name
Conditional
StringThe name of the loyalty programme. Won’t be visible if not existing location identifier was passed in request or there aren’t any programmes associated with that country or programme isn’t associated with membership identifier.
Format: Alphabets with space. Max length: 100
programmes.programmePartner
Conditional
Complex Type 0..1Represents the partner details associated with the programme. Won’t be visible if not existing location identifier was passed in request or there aren’t any programmes associated with that country or programme isn’t associated with membership identifier.
programmes.programmePartner.organisation
Present
Complex Type 1..1Represents the organisation information of the partner.
programmes.programmePartner.organisation.identifier
Present
StringPartner identifier.
Format: Alphanumeric. Max length: 20
programmes.programmePartner.organisation.organisationName
Present
StringPartner organisation name.
Format: Alphanumeric with with special symbol space ( ). Max length: 100
size
Present
IntegerPresent only when the retrieval of programmes is not based on programme identifier. This represents the number of programmes retrieved.
Format: Numeric. Max length: 2 Max value: 99
_
Present
Complex Type 1..1Represents the hateoas link.
_
Present
Complex Type 1..1Contains the self-link, the complete request URL.
_
Present
StringContains the self-link.
Format: Alphanumeric plus colon (:), oblique (/), dash (-), underscore (

Exception Message Elements

The following is an example of an unsuccessful response from the Retrieve Programme API:

{
  "code": "PROGRAMME_NOT_FOUND",
  "businessMessage": "Programme Not Found",
  "developerMessage": "Programme Not Found",
  "developerLink": "https://developer.iagloyalty.com/docs"
NameData typeDescription
code
Present
StringError code. E.g: PROGRAMME_NOT_FOUND
Format: Alphabet plus underscore (
businessMessage
Present
StringError message to business. E.g.: Programme Not Found
Format: Alphabets with space
developerMessage
Conditional
StringError message specific to client developer
Format: Alphabets with space
developerLink
Present
StringA URL link to a web page containing more detailed information about the error code.E.g. : https://developer.iagloyalty.com/docs
Format: Alphabets plus colon (:), oblique (/), dash (-), underscore (
childError
Conditional
Array of complex type 0..nWill only be present if an error has been detected and reported by the API.
childError.code
Present
StringError code. E.g: DATA_INVALID
Format: Alphabet plus underscore (
childError.path
Conditional
StringPath of the node on which error occurred.
Format: Alphabets plus period (.), oblique (/), open bracket (
childError.businessMessage
Present
StringError message to business. E.g: Data Invalid
Format: Alphabets with space
childError.developerMessage
Conditional
StringError message specific to client developer.
Format: Alphabets with space
childError.developerLink
Present
StringA URL link to a web page containing more detailed information about the error code. e.g.: https://developer.iagloyalty.com/docs
Format: Alphabetic plus colon (:), oblique (/), dash (-), underscore (

Error Codes

HTTP Status CodeDescription
400
REQUEST_INVALID
DATA_INVALID
In case the path and query parameters do not follow the format restriction.
400
REQUEST_INVALID
MEMBERSHIP_IDENTIFIER_INVALID
The specified membership identifier is not valid.
400
PROGRAMME_NOT_FOUND
When there is no record for the provided programme identifier.