Retrieve Membership API Documentation

v2Showing BAEC 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 is provided in the request message. This Access Token can only be created by a member having been authenticated.

The data returned in a successful response will contain Membership status and Member Profile along with account and membership 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 member access token.
  • 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

Pre-conditions

  • A Member Account must have been successfully created as a BA Executive Club account within BA applications (e.g. ba.com).
  • A valid Access Token for the member 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}/programmes/{programme-identifier}/memberships?api_key={api_key}'

Example

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

Test Endpoint:

https://api.avios.com/test/{version}/programmes/{programme-identifier}/memberships?api_key={api_key}
NameData typeDescription
version
Required
StringThe version of the API which will be confirmed during the on-boarding process.
Format: Alphanumeric V
programme-identifier
Required
StringThe identifier for the loyalty programme to which the member belongs. This will have been provided to the member as part of the Loyalty Programme API partner on-boarding process along with your API key and Mashery credentials. Restricted to BAEC.
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: As supplied by Avios during partner configuration, alpha-numeric. Min Length = 24, Max Length = 24.

Request Headers

NameData typeDescriptionExample
Accept
Optional
StringThe 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
StringA BA OAUTH access token authorising the partner access to this API.
Format: Alphanumeric
Bearer 50663dcb
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
StringThe originating IP address of a consumer.
Format: Valid IP address
172.17.1.1, 172.17.1.2
X-Agent-ID
Optional
StringAn 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 Retrieve Membership endpoint.

{
  "membershipStatus": "A",
  "member": {
    "person": {
      "name": {
NameData typeDescription
membershipStatus
Present
StringRepresents the membership status. Possible value is “A” for active
Format: Enumeration
member
Present
Complex type 1..1A complex type that represents the member within Avios systems. This type contains a person.
member.person
Present
Complex type 1..1A complex type that contains the member’s personal details within Avios systems.
member.person.name
Present
Complex type 1..1Contains 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
StringTitle (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
StringFirst 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.familyName
Present
StringSurname (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
DateThe 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
StringAn 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
Format: Enumeration.
member.person.postalAddresses
Conditional
Complex type 1..1A 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 1..1A complex type representing the preferred postal address of the member.
member.person.postalAddresses.preferredPostalAddress.type
Present
StringA 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 1..5An 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 of address 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
StringPostal address country name. Example: UNITED KINGDOM
Format: Alphabetic with special character space ( )
member.person.postalAddresses.preferredPostalAddress.postCode
Conditional
StringThe 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.emailAddresses
Present
Complex type 1..1A complex type representing the Member’s email addresses.
member.person.emailAddresses.preferredEmailAddress
Present
Complex type 1..1A complex type representing the Member’s preferred email address.
member.person.emailAddresses.preferredEmailAddress.email
Present
StringEmail 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 (
member.person.telecomAddresses
Conditional
Complex type 1..1A 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 1..1A complex type that represents a Member’s preferred telephone number.
member.person.telecomAddresses.preferredTelecomAddress.countryCode
Present
StringThe 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
StringThe 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
StringTelecom address type. Will be one of the following: BUSINESS PERSONAL
Format: Enumeration.
_
Present
Complex type 1..1Contains hypermedia links to represent account and program information
_
Present
Complex type 1..1A complex type that represents a link to ‘self’.
_
Present
StringA string containing the URI that uniquely defines a link to this resource.
Format: Alphanumeric plus colon (:), oblique (/), dash (-), question mark (?), underscore (

Exception Message Elements

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

{
  "code": "REQUEST_UNAUTHORIZED",
  "businessMessage": "Request Unauthorized",
  "developerMessage": "Request Unauthorized",
  "developerLink": "https://developer.avios.com/docs",
NameData typeDescription
code
Present
StringError code. Example: REQUEST_UNAUTHORIZED
Format: Alphabetic plus underscore (
businessMessage
Present
StringError message to business. Example: Request unauthorised
Format: Alphabets with space
developerMessage
Conditional
StringDeveloper 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
StringA URL link to a web page containing more detailed information about the error code. 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 one or more child error may have occurred.
childError.code
Present
StringError code. 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
StringError message to business. Example: Data invalid
Format: Alphabets with space
childError.developerMessage
Present
StringDeveloper 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
StringA URL link to a web page containing more detailed information about the error code. Example: https://developer.avios.com/docs
Format: Alphabetic plus colon (:), oblique (/), dash (-), underscore (

Error Codes

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