Each customer is identified by a unique “customerReference” generated internally and optionally by an external reference “issuerCustomerExternalReference” provided by the issuer - which must be unique per issuer.
The customer is created during the creation of the Contract or when additional Cards and Accounts are provided.
List customers
The "list customers" API enables to get a list of customers based on multiple criteria such as First name, Last name, Birth date,.. For the search, the API enables exact matches values (partialSearch field set to false) or not (partialSearch set to yes). In the latter case, the search criteria should be a subset of the corresponding value stored in our system ; as an example : if we set "JOH" as criteria search for name, then results JOHNNY or "LISE-JOHN" for name would match.
API Links
Find an example where the request retrieves the customers list for:
- Issuer : 1234
- Customer name : MATISSE
- First name: Jack
GET /api/v2/issuers/1234/customers?lastName=MATISSE&firstName=Jack&partialSearch=false&page=0&offset=100
Response data:
{
"data":[
{
"issuerId":"1234",
"customerIdentifier":{
"customerReference":"CUS10000388138",
"issuerCustomerExternalReference":"PERSON-2023020900010A"
},
"active":true,
"birthDate":"1975-10-22T00:00:00.000+00:00",
"birthPlace":"Stuttgart",
"commercialStatus":"Normal",
"courtesyTitle":"Herr",
"firstName":"Jack",
"lastName":"MATISSE",
"monthlySalary":"0",
"nationality":"DE",
"offlineRiskCategory":"Standard",
"onlineRiskCategory":"Standard",
"sex":"M"
}
]
}Retrieve customer information
The "retrieve customer" API allows the user to get customer information from the input parameters:
- Issuer ID
- Customer reference or the issuer customer reference
In addition to the person information, it is also possible to request the list of addresses of the customer and the address usages by using the embedded fields.
API Links
GET /api/V2/issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}
GET /api/V2/issuers/{issuerId}/customers/{customerReference}
Find an example where the request retrieves the customer detail for:
- Customer reference : CUS10000375046
- Issuer : 1234
GET /api/v2/issuers/1234/customers/CUS10000375046
Response data:
"data":{
"issuerId":"1234",
"customerIdentifier":{
"customerReference":"CUS10000375046",
"issuerCustomerExternalReference":"PERSON-2023012600010A"
},
"active":true,
"birthDate":"1960-10-22T00:00:00.000+00:00",
"birthPlace":"Stuttgart",
"commercialStatus":"Normal",
"courtesyTitle":"Herr",
"firstName":"Andre",
"lastName":"SWITCH",
"monthlySalary":"0",
"nationality":"DE",
"offlineRiskCategory":"Standard",
"onlineRiskCategory":"Standard",
"sex":"M"
}List contracts for a customer
This API allows to retrieve all contracts associated with a specific customer, regardless of their role in the contract (e.g., contract owner, card holder, account owner).
Information to be provided in input:
- Issuer ID
- The customer for which information is requested : It can be provided by using the customer reference or the issuer customer external reference.
The customer must exist for the provided issuer.
The API returns all contracts linked to the given customer for the provided issuer and sub-issuers if any, limited to the list of issuers allowed for the user.
API Links
Find an example where the request retrieves all the contracts for:
- Customer reference : CUS10000375046
- Issuer : 1234
In this example, the customer has 2 contracts.
GET /api/v2/issuers/1234/customers/CUS10000375046/contracts
Response data:
{
"data":[
{
"issuerId":"1234",
"contractIdentifier":{
"contractReference":"98e23901-8c38-4da9-ad22-a647d06e8be1",
"issuerContractExternalReference":"CONTRACT-2023012600010A"
},
"issuerBranchCode":"NO_BRANCH",
"cardReleaseOrder":"AUTOMATIC",
"numberOfFreeCardsPrimaryCardImpacted":false,
"signatureDate":"2023-01-26T14:36:01.000+00:00",
"status":"SIGNED",
"statusDate":"2023-01-26T14:36:01.000+00:00",
"contractOwnerIdentifier":{
"customerReference":"CUS10000375048",
"issuerCustomerExternalReference":"PERSON-2023012600012A"
},
"productIdentifier":{
"issuerProductExternalReference":"PDT_1234_DEBIT",
"productReference":"PDT_1234_DEBIT"
},
"rootAccountIdentifier":{
"accountReference":"12349095353652134625",
"issuerAccountExternalReference":"ROOT_ACCOUNT-2023012600010A"
}
},
{
"issuerId":"1234",
"contractIdentifier":{
"contractReference":"2cb82f2f-b3a0-425d-ab34-1df0a08511af",
"issuerContractExternalReference":"CONTRACT-202320900002A"
},
"issuerBranchCode":"NO_BRANCH",
"cardReleaseOrder":"AUTOMATIC",
"numberOfFreeCardsPrimaryCardImpacted":false,
"signatureDate":"2023-02-09T16:23:48.000+00:00",
"status":"SIGNED",
"statusDate":"2023-02-09T16:23:48.000+00:00",
"contractOwnerIdentifier":{
"customerReference":"CUS10000375046",
"issuerCustomerExternalReference":"PERSON-2023012600010A"
},
"productIdentifier":{
"issuerProductExternalReference":"PDT_1234_DEBIT",
"productReference":"PDT_1234_DEBIT"
},
"rootAccountIdentifier":{
"accountReference":"12345560829491606922",
"issuerAccountExternalReference":"ROOT_ACCOUNT-202320900002A"
}
}
]
}List card contracts for a cardholder
This API enables all the card contracts associated with the cardholder to be retrieved.
Information to be provided in input:
- Issuer ID
- Customer reference
The customer must exist for the provided issuer.
The API returns all card contracts linked to the given cardholder for the provided issuer and sub-issuers if any, limited to the list of issuers allowed for the user.
API Links
Find an example where the request retrieves all the card contracts for:
- Customer reference : CUS10000375046
- Issuer : 1234
In this example, the customer has 2 card contracts.
GET /api/v2/issuers/1234/customers/CUS10000375046/card-contracts
Response data:
{
"data":[
{
"issuerId":"1234",
"cardContractIdentifier":{
"cardContractReference":"12342000000000410211",
"issuerCardContractExternalReference":"CARD_CONTRACT-2023012600010A"
},
"cardTemplateReference":"T_1234_CARD_DEBIT",
"cardTypeCode":"F",
"status":"ACTIVE",
"openingDate":"2023-01-26T14:36:01.983+00:00",
"activationDate":"2023-01-26T14:36:01.983+00:00",
"trustedAuthenticationReference":"123420230126153601853",
"newCardRenewalAllowed":true,
"newCardReplacementAllowed":true,
"issuerBranchCode":"NO_BRANCH",
"artwork":"ClassicCardConsors",
"forcedEmbossingName":"ANDRE SWITCH",
"schemeDeclarationOptOut":false,
"principalSupplementaryCardIndicator":"SUPPLEMENTARY",
"productCategory":"DEBIT",
"productCategoryLabel":"IMMEDIATE_DEBIT_DEBIT",
"productIdentifier":{
"issuerProductExternalReference":"PDT_1234_DEBIT",
"productReference":"PDT_1234_DEBIT"
},
"cardHolderIdentifier":{
"customerReference":"CUS10000375046",
"issuerCustomerExternalReference":"PERSON-2023012600010A"
},
"contractIdentifier":{
"issuerContractExternalReference":"CONTRACT-2023012600010A"
},
"cardProfileDescription":"P_1234_CARD_DEBIT",
"cardProfileReference":"P_1234_CARD_DEBIT",
"contractType":"CONSUMER"
},
{
"issuerId":"1234",
"cardContractIdentifier":{
"cardContractReference":"12342000000000427562",
"issuerCardContractExternalReference":"CARD_CONTRACT-202320900002A"
},
"cardTemplateReference":"T_1234_CARD_DEBIT",
"cardTypeCode":"F",
"status":"ACTIVE",
"openingDate":"2023-02-09T16:23:49.216+00:00",
"activationDate":"2023-02-09T16:23:49.216+00:00",
"trustedAuthenticationReference":"123420230209172349968",
"newCardRenewalAllowed":true,
"newCardReplacementAllowed":true,
"issuerBranchCode":"NO_BRANCH",
"artwork":"ClassicCardConsors",
"forcedEmbossingName":"MR ANDRE SWITCH",
"schemeDeclarationOptOut":false,
"principalSupplementaryCardIndicator":"PRINCIPAL",
"productCategory":"DEBIT",
"productCategoryLabel":"IMMEDIATE_DEBIT_DEBIT",
"productIdentifier":{
"issuerProductExternalReference":"PDT_1234_DEBIT",
"productReference":"PDT_1234_DEBIT"
},
"cardHolderIdentifier":{
"customerReference":"CUS10000375046",
"issuerCustomerExternalReference":"PERSON-2023012600010A"
},
"vipFlag":false,
"contractIdentifier":{
"issuerContractExternalReference":"CONTRACT-202320900002A"
},
"cardProfileDescription":"P_1234_CARD_DEBIT",
"cardProfileReference":"P_1234_CARD_DEBIT",
"contractType":"CONSUMER"
}
]
}List addresses for a customer
This API enables all the addresses associated with a given customer, identified by his customer reference, to be retrieved. This address could be either a permanent address or a temporary address.
Several address types are managed. Each address can be used for a specific usage (card delivery, statement delivery, contract letter,...). Address usage is associated to a service (card service, account service, dispute service, ..) configured in our system.
The API can retrieve only the addresses linked to a specific usage: in this case, all the mandatory 'AddressUsage' attributes must be provided (e.g. serviceCode, AddressUsage).
If the showHistory indicator is set to Y then the full history of the addresses and the future addresses are returned. If this indicator is empty (default behavior) or equals to N, then only the last active addresses are returned.
Address identifiers, Address attributes and Address usages are displayed in the response.
API Links
Below an example of request and response for:
- The issuer : 1234
- The customer: CUS10000375016
The show history is requested in the response in order to have also the previous and the future addresses.
- Main postal address (reference: ADDREF_MAIN_POSTAL_ADDRESS_1000000000417761) with the current address and the future address
- Inactive second postal address (reference: ADDREF_SECOND_POSTAL_ADDRESS_1000000000440549
- Active second postal address (reference: ADDREF_SECOND_POSTAL_ADDRESS_1000000000440550) with 3 changes
GET /api/v2/issuers/1234/customers/CUS10000375016/addresses?showHistory=true
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",
"endDate":"2023-03-01T08:44:28.437+00:00"
},
{
"issuerId":"1234",
"addressIdentifier":{
"addressReference":"ADDREF_SECOND_POSTAL_ADDRESS_1000000000440549",
"issuerAddressExternalReference":"string"
},
"addressLabel":"SECOND_POSTAL_ADDRESS",
"addressType":"POSTAL_MAIL",
"postalAddress":{
"line1":"HENRI MARCADAS",
"line2":"line2",
"line3":"street 15",
"line4":"postcode town",
"line5":"DE",
"buildingNumber":"15",
"boxNumber":"AZ",
"streetName":"street",
"postCode":"postcode",
"townName":"town",
"countrySubdivision":"region",
"country":"DE"
},
"status":"INACTIVE",
"startDate":"2023-02-17T08:52:40.593+00:00"
},
{
"issuerId":"1234",
"addressIdentifier":{
"addressReference":"ADDREF_SECOND_POSTAL_ADDRESS_1000000000440550"
},
"addressLabel":"SECOND_POSTAL_ADDRESS",
"addressType":"POSTAL_MAIL",
"postalAddress":{
"line1":"HENRI MARCADAS",
"line2":"line2",
"line3":"street 15",
"line4":"postcode town",
"line5":"DE",
"buildingNumber":"15",
"boxNumber":"ABC box number",
"streetName":"street",
"postCode":"postcode",
"townName":"town",
"countrySubdivision":"region",
"country":"DE"
},
"status":"ACTIVE",
"startDate":"2023-02-17T09:17:56.629+00:00",
"endDate":"2023-02-17T09:24:47.586+00:00"
},
{
"issuerId":"1234",
"addressIdentifier":{
"addressReference":"ADDREF_SECOND_POSTAL_ADDRESS_1000000000440550"
},
"addressLabel":"SECOND_POSTAL_ADDRESS",
"addressType":"POSTAL_MAIL",
"postalAddress":{
"line1":"HENRI MARCADAS",
"line2":"line2",
"line3":"street ref 1000000000440550 15",
"line4":"postcode town",
"line5":"DE",
"buildingNumber":"15",
"boxNumber":"ABC box number",
"streetName":"street ref 1000000000440550",
"postCode":"postcode",
"townName":"town",
"countrySubdivision":"region",
"country":"DE"
},
"status":"ACTIVE",
"startDate":"2023-02-17T09:24:47.586+00:00",
"endDate":"2023-02-17T09:41:16.159+00:00"
},
{
"issuerId":"1234",
"addressIdentifier":{
"addressReference":"ADDREF_SECOND_POSTAL_ADDRESS_1000000000440550"
},
"addressLabel":"SECOND_POSTAL_ADDRESS",
"addressType":"POSTAL_MAIL",
"postalAddress":{
"line1":"HENRI MARCADAS",
"line2":"line2",
"line3":"street ref 1000000000440550 15",
"line4":"history town",
"line5":"DE",
"buildingNumber":"15",
"boxNumber":"ABC box number",
"streetName":"street ref 1000000000440550",
"postCode":"history",
"townName":"town",
"countrySubdivision":"region",
"country":"DE"
},
"status":"ACTIVE",
"startDate":"2023-02-17T09:41:16.159+00:00"
},
{
"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",
"line3":"future street 15",
"line4":"postcode town",
"line5":"DE",
"buildingNumber":"15",
"boxNumber":"AZ",
"streetName":"future street",
"postCode":"postcode",
"townName":"town",
"countrySubdivision":"region",
"country":"DE"
},
"status":"ACTIVE",
"startDate":"2023-03-01T08:44:28.437+00:00"
}
]
}List accounts for an account owner
This API enables all the accounts associated with the customer (cardholder) to be retrieved.
The customer must exist for the provided issuer.
The API returns all accounts linked to the given account owner for the provided issuer and sub-issuers if any, limited to the list of issuers allowed for the user.
The interface provides the generic information (mainly master data) for managing the account.
For credit cards, payment mode and the due amount calculation is provided back.
API Links
Update customer
The "update customer" API allows the user to update the attributes of a customer.
To identify the customer, it is needed to provide:
- The issuer ID
- The customer reference (internal or external) for which updates are required
The customer reference can be retrieved by using the "list customers" API.
All the attributes must be given in input even if they remain unchanged. For that, It can be needed to use the "retrieve customer" API to get all the current attributes.
API Links
Update customer partially
The "update customer partially" API allows the user to update the attributes of a customer.
To identify the customer, it is needed to provide:
- The issuer ID
- The customer reference (internal or external) for which updates are required
The customer reference can be retrieved by using the "list customers" API.
With this API, only attributes that need to be updated must be given in input.
In case the property Contact (list) is provided in input then it will replace the existing list.
API Links
PATCH /api/V2/issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}
PATCH /api/V2/issuers/{issuerId}/customers/{customerReference}
Find an example where the request updates:
- The second first name
- The sex
- The birth date
- The birth place
For:
- Customer reference : CUS10000375046
Issuer : 1234
PATCH /api/v2/issuers/1234/customers/CUS10000375046
Request data:
{
"secondFirstName":"John",
"sex":"M",
"birthDate":"1970-10-22T00:00:00.000Z",
"birthPlace":"Paris"
}Response data:
{
"responseMetadata":{
"correlationId":"a5542367-3384-4738-9710-7ee6111cd7c2",
"statusMessage":"Executed successfully",
"statusCode":200,
"responseDateTime":"2023-02-09T17:52:08.681+0100",
"timeTakenMs":42
},
"data":{
"customerIdentifier":{
"customerReference":"CUS10000375046",
"issuerCustomerExternalReference":"CUS10000375046"
}
}
}Create a contact for a customer
The API creates a contact person belonging to the customer (person) by providing information such as first name, name, department to which he is attached.
To create a contact, it is needed to provide:
- The issuer ID
- The customer reference or the issuer customer reference
Idempotency is managed by the API; that is, if the request with the same WL-Correlation-ID is sent multiple times, it will be executed only once. The response will be retrieved directly from our system.
API Links
Update a contact for a customer
The API allows information of a contact of the customer (person) to be modified.
To update a contact, it is needed to provide:
- The issuer ID
- The customer reference or the issuer customer reference
- The contact reference
All attributes must be provided (even if some of them have not been modified) else the value of missing attributes will be empty.
API Links
Remove a contact for a customer
The API allows a contact of the customer (person) to be deleted.
To remove a contact, it is needed to provide:
- The issuer ID
- The customer reference or the issuer customer reference
- The contact reference
API Links
Create a customer as a person
The API allows a new customer (as person) to be created if all the mandatory fields are provided.
The main input fields are:
- The issuer ID
- The first name of the customer
- The last name of the customer
- The default address of the customer : The Main postal address has to be provided because used as default address by all business processes if no address usage is defined.
The API returns the customer reference (as person) generated by our system.
The response can also be enriched (if specified as embedded fields in input) with additional data such as customer (as person) information, address identifiers linked to the customer, addresses of the customer, contacts of the customer.
Idempotency is managed by the API; that is, if the request with the same WL-Correlation-ID is sent multiple times, it will be executed only once. The response will be retrieved directly from our system.
API Links
Retrieve list of historic updates of a customer
The API allows the customer update history of a customer to be retrieved.
The main input fields requested by the API are:
- The issuer ID
- The customer for which information is requested : It can be provided by using the customer reference or the issuer customer external reference.
A start date and an end date can be provided in order to limit the search of the history.
In response, the interface provides a list of changes with the effective date of the update.
API Links