Retrieve Account API Documentation

v2Showing ATRP 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, a token must have been obtained via the Create Token endpoint. 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
  • The response is then filtered based on what information the caller of the service (i.e. Partner) has requested. If nothing is explicitly specified then the entire response as per the service response contract is returned.
  • 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.
  • A member identity must have been obtained.

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}/accounts/{account-identifier}?api_key={api_key}'

Example

https://api.avios.com/v2/programmes/ATRP/accounts/3081470000000000?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 Avios API partner on-boarding process along with the API key and Mashery credentials.
Format: Alphabetic only. Min length = 1, Max Length = 20.
ATRP
Account-identifier
Required
NumericMembership number starting with 308147.
Format: Numeric only. Min length = 16, Max Length = 24.
3081470000000000
fields
Optional
StringIdentifies the specific account element which Partner has requested. If nothing is specified the full set of account data is returned. Supported values: Balance, accountStatus, LastActivityDate, AccountType.
Format: Enumeration
AccountType
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 Access Token returned from a successful ‘Create Token' endpoint call. The Access Token is issued on a per Partner, per Member basis at the point of successful Member Identification.
Format: JWT token
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 3 examples of responses generated by the Retrieve Account endpoint:

Example 1. Full account data returned:

{
  "accountType": "INDIVIDUAL",
  "accountStatus": "ACTIVE",
  "lastActivityDate": "2016-05-31",
  "balance": {

Example 2. Only balance returned from account:

{
  "balance": {
    "amount": 100000,
    "currency": {
      "currencyCode": "AVIOS"

Example 3. Last activity date and balance information returned from account:

{
  "lastActivityDate": "2016-05-31",
  "balance": {
    "amount": 100000,
    "currency": {
NameTypeDescription
accountType
Optional
StringRepresents the type of account.Will be present only when it is requested for. Possible values are: INDIVIDUAL HOUSEHOLD
Format: Enumeration
accountStatus
Optional
StringRepresents the account status. Will be present only when it is requested for.
Format: Alphabetic only. Min length: 1, Max length: 10.
lastActivityDate
Optional
DateRepresents the last transaction date of member. Will be present only when it is requested for.
Format: YYYY-MM-DD ISO-8601
balance
Optional
Complex type 0..1Encapsulates the balance information for the account. Will be present only when it is requested for.
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.avios.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.avios.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.avios.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
ACCOUNT_NOT_FOUND
The account status is not valid for retrieval.