Worldline Customer - Address API

openapi: 3.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 Customer - Address API
  contact: {}
servers:
- url: https://sbx-wlip.api1-eu2.psapigateway.preprod.giservices.io/card-issuing/api/v2
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."
      parameters:
      - name: WL-Correlation-ID
        in: header
        required: false
        schema:
          type: string
      - name: WL-Origin
        in: header
        required: false
        schema:
          type: string
      - name: WL-Username
        in: header
        required: false
        schema:
          type: string
      - name: filter
        in: query
        description: Filtered Fields
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: issuerId
        in: path
        description: Issuer ID
        required: true
        schema:
          type: string
      - name: issuerCustomerExternalReference
        in: path
        description: Issuer Customer External Reference
        required: true
        schema:
          type: string
      responses:
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorApiResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorApiResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorApiResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorApiResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorErrorApiResponse'
        '502':
          description: Bad gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadGatewayErrorApiResponse'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseEntityCreateAddressResponse'
      security:
      - basic: []
      deprecated: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAddressRequest'
  ? /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."
      parameters:
      - name: WL-Correlation-ID
        in: header
        required: false
        schema:
          type: string
      - name: WL-Origin
        in: header
        required: false
        schema:
          type: string
      - name: WL-Username
        in: header
        required: false
        schema:
          type: string
      - name: filter
        in: query
        description: Filtered Fields
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: issuerId
        in: path
        description: Issuer ID
        required: true
        schema:
          type: string
      - name: issuerCustomerExternalReference
        in: path
        description: Issuer Customer External Reference
        required: true
        schema:
          type: string
      - name: issuerAddressExternalReference
        in: path
        description: Issuer address external reference
        required: true
        schema:
          type: string
      - name: embed
        in: query
        description: Embedded Fields
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - addressUsages
      responses:
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorApiResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorApiResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorApiResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorApiResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorErrorApiResponse'
        '502':
          description: Bad gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadGatewayErrorApiResponse'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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."
      parameters:
      - name: WL-Correlation-ID
        in: header
        required: false
        schema:
          type: string
      - name: WL-Origin
        in: header
        required: false
        schema:
          type: string
      - name: WL-Username
        in: header
        required: false
        schema:
          type: string
      - name: filter
        in: query
        description: Filtered Fields
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: issuerId
        in: path
        description: Issuer ID
        required: true
        schema:
          type: string
      - name: issuerCustomerExternalReference
        in: path
        description: Issuer Customer External Reference
        required: true
        schema:
          type: string
      - name: issuerAddressExternalReference
        in: path
        description: Issuer address external reference
        required: true
        schema:
          type: string
      responses:
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorApiResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorApiResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorApiResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorApiResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorErrorApiResponse'
        '502':
          description: Bad gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadGatewayErrorApiResponse'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseEntityModifyAddressResponse'
      security:
      - basic: []
      deprecated: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ModifyAddressRequest'
  ? /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'."
      parameters:
      - name: WL-Correlation-ID
        in: header
        required: false
        schema:
          type: string
      - name: WL-Origin
        in: header
        required: false
        schema:
          type: string
      - name: WL-Username
        in: header
        required: false
        schema:
          type: string
      - name: issuerId
        in: path
        description: Issuer ID
        required: true
        schema:
          type: string
      - name: issuerCustomerExternalReference
        in: path
        description: Issuer Customer External Reference
        required: true
        schema:
          type: string
      - name: issuerAddressExternalReference
        in: path
        description: Issuer address external reference
        required: true
        schema:
          type: string
      responses:
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorApiResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorApiResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorApiResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorApiResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorErrorApiResponse'
        '502':
          description: Bad gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadGatewayErrorApiResponse'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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'."
      parameters:
      - name: WL-Correlation-ID
        in: header
        required: false
        schema:
          type: string
      - name: WL-Origin
        in: header
        required: false
        schema:
          type: string
      - name: WL-Username
        in: header
        required: false
        schema:
          type: string
      - name: issuerId
        in: path
        description: Issuer ID
        required: true
        schema:
          type: string
      - name: issuerCustomerExternalReference
        in: path
        description: Issuer Customer External Reference
        required: true
        schema:
          type: string
      - name: addressReference
        in: path
        description: Address Reference
        required: true
        schema:
          type: string
      responses:
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorApiResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorApiResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorApiResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorApiResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorErrorApiResponse'
        '502':
          description: Bad gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadGatewayErrorApiResponse'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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'."
      parameters:
      - name: WL-Correlation-ID
        in: header
        required: false
        schema:
          type: string
      - name: WL-Origin
        in: header
        required: false
        schema:
          type: string
      - name: WL-Username
        in: header
        required: false
        schema:
          type: string
      - name: issuerId
        in: path
        description: Issuer ID
        required: true
        schema:
          type: string
      - name: customerReference
        in: path
        description: Customer Reference
        required: true
        schema:
          type: string
      - name: issuerAddressExternalReference
        in: path
        description: Issuer address external reference
        required: true
        schema:
          type: string
      responses:
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorApiResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorApiResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorApiResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorApiResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorErrorApiResponse'
        '502':
          description: Bad gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadGatewayErrorApiResponse'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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'."
      parameters:
      - name: WL-Correlation-ID
        in: header
        required: false
        schema:
          type: string
      - name: WL-Origin
        in: header
        required: false
        schema:
          type: string
      - name: WL-Username
        in: header
        required: false
        schema:
          type: string
      - name: issuerId
        in: path
        description: Issuer ID
        required: true
        schema:
          type: string
      - name: customerReference
        in: path
        description: Customer Reference
        required: true
        schema:
          type: string
      - name: addressReference
        in: path
        description: Address Reference
        required: true
        schema:
          type: string
      responses:
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorApiResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorApiResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorApiResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorApiResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorErrorApiResponse'
        '502':
          description: Bad gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadGatewayErrorApiResponse'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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."
      parameters:
      - name: WL-Correlation-ID
        in: header
        required: false
        schema:
          type: string
      - name: WL-Origin
        in: header
        required: false
        schema:
          type: string
      - name: WL-Username
        in: header
        required: false
        schema:
          type: string
      - name: filter
        in: query
        description: Filtered Fields
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: issuerId
        in: path
        description: Issuer ID
        required: true
        schema:
          type: string
      - name: issuerCustomerExternalReference
        in: path
        description: Issuer Customer External Reference
        required: true
        schema:
          type: string
      - name: issuerAddressExternalReference
        in: path
        description: Issuer address external reference
        required: true
        schema:
          type: string
      responses:
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorApiResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorApiResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorApiResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorApiResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorErrorApiResponse'
        '502':
          description: Bad gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadGatewayErrorApiResponse'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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"
      parameters:
      - name: WL-Correlation-ID
        in: header
        required: false
        schema:
          type: string
      - name: WL-Origin
        in: header
        required: false
        schema:
          type: string
      - name: WL-Username
        in: header
        required: false
        schema:
          type: string
      - name: filter
        in: query
        description: Filtered Fields
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: issuerId
        in: path
        description: Issuer ID
        required: true
        schema:
          type: string
      - name: issuerCustomerExternalReference
        in: path
        description: Issuer Customer External Reference
        required: true
        schema:
          type: string
      - name: issuerAddressExternalReference
        in: path
        description: Issuer address external reference
        required: true
        schema:
          type: string
      responses:
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorApiResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorApiResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorApiResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorApiResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorErrorApiResponse'
        '502':
          description: Bad gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadGatewayErrorApiResponse'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseEntityCreateAddressUsageResponse'
      security:
      - basic: []
      deprecated: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAddressUsageRequest'
    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"
      parameters:
      - name: WL-Correlation-ID
        in: header
        required: false
        schema:
          type: string
      - name: WL-Origin
        in: header
        required: false
        schema:
          type: string
      - name: WL-Username
        in: header
        required: false
        schema:
          type: string
      - name: filter
        in: query
        description: Filtered Fields
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: issuerId
        in: path
        description: Issuer ID
        required: true
        schema:
          type: string
      - name: issuerCustomerExternalReference
        in: path
        description: Issuer Customer External Reference
        required: true
        schema:
          type: string
      - name: issuerAddressExternalReference
        in: path
        description: Issuer address external reference
        required: true
        schema:
          type: string
      - name: serviceCode
        in: query
        description: 'The Service for which the address usage is defined : CARD_SERVICE, ACCOUNT_SERVICE. Mandat

# --- truncated at 32 KB (170 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/wordline/refs/heads/main/openapi/wordline-customer-address-api-openapi.yml