Update Membership API Documentation

v3

The Update Membership endpoint enables a partner to update personal and programme information for an existing membership. The endpoint updates membership details only when a membership number has been identified and a valid access token has been received.

The Update Membership endpoint accepts partial membership information updates. For example, the address could be passed in the endpoint request in isolation, without other details. In this scenario, only the address will be updated and the other pre-existing data will remain unchanged. The endpoint allows the postal address not to be validated and will allow it to stay in the format provided.

Business Context

Here’s the process flow:

Update Membership Flow

  • A member is identified in the partner application and initiates an change to their profile data.
  • The partner will capture the profile update, which may be partial (for example, just the member's address).
  • The partner will invoke the Update Membership endpoint providing the membership profile update and a valid access token, along with other pertinent data elements as described in the request section of this document.
  • The Update Membership endpoint validates the incoming request and stores the updated membership profile information within the Avios Platform. If the request is unsuccessful, an error message is returned.
  • The partner facilitates the member's onward journey through their channels.

Important Technical Notes

  • Request element values may be provided in either upper/lower case ASCII characters or accented characters, which will be stored in upper case ASCII format. The endpoint allows Postal Address to be persisted without any validation by setting the appropriate flag in the request.
  • Where Postal Address validation occurs, the format of the retained address will be standardised.
  • When invoking the Update Membership service, a partial request may be provided. Any type that is not provided will not be updated as part of the execution of the request. For example, postal address may be passed with the name omitted. However, the partial request must still be presented in the correct format and aligned to the specification.
  • Country of Residence, Title and Date of Birth can only be provided using the Update Membership endpoint if these data elements do not already exist in the Membership (can add, cannot update – offline process only).
  • Any accented characters provided in the request will be converted to uppercase ASCII.

Pre-conditions

  • The partner must have a valid API key to access the Update Membership endpoint
  • The member must have previously identified themselves by logging in, at which point the Partner will have received a valid Access Token for the member for use with Update Membership API requests
  • 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 the Join Programme endpoint or Register Account API.

Post-conditions

Success outcome: HTTP status code 204 is returned with an empty response body.

Error outcome: Service error is returned.

Service Details

URI Parameters

Production Endpoint:

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

Example

https://api.avios.com/v3/memberships/3081470000000000?api_key=abcdef

Test Endpoint:

https://api.avios.com/test/{version}/memberships/{membership-identifier}?api_key={api_key}
NameTypeDescriptionExample
version
Required
StringThe version of the API, which will be confirmed during the on-boarding process.
Format: Alphanumeric V
v3
membership-identifier
Required
StringThe membership number of the loyalty programme member.
Format: Min length = 16 Max Length = 24 Numeric.
3081470000000000
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
abcdefabdefabdefabcdef

Request Headers

NameTypeDescriptionExample
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: application/json
application/json
Content-Type
Required
StringThe Content-Type request-header field indicates the media type of the entity-body sent to the recipient as request payload. Only application/json is accepted currently.
Format: application/json
application/json
X-Forwarded-For
Optional
StringThe IP address of the end customer. API will validate only first provided IP address, second and following IP addresses will not be validated.
Format: Comma separated valid IP addresses
"172.17.1.1", "172.17.1.2"
Authorization
Required
StringAn access token authorising the partner access to this API.
Format: JWT Token
Bearer:eyJhbGcI1Ni J9

Request Elements

The following is an example of a request call to the Update Membership endpoint:

{
  "member": {
    "person": {
      "emailAddresses": {
        "preferredEmailAddress": {
NameTypeDescription
member
Optional
Complex type 0..1A complex type that represents the member within Avios systems. This type contains a person child element.
member.person
Required
Complex type 1..1Represents the member within Avios systems.
member.person.name
Optional
Complex type 0..1Contains the name of the member, split into various fields that represent a name in a recognised format. As only Title may be updated via the IAGL Avios API platform, this is the only field available in the Update Membership API request. All other name fields may only be updated offline.
member.person.name.title
Required
StringTitle (Salutation) of the member.The title may only be updated for a member via this API if the membership does not already contain title.
Format: Min Length: 1 Max length: 30 Alphabetic.
member.person.dateOfBirth
Conditional
ISO-8601 DateThe member's Date of Birth in ISO-8601 Calendar date format. The Date of Birth may only be updated for a member via this API if the membership does not already contain a Date of Birth. Error will be returned if DOB of member is less than 18 years old. Date of birth is accepted from 1000-01-01. Future date of birth isn't accepted.
Format: YYYY-MM-DD ISO-8601
member.person.locale
Optional
Complex type 0..1The local for the member, contains the preferred language as 'languageCode'.
member.person.locale.languageCode
Required
ISO 639-1 StringPreferred language of the member for use within Avios systems and channels. Case insensitive. Supported values are: IT; ES; CA; FR; EN
Format: Max length: 2 (ISO 639-1 Alphabetic 2 character language code)
member.person.postalAddresses
Optional
Complex type 0..1A complex type representing the Member's postal addresses.
member.person.postalAddresses.preferredPostalAddress
Required
Complex type 1..1A complex type representing the preferred postal address of the member.
member.person.postalAddresses.preferredPostalAddress.type
Required
StringType of postal address. Case sensitive and must be one of the following: PERSONAL
Format: Enumeration
member.person.postalAddresses.preferredPostalAddress.addressLine
Required
Array of string 1..4
member.person.postalAddresses.preferredPostalAddress.country
Required
ISO 3166-1 StringThe country of the member's preferred address. Case insensitive. This field will determine the member's Market within Avios systems, which will not have an impact on the Partner's interactions with the customer.
Format: Max length: 2 ISO 3166-1 Alphabetic 2 character country code.
member.person.postalAddresses.preferredPostalAddress.postCode
Conditional
StringPostal code of member's preferred address. Must not contain spaces.
Format: Max length: 8 Alphanumeric
member.person.postalAddresses.preferredPostalAddress.validationSource
Optional
StringThis specifies whether address needs to be validated. Case sensitive and the value provided must be one of the following: EXPLICIT (System Validation required) SYSTEM (System Validation required) Omitting this field in the request has the same effect as providing a value of SYSTEM. Now EXPLICIT and SYSTEM provides the same functionality.
Format: Enumeration
member.person.postalAddresses.otherPostalAddress
Optional
Complex type 0..1Optional postal address in addition to the preferred postal address.
member.person.postalAddresses.otherPostalAddress.type
Required
StringType of postal address. Case sensitive and must be one of the following: BUSINESS
Format: Enumeration.
member.person.postalAddresses.otherPostalAddress.addressLine
Required
Array of string 1..4
member.person.postalAddresses.otherPostalAddress.country
Required
ISO 3166-1 StringThe country of the member's other address. Case insensitive.This field will determine the member's Market within Avios systems, which will not have an impact on the Partner's interactions with the customer.
Format: Max length: 2 ISO 3166-1 Alphabetic 2 character country code.
member.person.postalAddresses.otherPostalAddress.postCode
Conditional
StringPostal code of member's other address. Must not contain spaces.
Format: Max length: 8 Alphanumeric
member.person.postalAddresses.otherPostalAddress.validationSource
Optional
StringThis specifies whether address needs to be validated. Case sensitive and the value provided must be one of the following: EXPLICIT (System Validation required) SYSTEM (System Validation required) Omitting this field in the request has the same effect as providing a value of SYSTEM. Now EXPLICIT and SYSTEM provides the same functionality.
Format: Enumeration
member.person.emailAddresses
Optional
Complex type 0..1A complex type representing the Member's email addresses.
member.person.emailAddresses.preferredEmailAddress
Required
Complex type 1..1A complex type representing the Member's preferred email address.
member.person.emailAddresses.preferredEmailAddress.email
Required
StringEmail address of the member. There will be only a single at-sign present. Also, all special characters can be visible before the at-sign and only minus (-) and period (.) after at-sign.
Format: Max length: 50 Alphanumeric with special characters.
member.person.telecomAddresses
Optional
Complex type 0.1A complex type that represents a collection of Member's fully elaborated telephone numbers, which include country and area codes.
member.person.telecomAddresses.preferredTele comAddress
Required
Complex type 1..1A complex type that represents a Member's preferred telephone number. This element will update telecomAddress details for member.
member.person.telecomAddresses.preferredTele comAddress.countryCode
Optional
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: Max length: 5 Numeric
member.person.telecomAddresses.preferredTele comAddress.areaCode
Optional
StringThe area code element of the Member's preferred telecom address.The total length of combination of the area code and the number cannot exceed 15 characters.
Format: Max length: 5 Numeric
member.person.telecomAddresses.preferredTelecomAddress.number
Required
StringThe 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
member.person.telecomAddresses.preferredTelecomAddress.type
Required
StringTelecom addresses type. Must be one of the following and case sensitive: 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; or If deviceType = phone and type = Business, the telephone number is saved as a work phone; or If deviceType = phone and type = Personal, the telephone number is saved as a home phone.Any other combination will result in error. There are 3 different types of telecom address mobile, work and home phones. If member has one type of telecom address and update membership API gets request with the same type, API updates telecom address details, if update membership gets request with different type of telecom address than member already has, it doesn't update existing phone details but provided details are saved as other telecom address. Member can have 3 different types of telecom address.
Format: Enumeration
member.person.telecomAddresses.preferredTelecomAddress.deviceType
Required
StringTelecom addresses device type. Must be one of the following and case sensitive: PHONE MOBILE This field and Type, described above, are interrelated as per the Description for the Type field above.
Format: Enumeration
member.person.telecomAddresses.otherTelecom Address
Optional
Array of complex type 0..2Other telecom address in addition to the preferred telecom address. 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. This element won't update telecom address details even if passed in request message.
member.person.telecomAddresses.otherTelecomAddress.countryCode
Optional
StringTelecom addresses country code. The total string length of the countryCode, areaCode and the telephone number cannot exceed 15 characters. This element won't update telecom address details even if passed in request message.
Format: Numeric characters
member.person.telecomAddresses.otherTelecomAddress.areaCode
Optional
StringTelecom address area code. The total string length of the areaCode and the telephone number cannot exceed 15 characters. This element won't update telecom address details even if passed in request message.
Format: Max length: 15 Numeric characters
member.person.telecomAddresses.otherTelecomAddress.number
Required
StringThe 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. This element won't update telecom address details even if passed in request message.
Format: Max length: 15 Numeric characters
member.person.telecomAddresses.otherTelecomAddress.type
Required
StringTelecom 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 number is 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. This element won't update telecom address details even if passed in request message.
Format: Enumeration
member.person.telecomAddresses.otherTelecomAddress.deviceType
Required
StringTelecom 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. This element won't update telecom address details even if passed in request message.
Format: Enumeration
member.person.marketingPreference
Optional
Array of complex type 0..2Member's preference for receiving marketing communications from Loyalty Programme in relation to products offering. There may be multiple instances of this element. There can only be passed two marketing preference objects with different campaign type channels. If there are passed few marketing preference objects with same campaign types error will be returned.
member.person.marketingPreference.campaignType
Required
StringPromotion activity of a product conducted by the Partner. Must be one of the following: TRAVEL_OFFERS PARTNER The following combinations are allowed:communicationChannel = POSTAL and campaignType = PARTNER for third party marketing communications by Post. communicationChannel = POSTAL and campaignType = TRAVEL_OFFERS for Avios marketing communications by Post.Any other combination will result in error.
Format: Enumeration
member.person.marketingPreference.communicationChannel
Required
StringChannel of communication preferred by the member to receive partner's marketing information. Must be "POSTAL". This field and Type, described above, are interrelated as per the Description for the campaignType field above.
Format: Enumeration
member.person.marketingPreference.selected
Required
StringIndicator if selection is Yes (Y) or No (N). Specifies if member wants to be contacted through specified communication channel. Decides if contact preference details will be returned in other endpoints. Example: retrieve Membership.
Format: Enumeration
member.person.contactPreference
Optional
Array of complex type 0..3Member's preference of being contacted by Partner/Loyalty Programme. There may be multiple instances of this element. There can only be passed three contact preference objects with different communication channels. If there are passed few contact preference objects with same communication channel error will be returned.
member.person.contactPreference.communicationChannel
Required
StringChannel of communication preferred by the member to receive partner's marketing information. The following combinations are allowed:communicationChannel = EMAIL for communications via email. communicationChannel = SMS for communications via SMS. communicationChannel = PHONE for communications via phone.Any other combination will result in error.
Format: Enumeration
member.person.contactPreference.selected
Required
StringIndicator if selection is Yes (Y) or No (N). Specifies if member wants to be contacted through specified communication channel. Decides if contact preference details will be returned in other endpoints. Example: retrieve Membership.
Format: Enumeration
programme
Optional
Complex type 0..1The loyalty programme to be associated with the membership.
programme.identifier
Required
StringThe identifier of the loyalty programme. Details of values to be provided will be supplied to the partner.
Format: Enumeration

Exception Message Elements

The exception message responses may be formatted in either upper or lower case. An example of an error response is shown:

{
  "code": "REQUEST_UNAUTHORIZED",
  "businessMessage": "Request Unauthorized",
  "developerMessage": "Request Unauthorized",
  "developerLink": "https://developer.iagloyalty.com/docs",
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
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: 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 0..nPresent for certain errors (Example: validation) where one or more child 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
StringDeveloper message will be present when detailed technical description is required for the child error, which has occurred, by the API. Example: in case of REQUEST_INVALID DATA_INVALID, it is required which data is invalid and what is invalid in the data.If no specific developer message is required, developer message will be as business message.
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

HTTP Status CodeDescription
400
REQUEST_INVALID
MANDATORY_DATA_MISSING
A mandatory element is missing from the request or request details doesn't follow JSON message contact.
400
REQUEST_INVALID
DATA_INVALID
Request element does not follow the request contract
400
REQUEST_INVALID
PHONE_NUMBER_INVALID
The specified phone number is not valid for the member's country of residence.
400
REQUEST_INVALID
POSTAL_ADDRESS_INVALID
The specified postal address is not valid. Country or postcode is incorrect.
400
REQUEST_INVALID
PROGRAMME_INVALID
The specified programme is invalid, it either isn't associated with the consumer or the member is already associated with the programme
400
ADDRESS_NOT_SUPPORTED
The following combination of Device type and address type are accepted by the application: If device type is mobile & address Type is Personal, it is saved as a mobile phone. If device type is phone & address Type is Business, it is saved as a work phone. If device type is phone & address Type is Personal, it is saved as a home phone. Any other combination will result in an error. This error will be returned also if type element will have value 'BUSINESS' under preferredPostalAddress or preferredPostalAddress and otherPostalAddress type element has the same value.
400
DETAILS_ALREADY_EXIST
The provided details cannot be updated in the membership record. Example:, title, DoB already exist or postalAddress contains other country than member was originally registered.
500
Internal server error for provided member who is younger than 18 years old or contactPreference or marketingPreference has multiple communication channels with same values.