Lorum Customers API

openapi: 3.2.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:
    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
    RejectionReason:
      type: string
      enum:
      - prohibited
      - sanction
      - pep
      - financial_crimes
      - other
    RegulatoryLicenseType:
      type: string
      enum:
      - banking
      - card_acquiring
      - card_issuer
      - crypto_asset
      - electronic_money
      - forex
      - payments
      - none
      - other
      - trading
    AddIndividualRequest:
      type: object
      required:
      - display_name
      - reference
      - address
      - first_name
      - last_name
      - date_of_birth
      - gender
      - nationality
      properties:
        address:
          $ref: '#/components/schemas/Address'
        currency_extra:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/IndividualCurrencyExtra'
        date_of_birth:
          type: string
          format: date
        display_name:
          type: string
          format: string
          maxLength: 140
        first_name:
          type: string
          format: string
          maxLength: 45
        gender:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/Gender'
        identification:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/IndividualIdentification'
            description: Identification document of the individual.
        last_name:
          type: string
          format: string
          maxLength: 45
        middle_name:
          type:
          - string
          - 'null'
          format: string
          maxLength: 45
        nationality:
          type: string
          format: string
          maxLength: 2
          minLength: 2
        reference:
          type: string
          format: string
          description: Reference set by the customer. Max 36 characters.
          maxLength: 36
        relationship_type:
          oneOf:
          - $ref: '#/components/schemas/CustomerRelationshipType'
            description: The relationship type of the customer to the organisation.
          default: direct
    DocumentSummary:
      type: object
      required:
      - id
      - document_type
      - reference
      properties:
        document_type:
          $ref: '#/components/schemas/DocumentType'
        id:
          type: string
          format: uuid
        reference:
          type: string
          format: string
          maxLength: 35
    ErrorResponse:
      type: object
      description: 'User-facing error type.


        This is the general error structure returned by all api routes.'
      required:
      - error
      - message
      - code
      properties:
        code:
          type: string
          description: Specific error code.
        error:
          type: string
          description: Soon to be deprecated.
        message:
          type: string
          description: Renaming of `error`. Human-readable description of the error.
    ListCustomersResponse:
      type: object
      required:
      - pages
      - customers
      properties:
        customers:
          type: array
          items:
            $ref: '#/components/schemas/CustomerSummary'
        pages:
          $ref: '#/components/schemas/Cursor_String'
    CustomerTypeFilter:
      type: string
      enum:
      - individual
      - business
    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'
    Currency:
      type: string
      enum:
      - AED
      - USD
      - JOD
      - EGP
      - SAR
      - GBP
      - EUR
      - HKD
      - CNH
      - SGD
    ErrorCode:
      type: string
      enum:
      - missing_document
      - missing_currency_data
      - no_shareholders
      - insufficient_majority_owership
      - shareholder_not_onboarded
      - business_registration_date_missing
      - invalid_business_registration_date
      - business_registration_number_missing
      - business_trade_license_expiry_missing
      - expired_trade_license
      - expired_identification_document
      - individual_missing_proof_of_address_document
      - business_missing_proof_of_address_document
      - invalid_documents
      - invalid_customer_name
      - invalid_shareholder_name
      - invalid_customer_address
    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.
    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"
    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
    LinkDocumentRequest:
      type: object
      required:
      - document_id
      properties:
        document_id:
          type: string
          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
    ApprovalStatus:
      type: string
      enum:
      - auto_approved
      - pending
      - approved
      - rejected
    OnboardingCurrency:
      type: string
      enum:
      - usd
      - eur
      - gbp
      - aed
    AddShareholderResponse:
      type: object
      required:
      - id
      properties:
        id:
          type: string
          format: Uuid
    IndividualCurrencyExtra:
      oneOf:
      - type: object
        title: Usd
        required:
        - id_number
        - country_of_issuance
        - country_of_birth
        - occupation_code
        - currency
        properties:
          country_of_birth:
            type: string
            format: string
            description: Country of birth. it should be ISO3166-1 Alpha2 country code
            maxLength: 2
            minLength: 2
          country_of_issuance:
            type: string
            format: string
            description: Country where id was issues. it should be ISO3166-1 Alpha2 country code
            maxLength: 2
            minLength: 2
          currency:
            type: string
            enum:
            - usd
          id_number:
            type: string
            format: string
            description: Valid person id number (Passport or national id).
            maxLength: 100
            minLength: 1
          ip_address:
            type: string
            format: string
            description: Optional IP address to use as a Proof of Address. Can be in IPv4 or IPv6 format.
            maxLength: 45
            minLength: 2
          occupation_code:
            type: string
            format: string
            description: 'US occupation code as defined by the Standard Occupational Classification (SOC) system.

              See https://reference.fuse.me/soc.html for supported list of codes.'
            maxLength: 6
            minLength: 6
      description: Represents the currency specific data for an individual.
    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'
    Cursor_String:
      type: object
      required:
      - size
      properties:
        next:
          type:
          - string
          - 'null'
        size:
          type: integer
          minimum: 0
    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
            

# --- 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