openapi: 3.2.0
info:
  title: Client Relations API
  description: Operations for Clients
  version: '1'
servers:
- url: https://sandbox-api.integrated.finance/v1/{instanceId}
  description: Sandbox
  variables: {}
- url: https://api.integrated.finance/v1/{instanceId}
  description: Production
  variables: {}
tags:
- name: Client Relations
paths:
  /clients/{clientId}/relations:
    get:
      tags:
      - Client Relations
      summary: List Client Relations
      operationId: client-relations.list
      parameters:
      - name: metadata.page.number
        in: query
        description: 0-indexed page number
        schema:
          minimum: 0
          type: integer
          format: int32
          default: 0
      - name: metadata.page.size
        in: query
        description: page size
        schema:
          maximum: 100
          minimum: 1
          type: integer
          format: int32
          default: 20
      - name: metadata.sort
        in: query
        description: default direction is ascending
        schema:
          type: string
        example: data.clientRelation.fullName,desc
      - name: data.clientRelation.identity.type
        in: query
        schema:
          $ref: '#/components/schemas/LegalEntityType'
      - name: data.clientRelation.relation
        in: query
        schema:
          $ref: '#/components/schemas/ClientRelatedLegalEntityRelation'
      - name: clientId
        in: path
        description: ID of the client in UUID format
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Client relation list returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientRelationListResponse'
              example:
                workflow: '{}'
                data:
                  clientRelations:
                  - id: 81dd82d1-7ef0-491c-b7b8-56b1ba6e7659
                    clientId: e4b3c646-53d6-48e0-8560-1a510923af62
                    relation: director
                    identity:
                      type: individual
                      country: GB
                      identifications:
                      - type: passport
                        identificationNumber: '12345678'
                        issuingCountry: GB
                        issueDate: null
                        expirationDate: null
                      givenName: John
                      familyName: Doe
                      birthDate: '2000-01-01'
                    profile:
                      identityType: individual
                      phone: '+441234567890'
                      email: test@integrated.finance
                      residentialAddress:
                        country: GB
                        region: England
                        city: London
                        street: Baker Street
                        postalCode: XYZ ABC
                        houseNumber: 221B
                    percentageOfOwnership: '55'
                    fullName: John Doe
                connect: '{}'
                metadata:
                  page:
                    size: 20
                    number: 0
                    totalElements: 1
                    totalPages: 1
        '500':
          description: Unknown system error
          content:
            application/json:
              examples:
                error-unknown:
                  description: error-unknown
                  value:
                    timestamp: '2023-02-12T13:06:35.0286835'
                    message: An unexpected error has occurred. Please contact the support team.
    post:
      tags:
      - Client Relations
      summary: Create a Client Relation
      operationId: client-relations.create
      parameters:
      - name: clientId
        in: path
        description: ID of the client in UUID format
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClientRelationCreateRequest'
            examples:
              direct-individual:
                description: direct-individual
                value:
                  workflow:
                    code: direct
                  data:
                    clientRelation:
                      relation: director
                      identity:
                        type: individual
                        givenName: John
                        familyName: Doe
                        country: GB
                        birthDate: '2000-01-01'
                      profile:
                        identityType: individual
                        phone: '+441234567890'
                        email: test@integrated.finance
                        residentialAddress:
                          country: GB
                          region: England
                          city: London
                          street: Baker Street
                          postalCode: XYZ ABC
                          houseNumber: 221B
                      percentageOfOwnership: '55'
                  connect: {}
                  metadata: {}
      responses:
        '201':
          description: Client relation created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientRelationCreateResponse'
              examples:
                direct-individual:
                  description: direct-individual
                  value:
                    workflow:
                      code: direct
                    data:
                      clientRelation:
                        id: d740cb17-fde3-4a8f-942f-d82ddd8f7dda
                        clientId: e4b3c646-53d6-48e0-8560-1a510923af62
                        relation: director
                        identity:
                          type: individual
                          country: GB
                          identifications: null
                          givenName: John
                          familyName: Doe
                          birthDate: '2000-01-01'
                        profile:
                          identityType: individual
                          phone: '+441234567890'
                          email: test@integrated.finance
                          residentialAddress:
                            country: GB
                            region: England
                            city: London
                            street: Baker Street
                            postalCode: XYZ ABC
                            houseNumber: 221B
                        percentageOfOwnership: '55'
                        fullName: John Doe
                    connect: '{}'
                    metadata: '{}'
  /clients/{clientId}/relations/{id}:
    get:
      tags:
      - Client Relations
      summary: Get a Client Relation
      operationId: client-relations.get
      parameters:
      - name: clientId
        in: path
        description: ID of the client in UUID format
        required: true
        schema:
          type: string
          format: uuid
      - name: id
        in: path
        description: ID of the client relation in UUID format
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Client relation resource returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientRelationGetResponse'
              example:
                workflow: '{}'
                data:
                  clientRelation:
                    id: 81dd82d1-7ef0-491c-b7b8-56b1ba6e7659
                    clientId: e4b3c646-53d6-48e0-8560-1a510923af62
                    relation: director
                    identity:
                      type: individual
                      country: GB
                      identifications:
                      - type: passport
                        identificationNumber: '12345678'
                        issuingCountry: GB
                        issueDate: null
                        expirationDate: null
                      givenName: John
                      familyName: Doe
                      birthDate: '2000-01-01'
                    profile:
                      identityType: individual
                      phone: '+441234567890'
                      email: test@integrated.finance
                      residentialAddress:
                        country: GB
                        region: England
                        city: London
                        street: Baker Street
                        postalCode: XYZ ABC
                        houseNumber: 221B
                    percentageOfOwnership: '55'
                    fullName: John Doe
                connect: '{}'
                metadata: '{}'
        '500':
          description: Unknown system error
          content:
            application/json:
              examples:
                error-unknown:
                  description: error-unknown
                  value:
                    timestamp: '2023-02-12T13:06:35.0286835'
                    message: An unexpected error has occurred. Please contact the support team.
    delete:
      tags:
      - Client Relations
      summary: Delete a Client Relation
      operationId: client-relations.delete
      parameters:
      - name: clientId
        in: path
        description: ID of the client in UUID format
        required: true
        schema:
          type: string
          format: uuid
      - name: id
        in: path
        description: ID of the client relation in UUID format
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '202':
          description: Client relation deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientRelationDeleteResponse'
              example:
                workflow: '{}'
                data:
                  clientRelation:
                    id: 81dd82d1-7ef0-491c-b7b8-56b1ba6e7659
                    clientId: e4b3c646-53d6-48e0-8560-1a510923af62
                    relation: director
                    identity:
                      type: individual
                      country: GB
                      identifications:
                      - type: passport
                        identificationNumber: '12345678'
                        issuingCountry: GB
                        issueDate: null
                        expirationDate: null
                      givenName: John
                      familyName: Doe
                      birthDate: '2000-01-01'
                    profile:
                      identityType: individual
                      phone: '+441234567890'
                      email: test@integrated.finance
                      residentialAddress:
                        country: GB
                        region: England
                        city: London
                        street: Baker Street
                        postalCode: XYZ ABC
                        houseNumber: 221B
                    percentageOfOwnership: '55'
                    fullName: John Doe
                connect: '{}'
                metadata: '{}'
    patch:
      tags:
      - Client Relations
      summary: Update a Client Relation
      operationId: client-relations.update
      parameters:
      - name: clientId
        in: path
        description: ID of the client in UUID format
        required: true
        schema:
          type: string
          format: uuid
      - name: id
        in: path
        description: ID of the client relation in UUID format
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClientRelationUpdateRequest'
            examples:
              direct-individual:
                description: direct-individual
                value:
                  workflow:
                    code: direct
                  data:
                    clientRelation:
                      identity:
                        type: individual
                        birthDate: '1950-01-01'
                  connect: '{}'
                  metadata: '{}'
      responses:
        '202':
          description: Client relation updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientRelationUpdateResponse'
              examples:
                direct-individual:
                  description: direct-individual
                  value: '{    "workflow": {        "code": "direct"    },    "data": {        "clientRelation": {            "id": "d740cb17-fde3-4a8f-942f-d82ddd8f7dda",            "clientId": "e4b3c646-53d6-48e0-8560-1a510923af62",            "relation": "director",            "identity": {                "type": "individual",                "country": "GB",                "identifications": null,                "givenName": "John",                "familyName": "Doe",                "birthDate": "1950-01-01"            },            "profile": {                "identityType": "individual"                "phone": "+441234567890",                "email": "test@integrated.finance"            },            "percentageOfOwnership": "55",            "fullName": "John Doe"        }    },    "connect": "{}",    "metadata": "{}"}'
components:
  schemas:
    ClientRelationUpdateDataContainer:
      required:
      - clientRelation
      type: object
      properties:
        clientRelation:
          type: object
          additionalProperties:
            type: object
            description: client relation data model
          description: client relation data model
    ClientRelationCreateWorkflow:
      type: string
      description: unique workflow code
      enum:
      - direct
    ClientRelationUpdateResponse:
      required:
      - connect
      - data
      - metadata
      - workflow
      type: object
      properties:
        workflow:
          $ref: '#/components/schemas/ClientRelationUpdateWorkflowContainer'
        data:
          $ref: '#/components/schemas/ClientRelationUpdateDataContainer'
        connect:
          $ref: '#/components/schemas/ClientRelationUpdateConnectContainer'
        metadata:
          $ref: '#/components/schemas/ClientRelationUpdateMetadataContainer'
    ClientRelationGetDataContainer:
      required:
      - clientRelation
      type: object
      properties:
        clientRelation:
          $ref: '#/components/schemas/ClientRelation'
    ClientRelationListDataContainer:
      type: object
      properties:
        clientRelation:
          $ref: '#/components/schemas/ClientRelationResourceListQueryInput'
        clientRelations:
          type: array
          description: collection of client relations
          readOnly: true
          items:
            $ref: '#/components/schemas/ClientRelation'
    ClientRelationCreateRequest:
      required:
      - connect
      - data
      - metadata
      - workflow
      type: object
      properties:
        workflow:
          $ref: '#/components/schemas/ClientRelationCreateWorkflowContainer'
        data:
          $ref: '#/components/schemas/ClientRelationCreateDataContainer'
        connect:
          $ref: '#/components/schemas/ClientRelationCreateConnectContainer'
        metadata:
          $ref: '#/components/schemas/ClientRelationCreateMetadataContainer'
    ClientRelationGetMetadataContainer:
      type: object
    ClientRelationDeleteResponse:
      required:
      - connect
      - data
      - metadata
      - workflow
      type: object
      properties:
        workflow:
          $ref: '#/components/schemas/ClientRelationDeleteWorkflowContainer'
        data:
          $ref: '#/components/schemas/ClientRelationDeleteDataContainer'
        connect:
          $ref: '#/components/schemas/ClientRelationDeleteConnectContainer'
        metadata:
          $ref: '#/components/schemas/ClientRelationDeleteMetadataContainer'
    LegalEntityIdentityIndividual:
      required:
      - familyName
      - givenName
      type: object
      allOf:
      - $ref: '#/components/schemas/LegalEntityIdentity'
      - type: object
        properties:
          type:
            $ref: '#/components/schemas/LegalEntityType'
          country:
            maxLength: 2
            minLength: 2
            pattern: ^[A-Z]{2}$
            type: string
          identifications:
            type: array
            items:
              $ref: '#/components/schemas/LegalEntityIdentification'
          givenName:
            type: string
          familyName:
            type: string
          birthDate:
            type: string
            format: date
    ClientRelatedLegalEntityRelation:
      type: string
      description: relation of legal entity with client
      enum:
      - director
      - shareholder
      - director-and-shareholder
      - authorized-person
    ClientRelationGetResponse:
      required:
      - connect
      - data
      - metadata
      - workflow
      type: object
      properties:
        workflow:
          $ref: '#/components/schemas/ClientRelationGetWorkflowContainer'
        data:
          $ref: '#/components/schemas/ClientRelationGetDataContainer'
        connect:
          $ref: '#/components/schemas/ClientRelationGetConnectContainer'
        metadata:
          $ref: '#/components/schemas/ClientRelationGetMetadataContainer'
    ClientRelationUpdateWorkflowContainer:
      required:
      - code
      type: object
      properties:
        code:
          $ref: '#/components/schemas/ClientRelationUpdateWorkflow'
    ClientRelationCreateDataContainer:
      type: object
      properties:
        clientRelation:
          $ref: '#/components/schemas/ClientRelation'
        clientRelations:
          type: array
          description: client relation data models, optional
          items:
            $ref: '#/components/schemas/ClientRelation'
    ClientRelationDeleteDataContainer:
      required:
      - clientRelation
      type: object
      properties:
        clientRelation:
          $ref: '#/components/schemas/ClientRelation'
    ClientRelation:
      required:
      - clientId
      - id
      - identity
      - relation
      type: object
      properties:
        attributes:
          $ref: '#/components/schemas/AttributeMap'
        id:
          type: string
          description: client relation id
          format: uuid
          readOnly: true
        clientId:
          type: string
          description: id of client
          format: uuid
          readOnly: true
        relation:
          $ref: '#/components/schemas/ClientRelatedLegalEntityRelation'
        identity:
          type: object
          description: client relation identity object
          oneOf:
          - $ref: '#/components/schemas/LegalEntityIdentityCorporate'
          - $ref: '#/components/schemas/LegalEntityIdentityIndividual'
        percentageOfOwnership:
          type: number
          description: percentage of ownership
        profile:
          type: object
          description: client relation profile object
          oneOf:
          - $ref: '#/components/schemas/ClientProfileCorporate'
          - $ref: '#/components/schemas/ClientProfileIndividual'
      description: client relation data model
    ClientRelationGetConnectContainer:
      type: object
    ClientRelationCreateMetadataContainer:
      type: object
    ClientRelationGetWorkflowContainer:
      type: object
    LegalEntityIdentityCorporate:
      required:
      - legalName
      type: object
      allOf:
      - $ref: '#/components/schemas/LegalEntityIdentity'
      - type: object
        properties:
          type:
            $ref: '#/components/schemas/LegalEntityType'
          country:
            maxLength: 2
            minLength: 2
            pattern: ^[A-Z]{2}$
            type: string
          identifications:
            type: array
            items:
              $ref: '#/components/schemas/LegalEntityIdentification'
          legalName:
            type: string
          incorporationDate:
            type: string
            format: date
          corporationType:
            $ref: '#/components/schemas/CorporationType'
    ClientProfileIndividual:
      type: object
      allOf:
      - $ref: '#/components/schemas/ClientProfile'
      - type: object
        properties:
          identityType:
            $ref: '#/components/schemas/LegalEntityType'
          phone:
            type: string
            description: client contact phone number
          email:
            type: string
            description: client contact email
          residentialAddress:
            $ref: '#/components/schemas/Address'
    AttributeMap:
      type: object
    ClientRelationCreateResponse:
      required:
      - connect
      - data
      - metadata
      - workflow
      type: object
      properties:
        workflow:
          $ref: '#/components/schemas/ClientRelationCreateWorkflowContainer'
        data:
          $ref: '#/components/schemas/ClientRelationCreateDataContainer'
        connect:
          $ref: '#/components/schemas/ClientRelationCreateConnectContainer'
        metadata:
          $ref: '#/components/schemas/ClientRelationCreateMetadataContainer'
    ClientRelationDeleteMetadataContainer:
      type: object
    ClientProfileCorporate:
      type: object
      allOf:
      - $ref: '#/components/schemas/ClientProfile'
      - type: object
        properties:
          identityType:
            $ref: '#/components/schemas/LegalEntityType'
          phone:
            type: string
            description: client contact phone number
          email:
            type: string
            description: client contact email
          registrationAddress:
            $ref: '#/components/schemas/Address'
    Address:
      required:
      - city
      - country
      - street
      type: object
      properties:
        country:
          maxLength: 2
          minLength: 2
          pattern: ^[A-Z]{2}$
          type: string
        region:
          type: string
        postalCode:
          type: string
        city:
          type: string
        street:
          type: string
        houseNumber:
          type: string
        refinement:
          type: string
      description: residential address object for individual clients
    ClientRelationDeleteConnectContainer:
      type: object
    ClientRelationListResponse:
      required:
      - connect
      - data
      - metadata
      - workflow
      type: object
      properties:
        workflow:
          $ref: '#/components/schemas/ClientRelationListWorkflowContainer'
        data:
          $ref: '#/components/schemas/ClientRelationListDataContainer'
        connect:
          $ref: '#/components/schemas/ClientRelationListConnectContainer'
        metadata:
          $ref: '#/components/schemas/ClientRelationListMetadataContainer'
    ClientRelationListMetadataContainer:
      required:
      - page
      type: object
      properties:
        page:
          $ref: '#/components/schemas/PageMetadata'
    ClientRelationCreateConnectContainer:
      type: object
    ClientRelationUpdateConnectContainer:
      type: object
    ClientRelationUpdateRequest:
      required:
      - connect
      - data
      - metadata
      - workflow
      type: object
      properties:
        workflow:
          $ref: '#/components/schemas/ClientRelationUpdateWorkflowContainer'
        data:
          $ref: '#/components/schemas/ClientRelationUpdateDataContainer'
        connect:
          $ref: '#/components/schemas/ClientRelationUpdateConnectContainer'
        metadata:
          $ref: '#/components/schemas/ClientRelationUpdateMetadataContainer'
    CorporationType:
      type: string
      enum:
      - ltd
      - plc
      - llp
      - lp
      - gp
      - st
      - other
    LegalEntityType:
      type: string
      enum:
      - corporate
      - individual
    ClientRelationListConnectContainer:
      type: object
    ClientRelationListWorkflowContainer:
      type: object
    ClientRelationCreateWorkflowContainer:
      required:
      - code
      type: object
      properties:
        code:
          $ref: '#/components/schemas/ClientRelationCreateWorkflow'
    ClientRelationUpdateMetadataContainer:
      type: object
    PageMetadata:
      required:
      - number
      - size
      - totalElements
      - totalPages
      type: object
      properties:
        size:
          minimum: 0
          type: integer
          description: number of elements in this page
          format: int32
        number:
          minimum: 0
          type: integer
          description: index of page starting from 0
          format: int32
        totalElements:
          minimum: 0
          type: integer
          description: total number of elements in all of the pages
          format: int64
          readOnly: true
        totalPages:
          minimum: 0
          type: integer
          description: number of total pages
          format: int32
          readOnly: true
    LegalEntityIdentity:
      required:
      - type
      type: object
      properties:
        type:
          type: string
      discriminator:
        propertyName: type
        mapping:
          corporate: '#/components/schemas/LegalEntityIdentityCorporate'
          individual: '#/components/schemas/LegalEntityIdentityIndividual'
    LegalEntityIdentification:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/LegalEntityIdentificationType'
        identificationNumber:
          type: string
        issuingCountry:
          maxLength: 2
          minLength: 2
          pattern: ^[A-Z]{2}$
          type: string
        issueDate:
          type: string
          format: date
        expirationDate:
          type: string
          format: date
    ClientRelationDeleteWorkflowContainer:
      type: object
    ClientRelationResourceListQueryInput:
      type: object
      properties:
        relation:
          $ref: '#/components/schemas/ClientRelatedLegalEntityRelation'
        identityType:
          $ref: '#/components/schemas/LegalEntityType'
      description: filter options of client relations
      writeOnly: true
    ClientRelationUpdateWorkflow:
      type: string
      description: unique workflow code
      enum:
      - direct
    ClientProfile:
      required:
      - identityType
      type: object
      properties:
        identityType:
          type: string
      discriminator:
        propertyName: identityType
        mapping:
          corporate: '#/components/schemas/ClientProfileCorporate'
          individual: '#/components/schemas/ClientProfileIndividual'
    LegalEntityIdentificationType:
      type: string
      enum:
      - registration-number
      - passport
      - identity-card
      - driving-licence
      - foreign-identity-card
      - tax-number
x-provenance:
  method: searched
  source: https://developer.integrated.finance/reference
  harvested: '2026-10-14'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://developer.integrated.finance/reference/client-relationscreate.md
  - https://developer.integrated.finance/reference/client-relationsdelete.md
  - https://developer.integrated.finance/reference/client-relationsget.md
  - https://developer.integrated.finance/reference/client-relationslist.md
  - https://developer.integrated.finance/reference/client-relationsupdate.md
  - https://developer.integrated.finance/reference/clientscreate-1.md
  - https://developer.integrated.finance/reference/clientsget.md
  - https://developer.integrated.finance/reference/clientslist.md
  - https://developer.integrated.finance/reference/clientsupdate-1.md
  merge:
    pages: 9
    deduped: 91
    conflicts_kept_first: 0