Retrieve Account API Documentation

v2Showing BAEC specific information

The Retrieve Account endpoint enables a member to retrieve their account details. The endpoint also allows a partner (the caller of the service) to filter information based on what has been requested. If nothing is explicitly specified then the entire response is returned as per the service response contract.

Business Context

Here’s the process flow:

Retrieve Account Flow

  • An identified member, for whom the partner has a valid access token, initiates a journey in the partner application.
  • The partner receives the member’s request and invokes the Retrieve Account endpoint, providing a request that contains the member’s access token, programme name and membership number.
  • The Retrieve Account endpoint receives and processes the request, returning an appropriate response or error.
  • The partner finalises processing of account, presenting it in an appropriate manner to the member.
  • The member continues their journey in the partner application.

Important Technical Notes

In order to call Retrieve Account, you have to follow the Member Authentication flow. The following steps are performed by the Retrieve Account application:

  • Default values are not assigned to elements that have not been supplied within a request message
  • Request elements are not stored

Pre-Conditions

  • The partner must have a valid API key to access the Retrieve Account endpoint
  • An Access Token must be supplied in order to use this service.

Post Conditions

Success outcome: Account details are returned in the endpoint response message.

Error outcome: Service error is returned.

Service Details

URI Parameters

Production Endpoint:

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

Example

https://api.avios.com/v2/programmes/BAEC/account?api_key=abcdefabcdefabcdefabcdef
NameTypeDescriptionExample
version
Required
StringThe version of the endpoint which will be confirmed during the on-boarding process.
Format: Alphanumeric v
V2
Programme-identifier
Required
StringThe loyalty programme that holds an account. This would have been provided to the partner as part of the IAGL Avios API partner on-boarding process along with the API key and Mashery credentials.
Format: Alphabetic only. Min length = 1, Max Length = 20.
BAEC
api_key
Required
StringThe partner API Key provided during initial partner configuration within Loyalty Programme systems as part of the standard partner on-boarding process.
Format: alpha-numeric. Min length = 24, Max Length = 24
abcdefabcdefabcdefabcdef

Request Header

NameTypeDescriptionExample
Accept
Optional
StringThe Accept request-header field specifies certain media types, which are acceptable for the response. Restricted to application/json.
Format: application/< content-type >
application/json
Authorization
Required
StringThe OAUTH Access Token returned from a successful ‘Create Token API’ call. The Access Token is issued on a per Partner, per Member basis at the point of successful Member Identification.
Format: JWT token
ba_client_applicationName
Required
StringName of the client application connecting to the BAEC members database. This name is the same for all partners.
Format: For all partners, the value should be AviosAPIPartners
AviosAPIPartners
X-Forwarded-For
Optional
StringIdentifies the originating IP address of the member.
Format: Valid IP address
192.168.69.63
X-Agent-Id
Optional
StringAn agent Id represents the agent name/user name/login id for offline channels like call centres.
Format: Alphanumeric
Masanobu.Fukuoka

Response Elements

The elements that make up the response message are detailed in the following table.

Examples of Responses

The following shows 2 examples of responses generated by the Retrieve Account endpoint:

Example 1. Full account data returned:

{
  "accountType": "INDIVIDUAL",
  "accountStatus": "ACTIVE",
  "balance": {
    "amount": 100000,
NameTypeDescription
accountType
Present
StringRepresents the type of account.Will be present only when it is requested for. Possible values are: INDIVIDUAL HOUSEHOLD
Format: Enumeration
accountStatus
Present
StringRepresents the account status..
Format: Alphabetic only. Min length: 1, Max length: 10.
lastActivityDate
Optional
DateRepresents the last transaction date of member..
Format: YYYY-MM-DD ISO-8601
balance
Present
Complex type 0..1Encapsulates the balance information for the account..
balance.amount
Present
IntegerRepresents the AVIOS amount the account has.
Format: Numeric
balance.currency
Present
Complex type 0..1
balance.currency.currencyCode
Present
StringThe currency code. Possible value is “AVIOS”.
Format: Enumeration

Exception Message Elements

The following shows an example of an error response generated by the Retrieve Account endpoint:

Example of an Error Response

{
  "code": "REQUEST_INVALID",
  "businessMessage": "Request Invalid",
  "developerMessage": "Request Invalid",
  "developerLink": "https://developer.iagloyalty.com/docs",

Example 2: Note: below errors will differ from other errors with their structure and will come with “error” element as parent of error response:

  1. SYSTEM_UNAVAILABLE
  2. DEVELOPER_NOT_AUTHORIZED
  3. DEVELOPER_INACTIVE
  4. USAGE_RATE_EXCEEDED
  5. USAGE_RATE_LIMIT_EXCEEDED
  6. SSL_REQUIRED
  7. GATEWAY_TIMEOUT
{
  "error": {
    "code": "GATEWAY_TIMEOUT",
    "businessMessage": "Request Unauthorized",
    "developerMessage": "Request Unauthorized",
NameTypeDescription
code
Present
StringError code. Example: REQUEST_INVALID
Format: Alphabetic plus underscore (
businessMessage
Present
StringA business level message describing the error which has occurred. Example: Request Invalid
Format: Alphabetic
developerMessage
Conditional
StringA more technical message describing the error which has occurred.
Format: Alphabetic
developerLink
Present
StringA link to supporting documentation for this API. Example: https://developer.iagloyalty.com/docs
Format: Alphabetic plus colon (:), oblique (/), dash (-), underscore (
childError
Conditional
Array of complex type 0. .nPresent for certain errors (e.g. validation) where more than error may have occurred.
childError.code
Present
StringThe error code for the child error (if returned). Example: DATA_INVALID
Format: Alphabetic plus underscore (
childError.path
Conditional
StringIdentifies the element in the request which has caused the error to occur. This will not come in case of any of the authorisation header elements are invalid or missing.
Format: Alphabetic plus period (.), oblique (/), open bracket (
childError.businessMessage
Present
StringA business level message describing the error which has occurred. Example: Programme not supported
Format: Alphabetic
childError.developerMessage
Conditional
StringA more technical message describing the error which has occurred.
Format: Alphabetic
childError.developerLink
Present
StringA link to supporting documentation for this API. Example: https://developer.iagloyalty.com/docs
Format: Alphabetic plus colon (:), oblique (/), dash (-), underscore (

Error Codes

The elements that make up the error messages are detailed in the following table:

Http Status CodeDescription
400
REQUEST_INVALID
DATA_INVALID
Authorization Header is missing Bearer Keyword.
400
REQUEST_INVALID
MANDATORY_DATA_MISSING
The authorization header or ba_client_applicationName header is empty.
400
REQUEST_INVALID
PROGRAMME_INVALID
Programme ID is invalid.
401
REQUEST_UNAUTHORIZED
TOKEN_INVALID
OAUTH token (authorization header) is invalid or expired, Authorization Header with (Bearer: ) keyword, or a BA-dependent service is unavailable.