Lorum Customers API

openapi: 3.1.0
info:
  title: Fuse Accounts Customers API
  description: 'Lorum (Fuse) clearing, settlement and treasury API: multi-currency accounts, payments, exchanges, transfers, customers/KYC, documents, batch payments and sandbox simulation. Harvested from the provider''s public ReadMe reference (per-operation OpenAPI definitions).'
  contact:
    name: Lorum
    url: https://docs.lorum.com
  license:
    name: Proprietary license
  version: 0.1.0
servers:
- url: https://api.fuse.me
  description: Production
- url: https://api-sandbox.fuse.me
  description: Sandbox
security:
- OAuth2: []
tags:
- name: Customers
paths:
  /v1/customers/businesses:
    post:
      tags:
      - Customers
      summary: Add business
      description: Add business
      operationId: add_business
      parameters:
      - name: Idempotency-Key
        in: header
        description: Idempotency key to allow safe retrying of the operation. The value should be a unique UUID for each distinct operation. See our understanding idempotency guide for full details.
        required: false
        schema:
          type:
          - string
          - 'null'
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddBusinessRequest'
        required: true
      responses:
        '201':
          description: Business has been created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddCustomerResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/customers/individuals:
    post:
      tags:
      - Customers
      summary: Add individual
      description: Add individual
      operationId: add_individual
      parameters:
      - name: Idempotency-Key
        in: header
        description: Idempotency key to allow safe retrying of the operation. The value should be a unique UUID for each distinct operation. See our understanding idempotency guide for full details.
        required: false
        schema:
          type:
          - string
          - 'null'
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddIndividualRequest'
        required: true
      responses:
        '201':
          description: Individual has been created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddCustomerResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/customers/businesses/{customer_id}/shareholders:
    post:
      tags:
      - Customers
      summary: Add a shareholder to a business
      description: Add a shareholder to a business
      operationId: add_shareholder
      parameters:
      - name: customer_id
        in: path
        description: Id of the customer
        required: true
        schema:
          type: string
          format: Uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddShareholderRequest'
        required: true
      responses:
        '201':
          description: Business has been created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddShareholderResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      deprecated: true
    get:
      tags:
      - Customers
      summary: List shareholders for a business
      description: List shareholders for a business
      operationId: list_shareholders
      parameters:
      - name: customer_id
        in: path
        description: Id of the customer
        required: true
        schema:
          type: string
          format: Uuid
      responses:
        '200':
          description: List of shareholders
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ShareholderSummary'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      deprecated: true
  /v1/customers/{customer_id}/archive:
    patch:
      tags:
      - Customers
      summary: Archive the customer so it is no longer available for use in the system.
      description: 'Archive the customer so it is no longer available for use in the system.

        customer linked to an open account can not be archived.'
      operationId: archive_customer
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Customer has been updated successfully
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/customers/{customer_id}:
    get:
      tags:
      - Customers
      summary: Get customer
      description: Get customer
      operationId: get_customer
      parameters:
      - name: customer_id
        in: path
        description: Id of the customer
        required: true
        schema:
          type: string
          format: Uuid
      responses:
        '200':
          description: Successfully retrieved contents of directory
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCustomerResponse'
    patch:
      tags:
      - Customers
      summary: Update customer
      description: Update customer
      operationId: update_customer
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCustomerRequest'
        required: true
      responses:
        '204':
          description: Customer has been updated successfully
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/customers/{customer_id}/onboarding/{currency}:
    get:
      tags:
      - Customers
      summary: Get Customer Onboarding Status for a specific currency
      description: Get Customer Onboarding Status for a specific currency
      operationId: get_customer_onboarding
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: currency
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/OnboardingCurrency'
        example: usd
      responses:
        '200':
          description: Successfully retrieved customer onboarding status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Onboarding'
    post:
      tags:
      - Customers
      summary: Onboard a customer for a specific currency
      description: Onboard a customer for a specific currency
      operationId: onboard_customer
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: currency
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/OnboardingCurrency'
        example: usd
      responses:
        '201':
          description: Customer successfully onboarded
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/customers/businesses/shareholders/{shareholder_id}:
    get:
      tags:
      - Customers
      summary: Get a shareholder
      description: Get a shareholder
      operationId: get_shareholder
      parameters:
      - name: shareholder_id
        in: path
        description: Id of the customer
        required: true
        schema:
          type: string
          format: Uuid
      responses:
        '200':
          description: Returns the shareholder
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetShareholderResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      deprecated: true
    patch:
      tags:
      - Customers
      summary: Update a shareholder
      description: Update a shareholder
      operationId: update_shareholder
      parameters:
      - name: shareholder_id
        in: path
        description: Id of the shareholder
        required: true
        schema:
          type: string
          format: Uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateShareholderRequest'
        required: true
      responses:
        '204':
          description: Shareholder has been updated successfully
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      deprecated: true
  /v1/customers/{customer_id}/documents:
    post:
      tags:
      - Customers
      summary: Submit a document
      description: Submit a document
      operationId: link_document
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinkDocumentRequest'
        required: true
      responses:
        '200':
          description: Document successfully linked to customer
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/customers:
    get:
      tags:
      - Customers
      summary: List customers
      description: List customers
      operationId: list_customers
      parameters:
      - name: reference
        in: query
        description: Filter customers by reference ID
        required: false
        schema:
          type: string
      - name: customer_type
        in: query
        description: Filter customers by their type
        required: false
        schema:
          $ref: '#/components/schemas/CustomerTypeFilter'
      - name: cursor
        in: query
        description: Base64 encoded pagination cursor for fetching subsequent pages
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: page_size
        in: query
        description: Number of customers to return per page
        required: false
        schema:
          type: integer
          format: int32
          minimum: 0
      responses:
        '200':
          description: Successfully retrieved list of customers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCustomersResponse'
  /v1/customers/{customer_id}/documents/{document_id}:
    delete:
      tags:
      - Customers
      summary: Unlink a document from a customer.
      description: 'Unlink a document from a customer.

        A document belonging to a USD onboarded customer cannot be unlinked from the customer.'
      operationId: unlink_document
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: document_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Document successfully unlinked from customer
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    CustomerRelationshipType:
      oneOf:
      - type: string
        description: 'The customer is a direct customer of the organisation.

          The customer is contracted with the organisation.'
        enum:
        - direct
      - type: object
        description: 'The customer is a sub-customer of the organisation.

          The customer is contracted with a direct customer of the organisation.'
        required:
        - indirect
        properties:
          indirect:
            type: object
            description: 'The customer is a sub-customer of the organisation.

              The customer is contracted with a direct customer of the organisation.'
            required:
            - parent_customer_id
            properties:
              parent_customer_id:
                type: string
                format: uuid
      description: Represents the relationship between a customer and the organisation.
    UpdateCustomerExtraAPI:
      oneOf:
      - type: object
        title: Individual
        required:
        - individual
        properties:
          individual:
            type: object
            properties:
              currency_extra:
                type:
                - array
                - 'null'
                items:
                  $ref: '#/components/schemas/IndividualCurrencyExtra'
              date_of_birth:
                type:
                - string
                - 'null'
                format: date
              first_name:
                type:
                - string
                - 'null'
                format: string
                maxLength: 45
              gender:
                oneOf:
                - type: 'null'
                - $ref: '#/components/schemas/Gender'
              identification:
                oneOf:
                - type: 'null'
                - $ref: '#/components/schemas/IndividualIdentification'
              last_name:
                type:
                - string
                - 'null'
                format: string
                maxLength: 45
              middle_name:
                type:
                - string
                - 'null'
                format: string
                maxLength: 45
              nationality:
                type:
                - string
                - 'null'
                format: string
                maxLength: 2
                minLength: 2
      - type: object
        title: Business
        required:
        - business
        properties:
          business:
            type: object
            properties:
              business_name:
                type:
                - string
                - 'null'
                format: string
                maxLength: 140
              country_of_issuance:
                type:
                - string
                - 'null'
                format: string
              currency_extra:
                type:
                - array
                - 'null'
                items:
                  $ref: '#/components/schemas/BusinessCurrencyExtra'
              issuance_authority:
                type:
                - string
                - 'null'
                format: string
                maxLength: 140
              linked_documents:
                type:
                - array
                - 'null'
                items:
                  type: string
                  format: uuid
                deprecated: true
              registration_date:
                type:
                - string
                - 'null'
                format: date
              registration_number:
                type:
                - string
                - 'null'
                format: string
                maxLength: 140
              regulatory_licenses:
                type:
                - array
                - 'null'
                items:
                  $ref: '#/components/schemas/RegulatoryLicenseType'
    AddShareholderRequest:
      allOf:
      - $ref: '#/components/schemas/AddShareholder'
      - type: object
        required:
        - holding_percentage
        properties:
          holding_percentage:
            type: integer
            format: int32
            minimum: 0
          shareholder_of:
            type:
            - string
            - 'null'
            format: Uuid
      description: "Company 1\n  |--> Shareholder 1 (Business)\n  |    |--> Shareholder 3 (Individual)\n  |--> Shareholder 2 (Business)\n  |    |--> Shareholder 4 (Business)\n            |--> Shareholder 5 (Individual)\n\n"
    UpdateCustomerRequest:
      allOf:
      - oneOf:
        - type: 'null'
        - $ref: '#/components/schemas/UpdateCustomerExtraAPI'
      - type: object
        properties:
          address:
            oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/UpdateAddress'
          display_name:
            type:
            - string
            - 'null'
            format: string
            maxLength: 140
          reference:
            type:
            - string
            - 'null'
            format: string
            maxLength: 36
    Address:
      type: object
      required:
      - line_1
      - country_code
      properties:
        country_code:
          type: string
          format: string
          maxLength: 2
          minLength: 2
        line_1:
          type: string
          format: string
          maxLength: 50
        line_2:
          type:
          - string
          - 'null'
          format: string
          description: '***optional*** for `AED` payments but ***mandatory*** for `USD` payments'
          maxLength: 50
        line_3:
          type:
          - string
          - 'null'
          format: string
          maxLength: 50
        line_4:
          type:
          - string
          - 'null'
          format: string
          maxLength: 50
    WatchlistIdType:
      type: string
      enum:
      - passport
      - national_id
    Shareholder:
      oneOf:
      - type: object
        required:
        - shareholder
        properties:
          shareholder:
            type: object
            required:
            - first_name
            - last_name
            - dob
            - pob
            - id_type
            - id_number
            properties:
              dob:
                type: string
                format: date
              first_name:
                type: string
              id_number:
                type: string
              id_type:
                type: string
              last_name:
                type: string
              middle_name:
                type:
                - string
                - 'null'
              pob:
                type: string
      - type: object
        required:
        - business_shareholder
        properties:
          business_shareholder:
            type: object
            required:
            - name
            - registration_number
            properties:
              name:
                type: string
              registration_number:
                type: string
    IndividualIdentification:
      oneOf:
      - type: object
        title: Passport
        required:
        - number
        - expiry_date
        - country_of_issuance
        - type
        properties:
          country_of_issuance:
            type: string
            format: string
            description: 'Country of issuance (i.e: US, AE)'
            maxLength: 2
            minLength: 2
          expiry_date:
            type: string
            format: date
            description: Expiry date of the passport.
          number:
            type: string
            format: string
            description: Passport number.
            maxLength: 100
            minLength: 1
          type:
            type: string
            enum:
            - passport
      - type: object
        title: NationalId
        required:
        - number
        - expiry_date
        - country_of_issuance
        - type
        properties:
          country_of_issuance:
            type: string
            format: string
            description: 'Country of issuance. (i.e: US, AE)'
            maxLength: 2
            minLength: 2
          expiry_date:
            type: string
            format: date
            description: Expiry date of the ID.
          number:
            type: string
            format: string
            description: National ID number.
            maxLength: 100
            minLength: 1
          type:
            type: string
            enum:
            - national_id
      description: 'Individual Identification


        Identification document of an individual.'
    Customer:
      allOf:
      - $ref: '#/components/schemas/CustomerExtraAPI'
      - type: object
        required:
        - id
        - reference
        - display_name
        - address
        - documents
        - approval_status
        - relationship_type
        properties:
          address:
            $ref: '#/components/schemas/Address'
          approval_status:
            $ref: '#/components/schemas/ApprovalStatus'
          display_name:
            type: string
          documents:
            type: array
            items:
              $ref: '#/components/schemas/DocumentSummary'
          id:
            type: string
            format: uuid
          reference:
            type: string
            maxLength: 36
          rejection_reason:
            oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/RejectionReason'
          relationship_type:
            $ref: '#/components/schemas/CustomerRelationshipType'
    OnboardingCurrency:
      type: string
      enum:
      - usd
      - eur
      - gbp
      - aed
    Cursor_String:
      type: object
      required:
      - size
      properties:
        next:
          type:
          - string
          - 'null'
        size:
          type: integer
          minimum: 0
    OnboardingStatus:
      oneOf:
      - type: string
        enum:
        - pending
      - type: string
        enum:
        - completed
      - type: object
        required:
        - failed
        properties:
          failed:
            $ref: '#/components/schemas/OnboardingError'
    UpdateShareholderRequest:
      allOf:
      - oneOf:
        - type: 'null'
        - $ref: '#/components/schemas/UpdateShareholder'
      - type: object
        properties:
          holding_percentage:
            type:
            - integer
            - 'null'
            format: int32
            minimum: 0
          shareholder_of:
            type:
            - string
            - 'null'
            format: Uuid
    CustomerSummary:
      type: object
      required:
      - id
      - reference
      - customer_type
      - display_name
      - created_at
      - approval_status
      properties:
        approval_status:
          $ref: '#/components/schemas/ApprovalStatus'
        created_at:
          type: string
          format: date-time
        customer_type:
          $ref: '#/components/schemas/CustomerTypeFilter'
        display_name:
          type: string
        id:
          type: string
          format: uuid
        reference:
          type: string
          maxLength: 36
    CustomerExtraAPI:
      oneOf:
      - type: object
        title: Individual
        required:
        - individual
        properties:
          individual:
            type: object
            required:
            - first_name
            - last_name
            - date_of_birth
            - gender
            - nationality
            - currency_extra
            properties:
              currency_extra:
                type: array
                items:
                  $ref: '#/components/schemas/IndividualCurrencyExtra'
              date_of_birth:
                type: string
                format: date-time
              first_name:
                type: string
              gender:
                $ref: '#/components/schemas/Gender'
              identification:
                oneOf:
                - type: 'null'
                - $ref: '#/components/schemas/IndividualIdentification'
              last_name:
                type: string
              middle_name:
                type:
                - string
                - 'null'
              nationality:
                type: string
                format: string
                maxLength: 2
                minLength: 2
      - type: object
        title: Business
        required:
        - business
        properties:
          business:
            type: object
            required:
            - business_name
            - registration_number
            - country_of_issuance
            - regulatory_licenses
            - currency_extra
            properties:
              business_name:
                type: string
              country_of_issuance:
                type: string
                format: string
                maxLength: 2
                minLength: 2
              currency_extra:
                type: array
                items:
                  $ref: '#/components/schemas/BusinessCurrencyExtra'
              issuance_authority:
                type:
                - string
                - 'null'
              registration_date:
                type:
                - string
                - 'null'
                format: date
              registration_number:
                type: string
              regulatory_licenses:
                type: array
                items:
                  $ref: '#/components/schemas/RegulatoryLicenseType'
    GetShareholderResponse:
      allOf:
      - $ref: '#/components/schemas/Shareholder'
      - type: object
        required:
        - shareholder_type
        - holding_percent
        properties:
          holding_percent:
            type: integer
            format: int32
            minimum: 0
          shareholder_of:
            type:
            - string
            - 'null'
            format: Uuid
          shareholder_type:
            $ref: '#/components/schemas/ShareholderType'
    DocumentType:
      type: string
      description: Types of documents that can be uploaded for customers and transactions.
      enum:
      - passport
      - visa
      - national_id
      - trade_licence
      - commercial_licence
      - identity_verification_biometrics
      - incorporation_cert
      - incumbency_cert
      - memorandum_articles
      - bank_statement
      - photo
      - proof_of_address
      - regulatory_license
      - articles_of_association
      - source_of_funds
      - aml_cft_sanctions_ind_audit
      - aml_cft_sanctions_policy
      - compliance_officer_resume
      - financial_statements
      - share_certificate
      - corporate_resolution
      - wolfsberg_gcbddq
      - edd_concentration_form
      - other
    AedLicenseIssuer:
      type: string
     

# --- truncated at 32 KB (47 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lorum/refs/heads/main/openapi/lorum-customers-api-openapi.yml