Customer Address Management
A Customer address can be of different types, such as postal address, email address or phone number.
The appropriate address type will be selected depending on the business usage, for example statement sending or card delivery.
Customer addresses can be created during the creation of the Contract or when additional Cards and Accounts are created.
A customer should have at least one main address (addressLabel: MAIN_POSTAL_ADDRESS)
Each Address is identified by a unique address Reference and optionally by a unique issuer Address External Reference per Issuer.
Through the API, Issuer can:
- Create additional addresses for a customer
- Retrieve customer address
- Update address
- Deactivate address
- Activate address
- Add an address usage
- Remove an address usage
- Invalidate an address
- Create address and add-on subscription for a customer
Retrieve customer address
The API returns the current version of the customer's address identified with:
- the reference of the customer,
- the reference of the address.
This address is either a permanent address or a temporary address (if this one is active at the time of request).
The address identifiers, address attributes, address usages and entity reference (application domain of the address) are displayed in the response.
API Links
Below an example for :
- Customer: CUS10000375016
- Issuer: 1234
GET /api/v2/issuers/1234/customers/CUS10000375016/addresses
Response data:
{
"data": [
{
"issuerId": "1234",
"addressIdentifier": {
"addressReference": "ADDREF_MAIN_POSTAL_ADDRESS_1000000000417761",
"issuerAddressExternalReference": "ADDRESS-202301260053"
},
"addressLabel": "MAIN_POSTAL_ADDRESS",
"addressType": "POSTAL_MAIL",
"postalAddress": {
"line1": "HENRI MARCADAS",
"line2": "line2",
"line4": "BERLIN",
"line5": "DE",
"townName": "BERLIN",
"country": "DE"
},
"status": "ACTIVE",
"startDate": "2023-01-26T10:23:47.029+00:00"
}
]
}
Create address for a customer
The API allows to create either a permanent address or a temporary address for the customer, identified with his reference.
An address includes the following information:
- the issuer address external reference
- the label (eg MAIN_POSTAL_ADDRESS),
- the type (mail address, phone number, email) and the corresponding data
- the address usages
- the start date (optional, by default the current date is used)
- the end date (conditional, is mandatory when creating a temporary address)
If the label of the address is already used for the customer, a new version will be created and active once the start date is reached.
When creating a temporary address, If a temporary address already exists with an overlap on the activity period then only the newly created address will be kept and the old one will be removed.
The temporary address is active between its start date and end date.
One or several address usages can be added to the address (in order to retrieve this address). An address usage is used for specific business process/service. When adding a usage to an address, the usage is immediately active and if it is already assigned to another address, it is removed from this latter.
For information, the main postal address is mandatory.
In return, the API provides the address Reference calculated by our system.
API Links
Below an example of create address request for the customer:
- Customer: CUS10000375016
- Issuer: 1234
POST /api/v2/issuers/1234/customers/CUS10000375016/addresses
Request data:
{
"issuerAddressExternalReference":"string",
"addressLabel":"MAIN_POSTAL_ADDRESS",
"addressType":"POSTAL_MAIL",
"postalAddress":{
"line1":"MARCADAS Henri",
"line2":"line2",
"line3":"line3",
"line4":"line4",
"line5":"line5",
"buildingNumber":"15",
"boxNumber":"AZ",
"streetName":"street",
"postCode":"postcode",
"townName":"town",
"countrySubdivision":"region",
"country":"DE"
},
"addressUsages":[
{
"addressUsageName":"CONTRACT_LETTER",
"serviceCode":"CONTRACT_SERVICE"
}
],
"startDate":"2023-02-17T08:44:28.437Z"
}Response data:
{
"responseMetadata":{
"correlationId":"f1ed54c9-7682-4984-8c8d-1db4cda96a5e",
"statusMessage":"Executed successfully",
"statusCode":200,
"responseDateTime":"2023-02-17T09:52:40.896+0100",
"timeTakenMs":497
},
"data":{
"addressIdentifier":{
"addressReference":"ADDREF_SECOND_POSTAL_ADDRESS_1000000000440549",
"issuerAddressExternalReference":"string"
}
}
}Update Address
The API allows to update the permanent address of a customer, identified with the reference of the customer and the reference of the address.
All the attributes must be provided even those unchanged, except the line 1 to 5 of the postal address if a specific issuer algorithm is configured.
If the address was invalid, the address becomes valid.
One or several address usages can be added to the address. An address usage is used for specific business process/service. When adding a usage to an address, the usage is immediately active and if it is already assigned to another address, it is removed from this latter.
All the usages already linked to the address cannot be removed via this API.
API Links
Below an example of the update request for:
- The issuer: 1234
- The customer: CUS10000375016
- The address reference: ADDREF_SECOND_POSTAL_ADDRESS_1000000000440549
As the address reference ( ADDREF…. 1000000000440549) is inactive, the API creates a new address reference: ADDREF_SECOND_POSTAL_ADDRESS_1000000000440550
Note that if the input address reference was active, the API updates the address reference and doesn’t create another address reference (see the result in the chapter List addresses for a customer).
PUT /api/v2/issuers/1234/customers/CUS10000375016/addresses/ADDREF_SECOND_POSTAL_ADDRESS_1000000000440549
Request data:
{
"issuerAddressExternalReference":"string",
"addressLabel":"SECOND_POSTAL_ADDRESS",
"addressType":"POSTAL_MAIL",
"postalAddress":{
"line1":"MARCADAS Henri",
"line2":"line2",
"line3":"line3",
"line4":"line4",
"line5":"line5",
"buildingNumber":"15",
"boxNumber":"ABC box number",
"streetName":"street",
"postCode":"postcode",
"townName":"town",
"countrySubdivision":"region",
"country":"DE"
},
"addressUsages":[
{
"addressUsageName":"CONTRACT_LETTER",
"serviceCode":"CONTRACT_SERVICE"
}
]
}Response data:
{
"responseMetadata":{
"correlationId":"046eef54-bbd8-492e-b502-ec5c74d68775",
"statusMessage":"Executed successfully",
"statusCode":200,
"responseDateTime":"2023-02-17T10:17:56.639+0100",
"timeTakenMs":41
},
"data":{
"addressIdentifier":{
"addressReference":"ADDREF_SECOND_POSTAL_ADDRESS_1000000000440550"
}
}"a"
}Activate Address
The API allows activation on demand of an address by providing
- the reference of the customer,
- the reference of the address
- the issuer Id.
If a temporary address exists, it becomes also active.
The address identifiers, address attributes and address usages are displayed in the response.
API Links
Deactivate Address
The API is used to deactivate the address, identified with the customer reference and the address reference.
The status becomes 'INACTIVE'.
This action is forbidden in case of:
- the address is the MAIN_POSTAL_ADDRESS
- an usage is linked to the address.
API Links
Below an example of deactivate address request for:
- the issuer: 1234
- the customer: CUS10000375016
- the address reference: ADDREF_SECOND_POSTAL_ADDRESS_1000000000440549
POST /api/v2/issuers/1234/customers/CUS10000375016/addresses/ADDREF_SECOND_POSTAL_ADDRESS_1000000000440549/deactivate
Response data:
{
"data":{
"addressIdentifier":{
"addressReference":"ADDREF_SECOND_POSTAL_ADDRESS_1000000000440549",
"issuerAddressExternalReference":"string"
},
"status":"INACTIVE"
}
}Add an address usage
The address usage describes in which business case the address will be used (eg statement sending, cad delivery, ...).
The complete authorized values list is shared during the product configuration between the issuer and WL.
This API allows a usage determined by its name (e.g. STATEMENT_SENDING) to be linked to the entity reference of the address (e.g. card contract reference) and the service code (e.g. ACCOUNT_SERVICE)
To create an address usage, it is needed to provide:
- Issuer ID
- Customer reference or the issuer customer reference
- Address reference or the issuer address reference
API Links
To create an address usage, it is needed to provide:
Below an example of the update request for:
- The issuer: 1234
- The customer: CUS10000375016
- The address reference: ADDREF_SECOND_POSTAL_ADDRESS_1000000000440550
In this example, the address will be used for the dispute letters.
POST /api/v2/issuers/1234/customers/CUS10000375016/addresses/ADDREF_SECOND_POSTAL_ADDRESS_1000000000440550/address-usages
Request data:
{
"addressUsageName":"DISPUTE",
"serviceCode":"DISPUTE_SERVICE"
}Response data:
{
"responseMetadata":{
"correlationId":"a7cf57a9-5abe-462d-9b38-24c2bedc2bf0",
"statusMessage":"Executed successfully",
"statusCode":200,
"responseDateTime":"2023-02-17T12:05:59.187+0100",
"timeTakenMs":233
},
"data":{
"addressUsageName":"DISPUTE",
"serviceCode":"DISPUTE_SERVICE"
}
}Remove an address usage
The API deletes the address usages linked to one address.
These address usages are filtered by the request params:
- addressUsageName (for definition see the ressource addressUsage), mandatory
- entityReference (for definition see the ressource addressUsage), optional
- serviceCode (for definition see the ressource addressUsage), mandatory
If the entityReference is empty and the API finds several addresseUsages (for the addressUsageName and serviceCode in request param), then the list of addressUsages will be deleted.
API Links
Below an example of delete address request for
- the issuer: 1234
- the customer: CUS10000375016
- the address reference: ADDREF_SECOND_POSTAL_ADDRESS_1000000000440549
DELETE /api/v2/issuers/1234/customers/CUS10000375016/addresses/ADDREF_SECOND_POSTAL_ADDRESS_1000000000440549/address-usages?serviceCode=CONTRACT_SERVICE&addressUsageName=CONTRACT_LETTER Response
Response data:
{
"responseMetadata":{
"correlationId":"e2ac07b1-861e-48cc-bc61-015f3e1801df",
"statusMessage":"Executed successfully",
"statusCode":200,
"responseDateTime":"2023-02-17T10:02:30.775+0100",
"timeTakenMs":39
},
"data":{
"addressUsages":[
{
"addressUsageName":"CONTRACT_LETTER",
"serviceCode":"CONTRACT_SERVICE"
}
]
}
}Invalidate an address
The API is used to invalidate the address identified with the customer reference (external or internal) and the address reference (external or internal).
The invalidation is applied only on the permanent address.
The address must be a postal address. If the user tries to invalidate another kind of address (PHONE/E_MAIL), an error is returned.
The attribute 'invalid' becomes 'true'.
API Links
Create address and add-on subscription for a customer
The API allows to create either a permanent address or a temporary address for the customer, identified with his reference, and to subscribe to an additional service (e.g. new letter, travel insurance) for a contract during all contract life cycle.
An address includes the following information:
- the issuer address external reference
- the label (e.g. MAIN_POSTAL_ADDRESS),
- the type (mail address, phone number, email) and the corresponding data
- the address usages
- the start date (optional, by default, the current date is used)
- the end date (conditional, only used when defining a temporary address)
When creating a temporary address, If a temporary address already exists with an overlap on the activity period then only the newly created address will be kept and the old one will be removed.
For information, the main postal address is mandatory.
A subscription to an additional service includes the following information:
- The identifier of the entity for which the add-on subscription is requested: Either the card contract by providing the card contract reference or the issuer external card contract reference, OR the account by providing the account reference or the issuer external account reference
- The corresponding reference of the additional service
- The service type reference defined at product level
The list of allowed additional services are defined on the product (e.g. PORTAL_ACCESS, ALERT, NOTIFICATION).
Depending on the service type, the issuer can add additional parameters to the add-on service.
As a result:
- The new add-on subscription for the contract is available and can be unsubscribed during all contract life cycle
- A fee can be generated and posted to the cardholder account if required for the product.
In return, the API provides the address reference calculated by the system.
API Links
Delete an address for a customer
The API allows a future permanent address or a temporary address (active or future) to be deleted.
The main input fields requested by the API are:
- The issuer ID
- The customer for which the address deletion is requested : It can be provided by using the customer reference or the issuer customer external reference
- The address of the customer for which the deletion is requested : It can be provided by using the address reference or the issuer address external reference
- The version reference of the address to be deleted
As result, the version of the customer address is deleted. If the address was an active temporary address, its end date is updated (set to the current date).
In response, the interface provides:
- the address identifier (address reference or the issuer address external reference)
- the deleted version reference of the address
API Links
Retrieve the list of versions of a customer address
The API allows the versions of a customer address to be retrieved.
The main input fields requested by the API are:
- The issuer ID
- The customer : It can be provided by using the customer reference or the issuer customer external reference
- The address of the customer for which the versions list is requested : It can be provided by using the address reference or the issuer address external reference
In response, the interface returns address data with the address version reference.
API Links
