Worldline Customer - Address API
Customer Address Api Controller
Customer Address Api Controller
swagger: '2.0'
info:
description: 'The current set of APIs will be available in Q2 2026 on Worldline Global Issuing Platforms.
Additional APIs are under construction and planned to be available in 2026.'
version: 2.41.1
title: Worldline Card Issuing Account - AccountState Customer - Address API
contact: {}
host: sbx-wlip.api1-eu2.psapigateway.preprod.giservices.io/card-issuing
basePath: /api/v2
schemes:
- https
tags:
- name: Customer - Address
description: Customer Address Api Controller
paths:
/issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}/addresses:
post:
x-wl-idempotent: true
x-wl-lra-operation: true
tags:
- Customer - Address
summary: Create address for a customer by external reference
operationId: createAddressByCustomerIssuerExtRef
description: "The API allows to create either a permanent address or a temporary address for the customer, identified with his reference. \nAn address includes the following information:\n•\tthe issuer address external reference \n•\tthe label (eg MAIN_POSTAL_ADDRESS),\n•\tthe type (mail address, phone number, email) and the corresponding data\n•\tthe address usages\n•\tthe start date (optional, by default the current date is used)\n•\tthe end date (conditional, is mandatory when creating a temporary address)\n\nIf 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.\n\nWhen 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. \nThe temporary address is active between its start date and end date.\n\nOne 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. \n\nFor information, the main postal address is mandatory.\nIn return, the API provides the address Reference calculated by the system.\n\nIdempotency 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."
consumes:
- application/json
produces:
- application/json
parameters:
- name: WL-Correlation-ID
in: header
required: false
type: string
- name: WL-Origin
in: header
required: false
type: string
- name: WL-Username
in: header
required: false
type: string
- name: filter
in: query
description: Filtered Fields
required: false
type: array
items:
type: string
collectionFormat: multi
- name: issuerId
in: path
description: Issuer ID
required: true
type: string
- name: issuerCustomerExternalReference
in: path
description: Issuer Customer External Reference
required: true
type: string
- in: body
name: body
required: false
schema:
$ref: '#/definitions/CreateAddressRequest'
responses:
'400':
description: Bad request
schema:
$ref: '#/definitions/BadRequestErrorApiResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/UnauthorizedErrorApiResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/ForbiddenErrorApiResponse'
'404':
description: Not found
schema:
$ref: '#/definitions/NotFoundErrorApiResponse'
'500':
description: Internal server error
schema:
$ref: '#/definitions/InternalServerErrorErrorApiResponse'
'502':
description: Bad gateway
schema:
$ref: '#/definitions/BadGatewayErrorApiResponse'
'200':
description: OK
schema:
$ref: '#/definitions/ApiResponseEntityCreateAddressResponse'
security:
- basic: []
deprecated: false
? /issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}/addresses/external-addresses/{issuerAddressExternalReference}
: get:
tags:
- Customer - Address
summary: Retrieve customer address by customer external reference and address external reference
operationId: retrieveAddressByIssuerExtRefAndCustomerIssuerExtRef
description: "The API returns the current version of the customer's address identified with:\n•\tthe reference of the customer,\n•\tthe reference of the address.\nThis address is either a permanent address or a temporary address (if this one is active at the time of request).\nThe address identifiers, address attributes, address usages and entity reference (application domain of the address) are displayed in the response."
produces:
- application/json
parameters:
- name: WL-Correlation-ID
in: header
required: false
type: string
- name: WL-Origin
in: header
required: false
type: string
- name: WL-Username
in: header
required: false
type: string
- name: filter
in: query
description: Filtered Fields
required: false
type: array
items:
type: string
collectionFormat: multi
- name: issuerId
in: path
description: Issuer ID
required: true
type: string
- name: issuerCustomerExternalReference
in: path
description: Issuer Customer External Reference
required: true
type: string
- name: issuerAddressExternalReference
in: path
description: Issuer address external reference
required: true
type: string
- name: embed
in: query
description: Embedded Fields
required: false
type: array
items:
type: string
enum:
- addressUsages
collectionFormat: multi
responses:
'400':
description: Bad request
schema:
$ref: '#/definitions/BadRequestErrorApiResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/UnauthorizedErrorApiResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/ForbiddenErrorApiResponse'
'404':
description: Not found
schema:
$ref: '#/definitions/NotFoundErrorApiResponse'
'500':
description: Internal server error
schema:
$ref: '#/definitions/InternalServerErrorErrorApiResponse'
'502':
description: Bad gateway
schema:
$ref: '#/definitions/BadGatewayErrorApiResponse'
'200':
description: OK
schema:
$ref: '#/definitions/ApiResponseEntityAddress'
security:
- basic: []
deprecated: false
put:
tags:
- Customer - Address
summary: Update address by customer external reference and address external reference
operationId: modifyAddressByIssuerExtRefAndCustomerIssuerExtRef
description: "The API allows to update the permanent address of a customer, identified with the reference of the customer and the reference of the address.\nAll 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.\nIf the address was invalid, the address becomes valid.\n\nOne 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. \nAll the usages already linked to the address cannot be removed via this API."
consumes:
- application/json
produces:
- application/json
parameters:
- name: WL-Correlation-ID
in: header
required: false
type: string
- name: WL-Origin
in: header
required: false
type: string
- name: WL-Username
in: header
required: false
type: string
- name: filter
in: query
description: Filtered Fields
required: false
type: array
items:
type: string
collectionFormat: multi
- name: issuerId
in: path
description: Issuer ID
required: true
type: string
- name: issuerCustomerExternalReference
in: path
description: Issuer Customer External Reference
required: true
type: string
- name: issuerAddressExternalReference
in: path
description: Issuer address external reference
required: true
type: string
- in: body
name: body
required: false
schema:
$ref: '#/definitions/ModifyAddressRequest'
responses:
'400':
description: Bad request
schema:
$ref: '#/definitions/BadRequestErrorApiResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/UnauthorizedErrorApiResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/ForbiddenErrorApiResponse'
'404':
description: Not found
schema:
$ref: '#/definitions/NotFoundErrorApiResponse'
'500':
description: Internal server error
schema:
$ref: '#/definitions/InternalServerErrorErrorApiResponse'
'502':
description: Bad gateway
schema:
$ref: '#/definitions/BadGatewayErrorApiResponse'
'200':
description: OK
schema:
$ref: '#/definitions/ApiResponseEntityModifyAddressResponse'
security:
- basic: []
deprecated: false
? /issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}/addresses/external-addresses/{issuerAddressExternalReference}/invalidate
: post:
tags:
- Customer - Address
summary: Invalidate address by customer external reference and address external reference
operationId: invalidateAddressByExtCustomerRefAndExtAddress
description: "The API is used to invalidate the address identified with the customer reference (external or internal) and the address reference (external or internal).\nThe invalidation is applied only on the permanent address. \nThe address must be a postal address. If the user tries to invalidate another kind of address (PHONE/E_MAIL), an error is returned.\nThe attribute 'invalid' becomes 'true'."
consumes:
- application/json
produces:
- application/json
parameters:
- name: WL-Correlation-ID
in: header
required: false
type: string
- name: WL-Origin
in: header
required: false
type: string
- name: WL-Username
in: header
required: false
type: string
- name: issuerId
in: path
description: Issuer ID
required: true
type: string
- name: issuerCustomerExternalReference
in: path
description: Issuer Customer External Reference
required: true
type: string
- name: issuerAddressExternalReference
in: path
description: Issuer address external reference
required: true
type: string
responses:
'400':
description: Bad request
schema:
$ref: '#/definitions/BadRequestErrorApiResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/UnauthorizedErrorApiResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/ForbiddenErrorApiResponse'
'404':
description: Not found
schema:
$ref: '#/definitions/NotFoundErrorApiResponse'
'500':
description: Internal server error
schema:
$ref: '#/definitions/InternalServerErrorErrorApiResponse'
'502':
description: Bad gateway
schema:
$ref: '#/definitions/BadGatewayErrorApiResponse'
'200':
description: OK
schema:
$ref: '#/definitions/ApiResponseEntityInvalidateAddressResponse'
security:
- basic: []
deprecated: false
/issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}/addresses/{addressReference}/invalidate:
post:
tags:
- Customer - Address
summary: Invalidate address by customer external reference
operationId: invalidateAddressByExtCustomerAndAddress
description: "The API is used to invalidate the address identified with the customer reference (external or internal) and the address reference (external or internal).\nThe invalidation is applied only on the permanent address. \nThe address must be a postal address. If the user tries to invalidate another kind of address (PHONE/E_MAIL), an error is returned.\nThe attribute 'invalid' becomes 'true'."
consumes:
- application/json
produces:
- application/json
parameters:
- name: WL-Correlation-ID
in: header
required: false
type: string
- name: WL-Origin
in: header
required: false
type: string
- name: WL-Username
in: header
required: false
type: string
- name: issuerId
in: path
description: Issuer ID
required: true
type: string
- name: issuerCustomerExternalReference
in: path
description: Issuer Customer External Reference
required: true
type: string
- name: addressReference
in: path
description: Address Reference
required: true
type: string
responses:
'400':
description: Bad request
schema:
$ref: '#/definitions/BadRequestErrorApiResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/UnauthorizedErrorApiResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/ForbiddenErrorApiResponse'
'404':
description: Not found
schema:
$ref: '#/definitions/NotFoundErrorApiResponse'
'500':
description: Internal server error
schema:
$ref: '#/definitions/InternalServerErrorErrorApiResponse'
'502':
description: Bad gateway
schema:
$ref: '#/definitions/BadGatewayErrorApiResponse'
'200':
description: OK
schema:
$ref: '#/definitions/ApiResponseEntityInvalidateAddressResponse'
security:
- basic: []
deprecated: false
/issuers/{issuerId}/customers/{customerReference}/addresses/external-addresses/{issuerAddressExternalReference}/invalidate:
post:
tags:
- Customer - Address
summary: Invalidate address by address external reference
operationId: invalidateAddressByCustomerAndExtAddress
description: "The API is used to invalidate the address identified with the customer reference (external or internal) and the address reference (external or internal).\nThe invalidation is applied only on the permanent address. \nThe address must be a postal address. If the user tries to invalidate another kind of address (PHONE/E_MAIL), an error is returned.\nThe attribute 'invalid' becomes 'true'."
consumes:
- application/json
produces:
- application/json
parameters:
- name: WL-Correlation-ID
in: header
required: false
type: string
- name: WL-Origin
in: header
required: false
type: string
- name: WL-Username
in: header
required: false
type: string
- name: issuerId
in: path
description: Issuer ID
required: true
type: string
- name: customerReference
in: path
description: Customer Reference
required: true
type: string
- name: issuerAddressExternalReference
in: path
description: Issuer address external reference
required: true
type: string
responses:
'400':
description: Bad request
schema:
$ref: '#/definitions/BadRequestErrorApiResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/UnauthorizedErrorApiResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/ForbiddenErrorApiResponse'
'404':
description: Not found
schema:
$ref: '#/definitions/NotFoundErrorApiResponse'
'500':
description: Internal server error
schema:
$ref: '#/definitions/InternalServerErrorErrorApiResponse'
'502':
description: Bad gateway
schema:
$ref: '#/definitions/BadGatewayErrorApiResponse'
'200':
description: OK
schema:
$ref: '#/definitions/ApiResponseEntityInvalidateAddressResponse'
security:
- basic: []
deprecated: false
/issuers/{issuerId}/customers/{customerReference}/addresses/{addressReference}/invalidate:
post:
tags:
- Customer - Address
summary: Invalidate address
operationId: invalidateAddress
description: "The API is used to invalidate the address identified with the customer reference (external or internal) and the address reference (external or internal).\nThe invalidation is applied only on the permanent address. \nThe address must be a postal address. If the user tries to invalidate another kind of address (PHONE/E_MAIL), an error is returned.\nThe attribute 'invalid' becomes 'true'."
consumes:
- application/json
produces:
- application/json
parameters:
- name: WL-Correlation-ID
in: header
required: false
type: string
- name: WL-Origin
in: header
required: false
type: string
- name: WL-Username
in: header
required: false
type: string
- name: issuerId
in: path
description: Issuer ID
required: true
type: string
- name: customerReference
in: path
description: Customer Reference
required: true
type: string
- name: addressReference
in: path
description: Address Reference
required: true
type: string
responses:
'400':
description: Bad request
schema:
$ref: '#/definitions/BadRequestErrorApiResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/UnauthorizedErrorApiResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/ForbiddenErrorApiResponse'
'404':
description: Not found
schema:
$ref: '#/definitions/NotFoundErrorApiResponse'
'500':
description: Internal server error
schema:
$ref: '#/definitions/InternalServerErrorErrorApiResponse'
'502':
description: Bad gateway
schema:
$ref: '#/definitions/BadGatewayErrorApiResponse'
'200':
description: OK
schema:
$ref: '#/definitions/ApiResponseEntityInvalidateAddressResponse'
security:
- basic: []
deprecated: false
? /issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}/addresses/external-addresses/{issuerAddressExternalReference}/activate
: post:
tags:
- Customer - Address
summary: Activate address by customer external reference and address external reference
operationId: activateAddressByIssuerExtRefAndCustomerIssuerExtRef
description: "The API allows to activate on demand of an address by providing\n•\tthe reference of the customer,\n•\tthe reference of the address\n•\tthe issuer Id.\nIf a temporary address exists, it becomes also active.\nThe address identifiers, address attributes and address usages are displayed in the response."
consumes:
- application/json
produces:
- application/json
parameters:
- name: WL-Correlation-ID
in: header
required: false
type: string
- name: WL-Origin
in: header
required: false
type: string
- name: WL-Username
in: header
required: false
type: string
- name: filter
in: query
description: Filtered Fields
required: false
type: array
items:
type: string
collectionFormat: multi
- name: issuerId
in: path
description: Issuer ID
required: true
type: string
- name: issuerCustomerExternalReference
in: path
description: Issuer Customer External Reference
required: true
type: string
- name: issuerAddressExternalReference
in: path
description: Issuer address external reference
required: true
type: string
responses:
'400':
description: Bad request
schema:
$ref: '#/definitions/BadRequestErrorApiResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/UnauthorizedErrorApiResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/ForbiddenErrorApiResponse'
'404':
description: Not found
schema:
$ref: '#/definitions/NotFoundErrorApiResponse'
'500':
description: Internal server error
schema:
$ref: '#/definitions/InternalServerErrorErrorApiResponse'
'502':
description: Bad gateway
schema:
$ref: '#/definitions/BadGatewayErrorApiResponse'
'200':
description: OK
schema:
$ref: '#/definitions/ApiResponseEntityActivateAddressResponse'
security:
- basic: []
deprecated: false
? /issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}/addresses/external-addresses/{issuerAddressExternalReference}/address-usages
: post:
tags:
- Customer - Address
summary: Add an address usage by customer external reference and address external reference
operationId: createAddressUsageByIssuerExtRefAndCustomerIssuerExtRef
description: "The address usage describes in which business case the address will be used (eg statement sending, cad delivery, ...) \nThe complete authorized values list is shared during the product configuration between the issuer and WL.\nThis 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)\nTo create an address usage, it is needed to provide:\n- The issuer ID\n- The customer reference or the issuer customer reference \n- The address reference or the issuer address reference"
consumes:
- application/json
produces:
- application/json
parameters:
- name: WL-Correlation-ID
in: header
required: false
type: string
- name: WL-Origin
in: header
required: false
type: string
- name: WL-Username
in: header
required: false
type: string
- name: filter
in: query
description: Filtered Fields
required: false
type: array
items:
type: string
collectionFormat: multi
- name: issuerId
in: path
description: Issuer ID
required: true
type: string
- name: issuerCustomerExternalReference
in: path
description: Issuer Customer External Reference
required: true
type: string
- name: issuerAddressExternalReference
in: path
description: Issuer address external reference
required: true
type: string
- in: body
name: body
required: false
schema:
$ref: '#/definitions/CreateAddressUsageRequest'
responses:
'400':
description: Bad request
schema:
$ref: '#/definitions/BadRequestErrorApiResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/UnauthorizedErrorApiResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/ForbiddenErrorApiResponse'
'404':
description: Not found
schema:
$ref: '#/definitions/NotFoundErrorApiResponse'
'500':
description: Internal server error
schema:
$ref: '#/definitions/InternalServerErrorErrorApiResponse'
'502':
description: Bad gateway
schema:
$ref: '#/definitions/BadGatewayErrorApiResponse'
'200':
description: OK
schema:
$ref: '#/definitions/ApiResponseEntityCreateAddressUsageResponse'
security:
- basic: []
deprecated: false
delete:
tags:
- Customer - Address
summary: Remove an address usage by customer external reference and address external reference
operationId: deleteAddressUsageByIssuerExtRefAndCustomerIssuerExtRef
description: "The API deletes the address usages linked to one address. \nThese address usages are filtered by the request params:\n- addressUsageName (for definition see the resource addressUsage), mandatory\n- entityReference (for definition see the resource addressUsage), optional\n- serviceCode (for definition see the resource addressUsage), mandatory\n\nIf the entityReference is empty and the API finds several addressUsages (for the addressUsageName and serviceCode in request param), then the list of addressUsages will be deleted"
consumes:
- application/json
produces:
- application/json
parameters:
- name: WL-Correlation-ID
in: header
required: false
type: string
- name: WL-Origin
in: header
required: false
type: string
- name: WL-Username
in: header
required: false
type: string
- name: filter
in: query
description: Filtered Fields
required: false
type: array
items:
type: string
collectionFormat: multi
- name: issuerId
in: path
description: Issuer ID
required: true
type: string
- name: issuerCustomerExternalReference
in: path
description: Issuer Customer External Reference
required: true
type: string
- name: issuerAddressExternalReference
in: path
description: Issuer address external reference
required: true
type: string
- name: serviceCode
in: query
description: 'The Service for which the address usage is defined : CARD_SERVICE, ACCOUNT_SERVICE. Mandatory '
required: true
type: string
- name: entityReference
in: query
description: 'This corresponds to the application domain of the address. It can be eg a card contract reference, card account reference. It is an optional field.
It enables to have the same usage address for the same customer applied to different addresses (one cardholder with 2 card contracts: card delivery address usage is assigned to main postal address for contract A and card delivery address usage is also assigned to office postal address for contract B.'
required: false
type: string
- name: addressUsageName
in: query
description: The business process for which the address usage is defined such as CARD_DELIVERY, PIN_MAILER_DELIVERY, STATEMENT_DELIVERY.
required: true
type: string
responses:
'400':
description: Bad request
schema:
$ref: '#/definitions/BadRequestErrorApiResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/UnauthorizedErrorApiResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/ForbiddenErrorApiResponse'
'404':
description: Not found
schema:
$ref: '#/definitions/NotFoundErrorApiResponse'
'500':
description: Internal server error
schema:
$ref: '#/definitions/InternalServerErrorErrorApiResponse'
'502':
description: Bad gateway
schema:
$ref: '#/definitions/BadGatewayErrorApiResponse'
'200':
description: OK
schema:
$ref: '#/definitions/ApiResponseEntityDeleteAddressUsageResponse'
security:
- basic: []
deprecated: false
? /issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}/addresses/external-addresses/{issuerAddressExternalReference}/deactivate
: post:
tags:
- Customer - Address
summary: Deactivate address by customer external reference and address external reference
operationId: deactivateAddressByIssuerExtRefAndCustomerIssuerExtRef
description: "The API is used to deactivate the address, identified with the customer reference and the address reference. \nThe status becomes \"INACTIVE\". \nThis action is forbidden in case of:\n- the address is the MAIN_POSTAL_ADDRESS\n- an usage is linked to the address."
consumes:
- application/json
produces:
- application/json
parameters:
- name: WL-Correlation-ID
in: header
required: false
type: string
- name: WL-Origin
in: header
required: false
type: string
- name: WL-Username
in: header
required: false
type: string
- name: filter
in: query
description: Filtered Fields
required: false
type: array
items:
type: string
collectionFormat: multi
- name: issuerId
in: path
description: Issuer ID
required: true
type: string
- name: issuerCustomerExternalReference
in: path
description: Issuer Customer External Reference
required: true
type: string
- name: issuerAddressExternalReference
in: path
description: Issuer address external reference
required: true
type: string
responses:
'400':
description: Bad request
schema:
$ref: '#/definitions/BadRequestErrorApiResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/UnauthorizedErrorApiResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/ForbiddenErrorApiResponse'
'404':
description: Not found
schema:
$ref: '#/definitions/NotFoundErrorApiResponse'
'500':
description: Internal server error
schema:
$ref: '#/definitions/InternalServerErrorErrorApiResponse'
'502':
description: Bad gateway
schema:
$ref: '#/definitions/BadGatewayErrorApiResponse'
'200':
description: OK
schema:
$ref: '#/definitions/ApiResponseEntityDeactivateAddressResponse'
security:
- basic: []
deprecated: false
/issuers/{issuerId}/customers/ext
# --- truncated at 32 KB (148 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/wordline/refs/heads/main/openapi/wordline-customer-address-api-openapi.yml