Retrieve Membership API Documentation

v2Showing ATRP specific information

The Retrieve Membership endpoint responds to valid requests by providing information related to a membership. The service returns membership details only if a valid Access Token for calling member/partner is provided in the request message. This Access Token can only be created by a member/partner having been authenticated.

The profile data returned by this service will have been previously retained within the Avios platform during either a Join Programme process, or an Update Membership process. The data returned in a successful response will contain Membership status and Member Profile along with account and programme details links.

This service will not return Security Profile or account/transaction data elements.

Business Context

A summary of the process flow is as follows:

Retrieve Membership Flow

During member interactions with a Partner channel membership data is required.
Member/Partner interactions trigger the need for Profile data in the Partner application. Partner invokes Retrieve Membership endpoint passing the appropriate membership identifier, Access Token and other required data elements.
The Retrieve Membership endpoint accesses the required membership data within the loyalty platform and if successful, passes this back to the partner (if unsuccessful, an appropriate error message is returned).
Partner renders the membership data as appropriate for its use, securely, in the Partner channel.
Member/partner continues his journey within the Partner application.

Important Technical Notes

Request elements are not stored within Avios systems, with the exception of logging for auditing purposes
Elements in the response message are all returned in upper case ASCII characters
The profile data returned by this service will have ASCII characters converted from accented characters which were previously supplied during either a Join Programme process, or an Update Membership process.

Pre-conditions

A Member Account must have been successfully created via Join Programme endpoint, or Avios channels
A Security Profile for the member account must have been created via Join Programme endpoint or Register Account endpoint
A valid Access Token for the member/partner must have been created before invoking this endpoint. Partner token must have been created with grant type as client_credentials and scope as retrieve_membership
Partner must have a valid API key to access Retrieve Membership endpoint

Post-conditions

Success outcome: Membership 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}/memberships/{account-identifier}?api_key={api_key}'

Example

https://api.avios.com/v2/memberships/3081470000000000?api_key=abcdefabcdefacbdefabcdef

Test Endpoint:

https://api.avios.com/test/{version}/memberships/{account-identifier}?api_key={api_key}

Name	Data type	Description
`version` Required	String	The version of the endpoint which will be confirmed during the on-boarding process. Format: Alphanumeric
`account-identifier` Required	String	The 16-digit membership number starting with 308147. Format: Numeric only. Min length = 16, Max Length = 24.
`api_key` Required	String	The partner API Key provided during initial partner configuration within Loyalty Programme systems as part of the standard partner on-boarding process. Format: As supplied by Avios during partner configuration, alpha-numeric. Min Length = 24, Max Length = 24.

Request Headers

Name	Data type	Description	Example
`Accept` Optional	String	The Accept request-header field is used to specify certain media types which are acceptable for the response. Only application/json is accepted currently. Format: Currently restricted to application/json	application/json
`Authorization` Required	String	An access token authorising the partner access to this API. Format: JWT Token	Bearer:eyJhbGcI1NiJ9
`X-Forwarded-For` Optional	String	The originating IP address of a consumer. Format: Valid IP address	172.17.1.1, 172.17.1.2
`X-Agent-ID` Optional	String	An agent Id represents the agent name/user name/login id for offline channels like call centres. Format: Alphanumeric. Min length: 2, Max length: 40.	Masanobu12Fukuoka

Response Elements

The following is an example of a response from the Retieve Membership endpoint.

{
  "membershipStatus": "ACTIVE",
  "member": {
    "person": {
      "name": {...

Name	Data type	Description
`membershipStatus` Present	String	Represents the membership status. Possible value is “ACTIVE” Format: Enumeration
`member` Present	Complex type	A complex type that represents the member within Avios systems. This type contains a person.
`member.person` Present	Complex type	A complex type that contains the member’s personal details within Avios systems.
`member.person.name` Present	Complex type	Contains the name of the member, split into various fields that represent a name in a recognised format. Title, forename, middle initial (if present), family name.
`member.person.name.title` Conditional	String	Title (Salutation) of the Loyalty programme member. If Title was provided during Join or update membership, it will be retrieved. Format: Alphabetic Max length: 30
`member.person.name.firstName` Present	String	First name (forename) of the Loyalty Programme member. May contain the following special characters: apostrophe (‘), hyphen (-), spaces. Format: Min Length:1, max Length: 25. Alphabetic plus apostrophe (‘), hyphen (-) and space.
`member.person.name.middleInitial` Conditional	String	Middle initial of the Loyalty Programme member. Will be present if previously supplied during a Join Programme API. Format: Max Length: 1. Alphabetic.
`member.person.name.familyName` Present	String	Surname (or last name) of the Loyalty Programme member. May contain the following special characters: apostrophe (‘), hyphen (-) and spaces. Format: Max Length: 40. Alphabetic plus apostrophe (‘), hyphen (-) and space.
`member.person.dateOfBirth` Conditional	Date	The member’s Date of Birth in ISO-8601 Calendar date format. Members who is older than 18 years old can only join loyalty programmes and this field will be present if a date of birth has been previously provided and is no earlier than 1700-04-01. Dates under 1700-04-01 will not be present even if was previously provided.
`member.person.gender` Present	String	An indicator of the gender of a member. API will derive the Gender of the member based on gender specific titles (Mr, Mrs, Ms, Miss, Dr, Lady, Sir, and Lord), if any other value will be provided in title element the Gender of the member will be set to NOTKNOWN. Will be one of the following: _MALE FEMALE NOT_KNOWN NOT_KNOWN Format: Enumeration.
`member.person.registeredIdentifier` Conditional	Complex type	This complex type represents the Identification document provided by the member. In some countries, for example South Africa, there is a requirement to collect recognised Identification when joining. This is typically the passport but could be another government issued Identification document. This element will be visible in the response if the country of residence is South Africa.
`Member.person.registeredIdentifier.token` Present	String	The passport number or other Identification Card issue number for the Identification provided by the member as part of the Join process. Format: Max length: 24. Alphanumeric.
`Member.person.registeredIdentifier.placeOfIssue` Present	Complex type	Place of issue of the identity document related to the token provided above.
`Member.person.registeredIdentifier.placeOfIssue.identifier` Present	String	Location identifier of the place where identification document has been issued. Format: Max length: 2, min length: 2. ISO 3166-1 two character alphabetic Country code.
`member.person.registeredIdentifier.placeOfIssue. type` Present	String	The type of location for place of issue. Case sensitive and will be “COUNTRY”. Format: Enumeration.
`member.person.registeredIdentifier.type` Present	String	Type of identification document. Will be one of the following: PASSPORT NATIONAL_IDENTITY_CARD Format: Enumeration.
`member.person.countryOfResidence` Conditional	String	The 2-digit ISO code for the country where the member is registered. This will be present in response if supplied during join or update membership details. Example: GB Format: ISO 2 digit. Max length :2
`member.person.locale` Present	Complex type	A complex type that represents the chosen locale of the Member.
`member.person.locale.languageCode` Present	String	If language code was not provided in join or update member API default ‘EN’ is assigned. Preferred language of the member for use within Avios systems and channels. Will be one of the following values: EN ES CA FR IT Format: ISO 639-1. Alphabetic 2 character language code. Max Length :2
`member.person.postalAddresses` Conditional	Complex type	A complex type that represents the Member’s postal addresses. This will be present in response if supplied during join or update membership details
`member.person.postalAddresses.preferredPostalAddress` Present	Complex type	A complex type representing the preferred postal address of the member.
`member.person.postalAddresses.preferredPostalAddress.type` Present	String	A string representing the type of the Member’s preferred postal address. Will be one of the following: PERSONAL Format: Enumeration
`member.person.postalAddresses.preferredPostalAddress.addressLine` Present	Array of string	An array of string values, each of which represents a line of the member’s preferred postal address, excluding postcode and country. For countries where postcode is not mandatory, at least two lines of address should be present. For countries where postcode is mandatory, at least one line ofaddress should be present. There will not be a comma (,) present at the end of each address line. Format: Max length: 30. Alphanumeric plus the following all ASCII printable special characters.
`member.person.postalAddresses.preferredPostalAddress.country` Present	String	Postal address country name. Example: UNITED KINGDOM Format: Alphabetic with special character space ( )
`member.person.postalAddresses.preferredPostalAddress.postCode` Conditional	String	The Postal code of address for the Member’s preferred postal address, if the address contains one this value will be present in the response. Please refer to the Country Address Rules document, which identifies the mandatory elements for each country. The postcode is returned without an embedded space. Example: RH109XA Format: Max length: 8. Alphanumeric
`member.person.postalAddresses.otherPostalAddress` Conditional	Array of Complex type	Other postal address details. Optional postal address in addition to the preferred postal address
`member.person.postalAddresses.otherPostalAddress.type` Present	String	Type of postal address. Will be one of the following: BUSINESS Format: Enumeration
`member.person.postalAddresses.otherPostalAddress.addressLine` Present	Array of string	An array of string values, each of which represents a line of the member’s other postal address, excluding postcode and country. For countries where postcode is not mandatory, at least two lines of address should be provided For countries where postcode is mandatory, at least one line of address should be provided There should not be a comma (,) at the end of each address line The request should follow JSON format for providing multiple address linesPlease refer to the Country Address Rules document, which identifies the mandatory elements for each country. Format: Max length: 30. Alphanumeric plus all ASCII printable special characters
`member.person.postalAddresses.otherPostalAddress.country` Present	String	Postal address country name. Example: UNITED KINGDOM Format: Alphabetic with space.
`member.person.postalAddresses.otherPostalAddress.postcode` Conditional	String	The Postal code of address for the Member’s other postal address, if the address contains one this value will be present in the response. The postcode is returned without an embedded space. Example: RH109XA Format: Max length: 8 Alphanumeric
`member.person.emailAddresses` Present	Complex type	A complex type representing the Member’s email addresses.
`member.person.emailAddresses.preferredEmailAddress` Present	Complex type	A complex type representing the Member’s preferred email address.
`member.person.emailAddresses.preferredEmailAddress.email` Present	String	Email address of the member. There may be only a single at-sign present. Also, all special characters can be specified before the at-sign and just minus (-) and period (.) after at-sign. Period (.) can’t be before at(@). Format: Alphanumeric Max length: 50 with special characters period (.), underscore , plus (+), minus (-) and at-sign (@), percentage (%).
`member.person.telecomAddresses` Conditional	Complex type	A complex type that represents a collection of Member’s fully elaborated telephone numbers, which include country and area codes. Area code and number will be combined in the response in a single field. This will be present in response if supplied during join or update membership details.
`member.person.telecomAddresses.preferredTelecomAddress` Present	Complex type	A complex type that represents a Member’s preferred telephone number.
`member.person.telecomAddresses.preferredTelecomAddress.countryCode` Present	String	The direct dialling code required to call the preferred telecom address from another country. Also referred to as the International Subscriber Dialling (ISD) code. This value will not be prefixed with leading zeros or a plus (+), for example UK telephone numbers will have a country code value of 44 Format: Numeric. Max length: 5. International dialling code.
`member.person.telecomAddresses.preferredTelecomAddress.number` Present	String	The member’s preferred telephone number (telecom address). This will include the area code but not the country code. Example.: 01924311750 Format: Max length: 15. Numeric.
`member.person.telecomAddresses.preferredTelecomAddress.type` Present	String	Telecom address type. Will be one of the following: BUSINESS PERSONAL Format: Enumeration.
`member.person.telecomAddresses.preferredTelecomAddress.deviceType` Present	String	Telecom address device type. Will be one of the following: PHONE MOBILE Format: Enumeration.
`member.person.telecomAddresses.otherTelecomAddress` Conditional	Array of complex type	Other telecom address in addition to the preferred telecom address. Will be visible if member will have more than one type of phone. A member could have more than one telephone number. Avios can store up to 3 telephone numbers for each member, including the preferred telecom address.
`member.person.telecomAddresses.otherTelecomAddress.countryCode` Present	String	Telecom addresses country code. The total string length of the countryCode, areaCode and the telephone number cannot exceed 15 characters. Format: Numeric characters
`member.person.telecomAddresses.otherTelecomAddress.number` Present	String	The body of the Member’s preferred phone number (Preferred Telecom Address). The total length of combination of the area code and the number cannot exceed 15 characters. Format: Max length: 15. Numeric characters.
`member.person.telecomAddresses.otherTelecomAddress.type` Present	String	Telecom addresses type. Case sensitive and must be one of the following: BUSINESS PERSONAL The following combinations of deviceType and type are accepted by the application: If deviceType = mobile and type = Personal, the telephone number is saved as a mobile phone. If deviceType = phone and type = Business, the telephone numberis saved as a work phone. If deviceType = phone and type = Personal, the telephone number is saved as a home phone.Any other combination will result in error. Format: Enumeration
`member.person.telecomAddresses.otherTelecomAddress.deviceType` Present	String	Telecom address device type. Must be one of the following: PHONE MOBILE This field and Type, described above, are interrelated as per the Description for the Type field above. Format: Enumeration
`member.person.marketingPreference` Conditional	Array of complex type	Member’s preference for receiving Avios marketing communications. This element can occur multiple times. API will return this element if it was specified with previously. For internal Avios use only.
`member.person.marketingPreference.campaignType` Present	String	Promotion activity of a product conducted by the Partner. Will be one of the following: TRAVEL_OFFERS PARTNER For internal Avios use only. Format: Enumeration
`member.person.marketingPreference.communicationChannel` Present	String	Channel of communication preferred by the member to receive marketing information. Will always be “POSTAL”. For internal Avios use only. Format: Enumeration
`member.person.contactPreference` Conditional	Array of complex type	Member’s preference of being contacted by Partner/Loyalty Programme. This element can occur multiple times. API will return this element if it was specified with previously. For internal Avios use only.
`member.person.contactPreference.communicationChannel` Present	String	Channel of communication preferred by the member to receive partner’s marketing information. Will be one of the following: EMAIL PHONE SMS For internal Avios use only. Format: Enumeration.
`member.person.deviceAddress` Present	Array of complex type	Specified the device address details. Will not contain child elements.
`member.person.profileStatus` Present	String	Specifies the profile status: FULL PARTIAL Format: Enumeration
`_` Present	Complex type	Contains hypermedia links to represent account and program information
`_` Present	Complex type	A complex type that represents a link to ‘self’.
`_` Present	String	A string containing the URI that uniquely defines a link to this resource. Format: Alphanumeric plus colon (:), forward slash (/), dash (-), question mark (?), underscore , equals (=), period (.) or ampersand (&)
`_` Present	Complex type	A complex type that represents a link to the associated account.
`_` Present	String	A string containing the URI that uniquely defines a link to the Account resource for this Membership. Format: Alphanumeric plus colon (:), forward slash (/), dash (-), question mark (?), underscore , equals (=), period (.) or ampersand (&)
`_` Present	Complex type	A complex type that represents a link to the programmes associated with this Membership.
`_` Present	String	A string containing the URI that uniquely defines a link to the Account resource for this Membership. Format: Alphanumeric plus colon (:), forward slash (/), dash (-), question mark (?), underscore , equals (=), period (.) or ampersand (&)

Exception Message Elements

The following is an example of an error response from the Retrieve Membership endpoint.

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

Name	Data type	Description
`code` Present	String	Error code. Example: REQUEST_UNAUTHORIZED Format: Alphabetic plus underscore
`businessMessage` Present	String	Error message to business. Example: Request unauthorized Format: Alphabets with space
`developerMessage` Conditional	String	Developer message will be present when detailed technical description is required for the error, which has occurred by the API. If no specific developer message is required, developer message will be as business message. Format: Alphabets with space
`developerLink` Present	String	A URL link to a web page containing more detailed information about the error code. Example: https://developer.iagloyalty.com/docs Format: Alphabetic plus colon (:), forward slash (/), dash (-), underscore or period (.).
`childError` Conditional	Array of complex type	Present for certain errors (e.g. validation) where one or more child error may have occurred.
`childError.code` Present	String	Error code. Example: DATA_INVALID Format: Alphabetic plus underscore
`childError.path` Conditional	String	Identifies 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 (.), forward slash (/), open bracket (
`childError.businessMessage` Present	String	Error message to business. Example: Data invalid Format: Alphabets with space
`childError.developerMessage` Present	String	Developer message will be present when detailed technical description is required for the error, which has occurred by the API. If no specific developer message is required, developer message will be as business message. Format: Alphabets with space
`childError.developerLink` Present	String	A URL link to a web page containing more detailed information about the error code. Example: https://developer.iagloyalty.com/docs Format: Alphabetic plus colon (:), forward slash (/), dash (-), underscore or period (.).

Error Codes

Http Status Code	Description
`400` MEMBERSHIP_NOT_FOUND	When an account status associated with the provided membership identifier is in fraud status.