Worldline Company - 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 Company - Address API
  contact: {}
servers:
- url: https://sbx-wlip.api1-eu2.psapigateway.preprod.giservices.io/card-issuing/api/v2
tags:
- name: Company - Address
  description: Company Address Api Controller
paths:
  /issuers/{issuerId}/companies/{customerReference}/addresses:
    post:
      x-wl-idempotent: true
      tags:
      - Company - Address
      summary: Create address for a company customer
      operationId: createCompanyAddressByCustomerRef
      description: "The API allows to create either a permanent address or a temporary address for the company, identified with his reference. \nTo identify the company, it is needed to provide:\n- The issuer ID\n- The customer reference or the issuer customer reference (as company)\nAn address includes the following information:\n•\tthe issuer address external reference \n•\tthe label (e.g. HEAD_OFFICE)\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\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 head office 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: customerReference
        in: path
        description: Customer 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}/companies/{customerReference}/addresses/{addressReference}:
    get:
      tags:
      - Company - Address
      summary: Retrieve company's address information by address ref
      operationId: retrieveCompanyAddressByCustomerRefAndAddressRef
      description: "The API returns the current version of a company's address.\nInformation to be provided in input:\n- The issuer ID\n- The customer reference or the issuer customer reference (as company)\n- The address reference or the issuer address reference \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: issuerId
        in: path
        description: issuerId
        required: true
        schema:
          type: string
      - name: customerReference
        in: path
        description: customerReference
        required: true
        schema:
          type: string
      - name: addressReference
        in: path
        description: addressReference
        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
      - name: filter
        in: query
        description: Filtered Fields
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseEntityCompany'
        '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'
      security:
      - basic: []
      deprecated: false
    put:
      tags:
      - Company - Address
      summary: Update company address
      operationId: modifyCompanyAddress
      description: "The API updates all the attributes of a company's address.\nTo identify the address of the company for which updates are required, it is needed to provide:\n- The issuer ID\n- The customer reference or the issuer customer reference (as company) \n- The address reference or the issuer address reference\nAll the attributes must be provided even those unchanged (except for the usages).\nThe API allows to validate an address ('invalid' status is set to false). But it's not possible to invalidate an address changing the value of the invalid 'flag' to true. If the user tries to do this action, an error message is returned.\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. \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: 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/ApiResponseEntityModifyAddressResponse'
      security:
      - basic: []
      deprecated: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ModifyAddressRequest'
  /issuers/{issuerId}/companies/{customerReference}/addresses/external-addresses/{issuerAddressExternalReference}:
    get:
      tags:
      - Company - Address
      summary: Retrieve company's address information by address external reference
      operationId: retrieveCompanyAddressByCustomerRefAndExtAddressRef
      description: "The API returns the current version of a company's address.\nInformation to be provided in input:\n- The issuer ID\n- The customer reference or the issuer customer reference (as company)\n- The address reference or the issuer address reference \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: issuerId
        in: path
        description: issuerId
        required: true
        schema:
          type: string
      - name: customerReference
        in: path
        description: customerReference
        required: true
        schema:
          type: string
      - name: issuerAddressExternalReference
        in: path
        description: issuerAddressExternalReference
        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
      - name: filter
        in: query
        description: Filtered Fields
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseEntityCompany'
        '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'
      security:
      - basic: []
      deprecated: false
    put:
      tags:
      - Company - Address
      summary: Update company address by external address reference
      operationId: modifyCompanyAddressByCustomerRefAndExtAddressRef
      description: "The API updates all the attributes of a company's address.\nTo identify the address of the company for which updates are required, it is needed to provide:\n- The issuer ID\n- The customer reference or the issuer customer reference (as company) \n- The address reference or the issuer address reference\nAll the attributes must be provided even those unchanged (except for the usages).\nThe API allows to validate an address ('invalid' status is set to false). But it's not possible to invalidate an address changing the value of the invalid 'flag' to true. If the user tries to do this action, an error message is returned.\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. \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: 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/ApiResponseEntityModifyAddressResponse'
      security:
      - basic: []
      deprecated: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ModifyAddressRequest'
  /issuers/{issuerId}/companies/external-customers/{issuerCustomerExternalReference}/addresses:
    post:
      x-wl-idempotent: true
      tags:
      - Company - Address
      summary: Create address for a company by external reference
      operationId: createCompanyAddressByCustomerIssuerExtRef
      description: "The API allows to create either a permanent address or a temporary address for the company, identified with his reference. \nTo identify the company, it is needed to provide:\n- The issuer ID\n- The customer reference or the issuer customer reference (as company)\nAn address includes the following information:\n•\tthe issuer address external reference \n•\tthe label (e.g. HEAD_OFFICE)\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\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 head office 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}/companies/external-customers/{issuerCustomerExternalReference}/addresses/{addressReference}:
    get:
      tags:
      - Company - Address
      summary: Retrieve address information by company external reference
      operationId: retrieveCompanyByIssuerExtRefAndAddressRef
      description: "The API returns the current version of a company's address.\nInformation to be provided in input:\n- The issuer ID\n- The customer reference or the issuer customer reference (as company)\n- The address reference or the issuer address reference \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: issuerId
        in: path
        description: issuerId
        required: true
        schema:
          type: string
      - name: issuerCustomerExternalReference
        in: path
        description: issuerCustomerExternalReference
        required: true
        schema:
          type: string
      - name: addressReference
        in: path
        description: addressReference
        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
      - name: filter
        in: query
        description: Filtered Fields
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseEntityCompany'
        '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'
      security:
      - basic: []
      deprecated: false
    put:
      tags:
      - Company - Address
      summary: Update company address by company external reference
      operationId: modifyCompanyAddressByCustomerExtRefAndAddressRef
      description: "The API updates all the attributes of a company's address.\nTo identify the address of the company for which updates are required, it is needed to provide:\n- The issuer ID\n- The customer reference or the issuer customer reference (as company) \n- The address reference or the issuer address reference\nAll the attributes must be provided even those unchanged (except for the usages).\nThe API allows to validate an address ('invalid' status is set to false). But it's not possible to invalidate an address changing the value of the invalid 'flag' to true. If the user tries to do this action, an error message is returned.\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. \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: 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/ApiResponseEntityModifyAddressResponse'
      security:
      - basic: []
      deprecated: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ModifyAddressRequest'
  ? /issuers/{issuerId}/companies/external-customers/{issuerCustomerExternalReference}/addresses/external-addresses/{issuerAddressExternalReference}
  : get:
      tags:
      - Company - Address
      summary: Retrieve address information by company external reference and address external reference
      operationId: retrieveCompanyAddressByIssuerExtRefAndAddressExtRef
      description: "The API returns the current version of a company's address.\nInformation to be provided in input:\n- The issuer ID\n- The customer reference or the issuer customer reference (as company)\n- The address reference or the issuer address reference \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: issuerId
        in: path
        description: issuerId
        required: true
        schema:
          type: string
      - name: issuerCustomerExternalReference
        in: path
        description: issuerCustomerExternalReference
        required: true
        schema:
          type: string
      - name: issuerAddressExternalReference
        in: path
        description: issuerAddressExternalReference
        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
      - name: filter
        in: query
        description: 

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