openapi: 3.2.0
info:
  title: ClearBank Retail V2 Customer API
  contact:
    name: API Support
    url: https://clear.bank
    email: fiapisupport@clear.bank
  version: 2.0-customers-retail
tags:
- name: Customer
paths:
  /customers/v2/customers/{customerId}:
    get:
      tags:
      - Customer
      summary: Retrieves a customer by their customer ID.
      operationId: V2CustomerGet
      parameters:
      - name: Authorization
        in: header
        description: Your API token, retrieved from the web portal.
        required: true
        schema:
          type: string
      - name: DigitalSignature
        in: header
        description: Signed hash of the body of the request. The hash is signed by your private key.
        required: true
        schema:
          type: string
      - name: X-Request-Id
        in: header
        description: A unique identifier for the request.
        required: true
        schema:
          type: string
      - name: customerId
        in: path
        description: The ID of the customer.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetailCustomerGetResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Forbidden
  /customers/v2/customers/{customerId}/related-parties:
    get:
      tags:
      - Customer
      summary: Retrieves the related party data of a customer by their customer ID.
      operationId: V2RelatedPartiesGet
      parameters:
      - name: Authorization
        in: header
        description: Your API token, retrieved from the web portal.
        required: true
        schema:
          type: string
      - name: DigitalSignature
        in: header
        description: Signed hash of the body of the request. The hash is signed by your private key.
        required: true
        schema:
          type: string
      - name: X-Request-Id
        in: header
        description: A unique identifier for the request.
        required: true
        schema:
          type: string
      - name: customerId
        in: path
        description: The ID of the original customer.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/RelatedPartyGetResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Forbidden
    post:
      tags:
      - Customer
      summary: 'Adds a new related party to an existing customer. Note that relationships must be unique: if a relationship already exists that links the same two customers with the same relationship type, your request will be rejected.'
      operationId: V2RelatedPartyPost
      parameters:
      - name: Authorization
        in: header
        description: Your API token, retrieved from the web portal.
        required: true
        schema:
          type: string
      - name: DigitalSignature
        in: header
        description: Signed hash of the body of the request. The hash is signed by your private key.
        required: true
        schema:
          type: string
      - name: X-Request-Id
        in: header
        description: A unique identifier for the request.
        required: true
        schema:
          type: string
      - name: customerId
        in: path
        description: The ID of the original customer.
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        description: Information required to add related party to customer.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRelatedPartyRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatedRelatedPartyResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '403':
          description: Forbidden
  /customers/v2/customers/{customerId}/current-addresses:
    post:
      tags:
      - Customer
      summary: Updates a customer's current address while maintaining their previous addresses history.
      operationId: V2CustomersCurrentAddressPost
      parameters:
      - name: Authorization
        in: header
        description: Your API token, retrieved from the web portal.
        required: true
        schema:
          type: string
      - name: DigitalSignature
        in: header
        description: Signed hash of the body of the request. The hash is signed by your private key.
        required: true
        schema:
          type: string
      - name: X-Request-Id
        in: header
        description: A unique identifier for the request.
        required: true
        schema:
          type: string
      - name: customerId
        in: path
        description: The ID of the customer.
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        description: Information required to update the customer's address
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CurrentAddressRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerSubresourceCreatedResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '403':
          description: Forbidden
  /customers/v2/customers/{customerId}/related-parties/{relatedCustomerId}/{relatedPartyType}:
    delete:
      tags:
      - Customer
      summary: Removes a related party link between two customers.
      operationId: V2RelatedPartyDelete
      parameters:
      - name: Authorization
        in: header
        description: Your API token, retrieved from the web portal.
        required: true
        schema:
          type: string
      - name: DigitalSignature
        in: header
        description: Signed hash of the body of the request. The hash is signed by your private key.
        required: true
        schema:
          type: string
      - name: X-Request-Id
        in: header
        description: A unique identifier for the request.
        required: true
        schema:
          type: string
      - name: customerId
        in: path
        description: The ID of the customer.
        required: true
        schema:
          type: string
          format: uuid
      - name: relatedCustomerId
        in: path
        description: The ID of the related customer to unlink.
        required: true
        schema:
          type: string
          format: uuid
      - name: relatedPartyType
        in: path
        description: The type of related party. Used to disambiguate where a party is related in more than one way.
        required: true
        schema:
          $ref: '#/components/schemas/RelatedPartyType'
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '403':
          description: Forbidden
  /customers/v2/customers/{customerId}/identity-documents/{idCountryOfIssue}-{idType}:
    put:
      tags:
      - Customer
      summary: Adds or updates a customer's identity document. Returns 200 OK when updating an existing ID, or 201 Created when adding a new ID.
      operationId: V2CustomerIdentityDocumentPut
      parameters:
      - name: Authorization
        in: header
        description: Your API token, retrieved from the web portal.
        required: true
        schema:
          type: string
      - name: DigitalSignature
        in: header
        description: Signed hash of the body of the request. The hash is signed by your private key.
        required: true
        schema:
          type: string
      - name: X-Request-Id
        in: header
        description: A unique identifier for the request.
        required: true
        schema:
          type: string
      - name: customerId
        in: path
        description: The ID of the customer.
        required: true
        schema:
          type: string
          format: uuid
      - name: idCountryOfIssue
        in: path
        description: Country of issue.
        required: true
        schema:
          $ref: '#/components/schemas/CountryCode'
      - name: idType
        in: path
        description: Type of identity document.
        required: true
        schema:
          $ref: '#/components/schemas/IdType'
      requestBody:
        description: The updated details of the identity document.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateIdentityDocumentRequest'
      responses:
        '200':
          description: OK
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerSubresourceCreatedResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '403':
          description: Forbidden
    delete:
      tags:
      - Customer
      summary: Removes a customer's identity document.
      operationId: V2CustomerIdentityDocumentDelete
      parameters:
      - name: Authorization
        in: header
        description: Your API token, retrieved from the web portal.
        required: true
        schema:
          type: string
      - name: DigitalSignature
        in: header
        description: Signed hash of the body of the request. The hash is signed by your private key.
        required: true
        schema:
          type: string
      - name: X-Request-Id
        in: header
        description: A unique identifier for the request.
        required: true
        schema:
          type: string
      - name: customerId
        in: path
        description: The ID of the customer.
        required: true
        schema:
          type: string
          format: uuid
      - name: idCountryOfIssue
        in: path
        description: Country of issue.
        required: true
        schema:
          $ref: '#/components/schemas/CountryCode'
      - name: idType
        in: path
        description: Type of identity document.
        required: true
        schema:
          $ref: '#/components/schemas/IdType'
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Forbidden
  /customers/v2/customers/{customerId}/tax-residencies/{countryOfTaxResidence}:
    put:
      tags:
      - Customer
      summary: Adds or updates a customer's tax residency entry for the specified country. Returns 200 OK when updating an existing tax residency, or 201 Created when adding a new tax residency.
      operationId: V2CustomerTaxResidencyPut
      parameters:
      - name: Authorization
        in: header
        description: Your API token, retrieved from the web portal.
        required: true
        schema:
          type: string
      - name: DigitalSignature
        in: header
        description: Signed hash of the body of the request. The hash is signed by your private key.
        required: true
        schema:
          type: string
      - name: X-Request-Id
        in: header
        description: A unique identifier for the request.
        required: true
        schema:
          type: string
      - name: customerId
        in: path
        description: The ID of the customer.
        required: true
        schema:
          type: string
          format: uuid
      - name: countryOfTaxResidence
        in: path
        description: Country of tax residence.
        required: true
        schema:
          $ref: '#/components/schemas/CountryCode'
      requestBody:
        description: Tax residency details (TIN or reason for no TIN).
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTaxResidencyRequest'
      responses:
        '200':
          description: OK
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerSubresourceCreatedResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '403':
          description: Forbidden
    delete:
      tags:
      - Customer
      summary: Removes a customer's tax residency entry for the specified country.
      operationId: V2CustomerTaxResidencyDelete
      parameters:
      - name: Authorization
        in: header
        description: Your API token, retrieved from the web portal.
        required: true
        schema:
          type: string
      - name: DigitalSignature
        in: header
        description: Signed hash of the body of the request. The hash is signed by your private key.
        required: true
        schema:
          type: string
      - name: X-Request-Id
        in: header
        description: A unique identifier for the request.
        required: true
        schema:
          type: string
      - name: customerId
        in: path
        description: The ID of the customer.
        required: true
        schema:
          type: string
          format: uuid
      - name: countryOfTaxResidence
        in: path
        description: Country of tax residence to remove.
        required: true
        schema:
          $ref: '#/components/schemas/CountryCode'
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '403':
          description: Forbidden
components:
  schemas:
    CurrentAddressRequest:
      required:
      - addressType
      - buildingNameNumber
      - streetName
      - city
      - country
      - postalCode
      type: object
      properties:
        addressType:
          $ref: '#/components/schemas/AddressType'
        buildingNameNumber:
          minLength: 1
          maxLength: 100
          pattern: '[^!$%^_=+><?|;~@`]'
          type:
          - string
          - 'null'
          description: The building name or number of this address. Must not contain postal code.
          example: '322'
        streetName:
          type:
          - string
          - 'null'
          minLength: 1
          maxLength: 100
          pattern: '[^!$%^_=+><?|;~@`]'
          description: This address' street name. Must not contain postal code.
          example: Long Road
        city:
          minLength: 1
          type:
          - string
          - 'null'
          description: City of the customer's address.
          example: Cyan City
        county:
          minLength: 1
          type:
          - string
          - 'null'
          description: County of the customer's address. Must not contain the values of buildingNameNumber or streetName fields.
          example: Greenshire
        postalCode:
          minLength: 1
          type:
          - string
          - 'null'
          description: Postal code of the customer's address. If this address is in the UK, must be a valid UK postcode and conform to the regex pattern.
          example: PG15 8AB
          pattern: ^([Gg][Ii][Rr] 0[Aa]{2})|((([A-Za-z][0-9]{1,2})|(([A-Za-z][A-Ha-hJ-Yj-y][0-9]{1,2})|(([A-Za-z][0-9][A-Za-z])|([A-Za-z][A-Ha-hJ-Yj-y][0-9]?[A-Za-z])))) [0-9][A-Za-z]{2})$
        country:
          $ref: '#/components/schemas/CountryCode'
        validFrom:
          type:
          - string
          - 'null'
          description: Date from which the address is valid. Defaults to today if unspecified.
          format: date
          example: '2022-05-22'
      additionalProperties: false
      description: The customer's current address.
    PersonalDetailsGetResponse:
      type: object
      properties:
        firstName:
          minLength: 1
          maxLength: 255
          type:
          - string
          - 'null'
          description: Customer's first name
          example: Kirsty
          pattern: '[^0-9!$%^_=+><?|;~@£&()/\\[\]{}:",#`¬]{1,255}'
        middleName:
          type:
          - string
          - 'null'
          description: Customer's middle name
          example: Jane
        surname:
          minLength: 1
          maxLength: 255
          type:
          - string
          - 'null'
          description: Customer's surname
          example: Friar
          pattern: '[^0-9!$%^_=+><?|;~@£&()/\\[\]{}:",#`¬]{1,255}'
        email:
          type:
          - string
          - 'null'
          description: Customer's email address. Must be RFC compliant.
          example: kristy.fr@mymail.com
        telephone:
          type:
          - string
          - 'null'
          minLength: 3
          maxLength: 20
          description: The customer's telephone number.  Must start with '00' in place of '+', and include the country-code.
          example: '00441234555777'
          pattern: ^(00)[0-9]{1,18}$
        countryOfResidence:
          $ref: '#/components/schemas/CountryCode'
        dateOfBirth:
          type:
          - string
          - 'null'
          description: Customer's Date of Birth
          format: date
          example: '1985-12-22'
        nationalIdentificationNumber:
          type:
          - string
          - 'null'
          description: Updated national identification number (if changed).
          example: PC112233D
      additionalProperties: false
      description: Customer's personal details
    CreateRelatedPartyRequest:
      required:
      - relatedCustomerId
      - relatedPartyType
      type: object
      properties:
        relatedCustomerId:
          type: string
          description: The ID of the customer to be linked as a related party.
          format: uuid
        relatedPartyType:
          $ref: '#/components/schemas/RelatedPartyType'
        ownershipPercentage:
          type:
          - integer
          - 'null'
          description: The ownership percentage of the related party. Only allowed for UBO relationships.
          format: int32
          example: 100
      additionalProperties: false
      description: A request to link one customer to another as a related party.
    ValidationProblemDetails:
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
          description: A URI reference [RFC3986] that identifies the problem type. This specification encourages that, when dereferenced, it provides human-readable documentation for the problem type (e.g., using HTML [W3C.REC-html5-20141028]). When this member is not present, its value is assumed to be "about:blank".
        title:
          type:
          - string
          - 'null'
          description: A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization (e.g., using proactive content negotiation; see[RFC7231], Section 3.4).
        status:
          type:
          - integer
          - 'null'
          description: The HTTP status code([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.
          format: int32
        detail:
          type:
          - string
          - 'null'
          description: A human-readable explanation specific to this occurrence of the problem.
        instance:
          type:
          - string
          - 'null'
          description: A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
        errors:
          type:
          - object
          - 'null'
          additionalProperties:
            type: array
            items:
              type: string
          description: The validation errors.
      additionalProperties: {}
      description: A machine-readable format for specifying errors in HTTP API responses based on https://tools.ietf.org/html/rfc7807
    CreatedRelatedPartyResponse:
      type: object
      properties:
        customerId:
          type: string
          description: Unique identifier of the original customer.
          format: uuid
        relatedCustomerId:
          type: string
          description: Unique identifier of the newly linked customer.
          format: uuid
      additionalProperties: false
      description: Response containing information about the created related party.
    SpecialStatusValue:
      enum:
      - Vulnerability_Health_VisualImpairmentBraille
      - Vulnerability_Health_VisualImpairmentLargeText
      - Vulnerability_Health_AudioImpairment
      - Vulnerability_Health_Other
      - Vulnerability_LifeEvents
      - Vulnerability_Resilience
      - Vulnerability_Capability
      type: string
      example: Vulnerability_LifeEvents
      description: Supported special statuses.
    CustomerStatus:
      enum:
      - Active
      type: string
      example: Active
      description: Represents the status of a customer in the system. This will always be 'Active'.
    ProblemDetails:
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
          description: A URI reference [RFC3986] that identifies the problem type. This specification encourages that, when dereferenced, it provides human-readable documentation for the problem type (e.g., using HTML [W3C.REC-html5-20141028]). When this member is not present, its value is assumed to be "about:blank".
        title:
          type:
          - string
          - 'null'
          description: A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization (e.g., using proactive content negotiation; see[RFC7231], Section 3.4).
        status:
          type:
          - integer
          - 'null'
          description: The HTTP status code([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.
          format: int32
        detail:
          type:
          - string
          - 'null'
          description: A human-readable explanation specific to this occurrence of the problem.
        instance:
          type:
          - string
          - 'null'
          description: A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
      description: A machine-readable format for specifying errors in HTTP API responses based on https://tools.ietf.org/html/rfc7807
    AddressGetResponse:
      type: object
      properties:
        addressType:
          $ref: '#/components/schemas/AddressType'
        buildingNameNumber:
          type:
          - string
          - 'null'
          description: The building name or number at this address.
          example: '322'
        streetName:
          type:
          - string
          - 'null'
          description: The customer's address' street name.
          example: Long Road
        county:
          type:
          - string
          - 'null'
          description: County of the customer's address.
          example: Greenshire
        city:
          type:
          - string
          - 'null'
          minLength: 1
          description: City of the customer's address.
          example: Cyan City
        postalCode:
          type:
          - string
          - 'null'
          description: Postal code of the customer's address. If this address is in the UK, must be a valid UK postcode and conform to the regex pattern.
          example: PG15 8AB
          pattern: ^([Gg][Ii][Rr] 0[Aa]{2})|((([A-Za-z][0-9]{1,2})|(([A-Za-z][A-Ha-hJ-Yj-y][0-9]{1,2})|(([A-Za-z][0-9][A-Za-z])|([A-Za-z][A-Ha-hJ-Yj-y][0-9]?[A-Za-z])))) [0-9][A-Za-z]{2})$
        country:
          $ref: '#/components/schemas/CountryCode'
        validFrom:
          type:
          - string
          - 'null'
          description: The date from which the customer started living at this address.
          format: date
          example: '2022-05-15'
        validTo:
          type:
          - string
          - 'null'
          description: The date at which the customer stopped living at this address.
          format: date
        isCurrentAddress:
          type:
          - boolean
          - 'null'
          description: Indicates if this is the customer's current address.
      additionalProperties: false
      description: The details of the customer's address history.
    RelatedPartyType:
      enum:
      - Director
      - UBO
      - ControllingPerson
      type: string
      example: UBO
      description: Related party types.
    RetailCustomerGetResponse:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the customer. You should keep note of this, as you'll need it to amend or access the customer later.
          format: uuid
          example: 0e7ce040-b157-44a4-ba29-ed5e9b259cd3
        institutionId:
          type: string
          description: The unique identifier of the institution associated with this customer.
          format: uuid
          example: 2500fbf8-787f-425d-b630-bde0d1c6ff58
        status:
          $ref: '#/components/schemas/CustomerStatus'
        type:
          $ref: '#/components/schemas/CustomerType'
        personalDetails:
          $ref: '#/components/schemas/PersonalDetailsGetResponse'
        kycAml:
          $ref: '#/components/schemas/KycAmlGetResponse'
        taxDetails:
          $ref: '#/components/schemas/TaxDetailsGetResponse'
        specialStatuses:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/SpecialStatusValue'
          description: 'The customer''s special statuses, if any. Possible values include: ''Vulnerability_Health_VisualImpairmentBraille'', ''Vulnerability_Health_VisualImpairmentLargeText'', ''Vulnerability_Health_AudioImpairment'', ''Vulnerability_Health_Other'', ''Vulnerability_LifeEvents'', ''Vulnerability_Resilience'', and ''Vulnerability_Capability'''
        identityDocuments:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/IdentityDocumentsGetResponse'
          description: Array of the customer's identity document details.
        addresses:
          $ref: '#/components/schemas/AddressHistoryGetResponse'
      additionalProperties: false
      description: The Retail Customer type response body.
    KycAmlGetResponse:
      type: object
      properties:
        sanctions:
          type:
          - boolean
          - 'null'
          description: Indicates if the customer is under sanctions.
        pep:
          $ref: '#/components/schemas/PepType'
        rca:
          $ref: '#/components/schemas/RcaType'
        craRating:
          $ref: '#/components/schemas/CraRating'
      additionalProperties: false
      description: KYC/AML information of the customer.
    UpdateTaxResidencyRequest:
      type: object
      properties:
        taxIdNumber:
          minLength: 1
          type:
          - string
          - 'null'
          description: Tax identification number. If not provided, you must specify a noTaxIdReason.
          example: PC335577B
        noTaxIdReason:
          $ref: '#/components/schemas/ReasonForNoTaxId'
      additionalProperties: false
      description: The customer's tax residency update request.
    PreviousAddressGetResponse:
      type: object
      properties:
        addressType:
          $ref: '#/components/schemas/AddressType'
        buildingNameNumber:
          type:
          - string
          - 'null'
          description: The building name or number at this address.
          example: '9'
        streetName:
          type:
          - string
          - 'null'
          description: The customer's address' street name.
          example: Short Road
        county:
          type:
          - string
          - 'null'
          description: County of the customer's address.
          example: Blueshire
        city:
          type:
          - string
          - 'null'
          minLength: 1
          description: City of the customer's address.
          example: Lilac City
        postalCode:
          type:
          - string
          - 'null'
          description: Postal code of the customer's address. If this address is in the UK, must be a valid UK postcode and conform to the regex pattern.
          example: LB1 7CC
          pattern: ^([Gg][Ii][Rr] 0[Aa]{2})|((([A-Za-z][0-9]{1,2})|(([A-Za-z][A-Ha-hJ-Yj-y][0-9]{1,2})|(([A-Za-z][0-9][A-Za-z])|([A-Za-z][A-Ha-hJ-Yj-y][0-9]?[A-Za-z])))) [0-9][A-Za-z]{2})$
        country:
          $ref: '#/components/schemas/CountryCode'
        validFrom:
          type:
          - string
          - 'null'
          description: The date from which the customer started living at this address.
          format: date
          example: '2021-02-18'
        validTo:
          type:
          - string
          - 'null'
          description: The date at which the customer stopped living at this address.
          format: date
          example: '2022-05-15'
        isCurrentAddress:
          type:
          - boolean
          - 'null'
          description: Indicates if this is the customer's current address.
          example: false
      additionalProperties: false
      description: The details of the customer's address history.
    CraRating:
      enum:
      - LowRisk
      - MediumRisk
      - HighRisk
      - VeryHighRisk
      type: string
      description: The customer's CRA rating. Determined by the outcomes of your due diligence checks.
    CustomerType:
      enum:
      - Retail
      type: string
      example: Retail
      description: The type of customer. This will always be 'Retail'.
    CustomerSubresourceCreatedResponse:
      type: object
      properties:
        customerId:
          type: string
          description: The ID of the customer under which the subresource was created.
          format: uuid
      additionalProperties: false
      description: Represents the response returned when a subresource is created for a customer.
    IdentityDocumentsGetResponse:
      type: object
      properties:
        idNumber:
          type:
          - string
          - 'null'
          description: The ID number of the identity document.
          example: PC335577B
        expiryDate:
          type:
          - string
          - 'null'
          description: The expiry date of the identity document.
          format: date
        countryOfIssue:
          $ref: '#/components/schemas/CountryCode'
        type:
          $ref: '#/components/schemas/IdType'
      additionalProperties: false
      description: Customer's Identity documents
    TaxDetailsGetResponse:
      type: object
      properties:
        taxResidencies:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/TaxResidencyGetResponse'
          description: Collection of tax residencies of the customer.
        validSelfCertification:
          type:
          - boolean
          - 'null'
          description: Indicates if self-certification is valid.
        usPerson:
          $ref: '#/components/schemas/USPerson'
      additionalProperties: false
      description: Tax details of the customer.
    USPerson:
      enum:
      - NotAUSPerson
      - SpecifiedUSPerson
      - USPersonOtherThanASpecifiedUSPerson
      type: string
      description: Specifies the classification of a person as a U.S. person for regulatory or reporting purposes.
    ReasonForNoTaxId:
      enum:
      - CountryDoesNotIssue
      - UnableToObtain
      - NotRequired
      type: string
      description: Supported reasons for not having a tax ID (required if no tax ID number provided).
    TaxResidencyGetResponse:
      type: object
      properties:
        countryOfTaxResidence:
          $ref: '#/components/schemas/CountryCode'
        taxIdNumber:
          type:
          - string
          - 'null'
          description: The customer's tax id number
          example: DR123467L
        noTaxIdReason:
          $ref: '#/components/schemas/ReasonForNoTaxId'
      additionalProperties: false
      description: Customer TaxResidency.
    AddressType:
      enum:
      - ResidentialAddress
      type: string
      example: ResidentialAddress
      description: Represents the type of the address
    UpdateIdentityDocumentRequest:
      required:
      - idExpiryDate
      - idNumber
      type: object
      properties:
        idNumber:
          minLength: 1
          type: string
          description: Identity document number.
          example: '684622049233'
        idExpiryDate:
          type: string
          description: Expiry date of the identity document.
          format: date
          example: '2029-02-13'
      additionalProperties: false
      description: The customer's identity document.
    RelatedPartyGetResponse:
      description: Response model for Related Party.
      type: object
      properties:
        id:
          type: string
          description: The related party's unique ID.
          format: uuid
        type:
          $ref: '#/components/schemas/RelatedPartyType'
        ownershipPercentage:
          type:
          - integer
          - 'null'
          description: The related party's ownership percentage, expressed as an integer.
          format: int32
          example: 100
    PepType:
      enum:
      - 'No'
      - Yes_Domestic
      - Yes_International
      type: string
      description: Indicates if the customer is a Politically Exposed Person.
    IdType:
      enum:
      - Passport
      - DrivingLicence
      - NationalId
      type: string
      description: The type of ID document.
    RcaType:
      enum:
      - 'No'
      - Yes_Domestic
      - Yes_International
      type: string
      description: Indicates if the customer is a Relative or Close Associate.
    AddressHistoryGetResponse:
      type: object
      properties:
        currentAddress:
          $ref: '#/components/schemas/AddressGetResponse'
        previousAddresses:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/PreviousAddressGetResponse'
          description: Array of the customer's previous addresses.
      additionalProperties: false
      description: Addresses associated with the customer.
    CountryCode:
      enum:
      - AFG
      - ALB
      - ATA
      - DZA
      - ASM
      - AND
      - AGO
      - ATG
      - AZE
      - ARG
      - AUS
      - AUT
      - BHS
      - BHR
      - BGD
      - ARM
      - BRB
      - BEL
      - BMU
      - BTN
      - BOL
      - BIH
      - BWA
      - BVT
      - BRA
      - BLZ
      - IOT
      - SLB
      - VGB
      - BRN
      - BGR
      - MMR
      - BDI
      - BLR
      - KHM
      - CMR
      - CAN
      - CPV
      - CYM
      - CAF
      - LKA
      - TCD
      - CHL
      - CHN
      - TWN
      - CXR
      - CCK
      - COL
      - COM
      - MYT
      - COG
      - COD
      - COK
      - CRI
      - HRV
      - CUB
      - CYP
      - CZE
      - BEN
      - DNK
      - DMA
      - DOM
      - ECU
      - SLV
      - GNQ
      - ETH
      - ERI
      - EST
      - FRO
      - FLK
      - SGS
      - FJI
      - FIN
      - ALA
      - FRA
      - GUF
      - PYF
      - ATF
      - DJI
      - GAB
      - GEO
      - GMB
      - PSE
      - DEU
      - GHA
      - GIB
      - KIR
      - GRC
      - GRL
      - GRD
      - GLP
      - GUM
      - GTM
      - GIN
      - GUY
      - HTI
      - HMD
      - VAT
      - HND
      - HKG
      - HUN
      - ISL
      - IND
      - IDN
      - IRN
      - IRQ
      - IRL
      - ISR
      - ITA
      - CIV
      - JAM
      - JPN
      - KAZ
      - JOR
      - KEN
      - PRK
      - KOR
      - KWT
      - KGZ
      - LAO
      - LBN
      - LSO
      - LVA
      - LBR
      - LBY
      - LIE
      - LTU
      - LUX
      - MAC
      - MDG
      - MWI
      - MYS
      - MDV
      - MLI
      - MLT
      - MTQ
      - MRT
      - MUS
      - MEX
      - MCO
      - MNG
      - MDA
      - MNE
      - MSR
      - MAR
      - MOZ
      - OMN
      - NAM
      - NRU
      - NPL
      - NLD
      - CUW
      - ABW
      - SXM
      - BES
      - NCL
      - VUT
      - NZL
      - NIC
      - NER
      - NGA
      - NIU
      - NFK
      - NOR
      - MNP
      - UMI
      - FSM
      - MHL
      - PLW
      - PAK
      - PAN
      - PNG
      - PRY
      - PER
      - PHL
      - PCN
      - POL
      - PRT
      - GNB
      - TLS
      - PRI
      - QAT
      - REU
      - ROU
      - RUS
      - RWA
      - BLM
      - SHN
      - KNA
      - AIA
      - LCA
      - MAF
      - SPM
      - VCT
      - SMR
      - STP
      - SAU
      - SEN
      - SRB
      - SYC
      - SLE
      - SGP
      - SVK
      - VNM
      - SVN
      - SOM
      - ZAF
      - ZWE
      - ESP
      - SSD
      - SDN
      - ESH
      - SUR
      - SJM
      - SWZ
      - SWE
      - CHE
      - SYR
      - TJK
      - THA
      - TGO
      - TKL
      - TON
      - TTO
      - ARE
      - TUN
      - TUR
      - TKM
      - TCA
      - TUV
      - UGA
      - UKR
      - MKD
      - EGY
      - GBR
      - GGY
      - JEY
      - IMN
      - TZA
      - USA
      - VIR
      - BFA
      - URY
      - UZB
      - VEN
      - WLF
      - WSM
      - YEM
      - ZMB
      type: string
      example: GBR
      description: 3-letter country codes as defined in ISO 3166-1