Unstoppable Finance (Iron) Customer API

openapi: 3.1.0
info:
  description: The Stablecoin Payment Network
  title: Iron API - Sandbox Addresses Customer API
  version: 1.0-16988
servers:
- url: https://api.sandbox.iron.xyz/api
tags:
- description: Operations on Customers
  name: Customer
paths:
  /authentication-codes/entity/{id}:
    get:
      description: 'Get the pending authentication code for an entity by ID

        e.g. ID of Autoramp or FiatAddress (entity in AuhorizationRequired state)

        if no pending code is found, retry flow will have to be triggered

        '
      operationId: getPendingAuthenticationCode
      parameters:
      - deprecated: false
        description: Optional sub-partner UUID, if provided, the authentication code will be filtered for the sub-partner
        explode: true
        in: header
        name: X-SUB-PARTNER-ID
        required: false
        schema:
          type: string
      - deprecated: false
        description: The ID of the entity to get the pending authentication code for
        explode: true
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      - $ref: '#/components/parameters/XApiVersion'
      responses:
        '200':
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/AuthenticationCode'
          description: GET Authentication Code Succeeded
        '401':
          content:
            application/json; charset=utf-8:
              schema:
                type: string
          description: GET Authentication Code Failed (Unauthorized)
        '404':
          content:
            application/json; charset=utf-8:
              schema:
                type: string
          description: GET Authentication Code Failed (Not Found)
        '500':
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: GET Authentication Code Failed (Internal Error)
      security:
      - ApiKeyAuth: []
      summary: Get the pending authentication code for an entity
      tags:
      - Customer
  /authentication-codes/{id}:
    put:
      description: 'Submit the code for a given authentication

        '
      operationId: submitAuthenticationCode
      parameters:
      - deprecated: false
        description: Optional sub-partner UUID, if provided, the authentication code will be submitted under scope of the sub-partner
        explode: true
        in: header
        name: X-SUB-PARTNER-ID
        required: false
        schema:
          type: string
      - deprecated: false
        description: The ID of the authentication code to submit
        explode: true
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      - $ref: '#/components/parameters/XApiVersion'
      requestBody:
        content:
          application/json; charset=utf-8:
            schema:
              $ref: '#/components/schemas/SubmitAuthenticationCodeParams'
        description: The authentication code to submit
        required: true
      responses:
        '200':
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/AuthenticationCode'
          description: PUT Authentication Code Succeeded
        '401':
          content:
            application/json; charset=utf-8:
              schema:
                type: string
          description: PUT Authentication Code Failed (Unauthorized)
        '404':
          content:
            application/json; charset=utf-8:
              schema:
                type: string
          description: PUT Authentication Code Failed (Not Found)
        '500':
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: PUT Authentication Code Failed (Internal Error)
      security:
      - ApiKeyAuth: []
      summary: Submit an authentication code
      tags:
      - Customer
  /customers:
    get:
      description: 'Get all customers for a particular partner. The partner ID does not need to be provided as it

        is provided by the API Key.


        An optional `search_term` can be provided to filter by name, id, email, or external id.

        '
      operationId: getAllCustomers
      parameters:
      - deprecated: false
        description: Optional sub-partner UUID, if provided, the customers will be filtered for the sub-partner
        explode: true
        in: header
        name: X-SUB-PARTNER-ID
        required: false
        schema:
          type: string
      - deprecated: false
        description: 'Paging: the cursor field from previous page'
        explode: false
        in: query
        name: cursor
        required: false
        schema:
          default: null
          format: uuid
          type: string
      - deprecated: false
        description: 'Paging: the cursor field for backward pagination'
        explode: false
        in: query
        name: prev_cursor
        required: false
        schema:
          default: null
          format: uuid
          type: string
      - deprecated: false
        description: 'Paging: the requested page size (max 100)'
        explode: false
        in: query
        name: page_size
        required: false
        schema:
          default: 10
          format: uint32
          maximum: 100.0
          type: integer
      - deprecated: false
        description: A search term to filter the customers
        explode: false
        in: query
        name: search_term
        required: false
        schema:
          default: null
          maxLength: 256
          type: string
      - deprecated: false
        description: Filter by customer status (comma-separated or repeated values)
        explode: true
        in: query
        name: status
        required: false
        schema:
          default: null
          items:
            $ref: '#/components/schemas/CustomerStatus'
          type: array
      - deprecated: false
        description: Filter by the customer's most-recent identification status
        explode: true
        in: query
        name: identification_status
        required: false
        schema:
          default: null
          items:
            $ref: '#/components/schemas/IdentificationStatus'
          type: array
      - deprecated: false
        description: Filter by customer type (Person or Business)
        explode: true
        in: query
        name: customer_type
        required: false
        schema:
          default: null
          items:
            $ref: '#/components/schemas/CustomerType'
          type: array
      - deprecated: false
        description: 'When true, only customers with at least one transaction; when

          false, only customers without any. Omit to disable the filter.'
        explode: false
        in: query
        name: has_transactions
        required: false
        schema:
          default: null
          type: boolean
      - deprecated: false
        description: 'Sort order: "asc" for oldest first, "desc" for newest first (default)'
        explode: false
        in: query
        name: sort_order
        required: false
        schema:
          allOf:
          - $ref: '#/components/schemas/SortOrder'
          - default: null
          default: null
      - $ref: '#/components/parameters/XApiVersion'
      responses:
        '200':
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/PagedList_Customer'
          description: GET ALL Customer Succeeded
        '401':
          content:
            application/json; charset=utf-8:
              schema:
                type: string
          description: GET ALL Customer Failed (Unauthorized)
        '500':
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: GET ALL Customer Failed (Internal Error)
      security:
      - ApiKeyAuth: []
      summary: Get all Customers
      tags:
      - Customer
    post:
      description: 'Create a new **business** or **legal person** customer.

        '
      operationId: createCustomer
      parameters:
      - deprecated: false
        description: a UUID ensuring an Customer operation is only processed once
        explode: true
        in: header
        name: IDEMPOTENCY-KEY
        required: true
        schema:
          type: string
      - deprecated: false
        description: Optional sub-partner UUID, if provided, the customer will be created for the sub-partner
        explode: true
        in: header
        name: X-SUB-PARTNER-ID
        required: false
        schema:
          type: string
      - $ref: '#/components/parameters/XApiVersion'
      requestBody:
        content:
          application/json; charset=utf-8:
            schema:
              $ref: '#/components/schemas/CreateCustomerParams'
        description: Parameters required to create a new Customer
        required: true
      responses:
        '201':
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Customer'
          description: POST Customer Succeeded
        '400':
          content:
            application/json; charset=utf-8:
              schema:
                type: string
          description: POST Customer Failed (Bad Request)
        '401':
          content:
            application/json; charset=utf-8:
              schema:
                type: string
          description: POST Customer Failed (Unauthorized)
        '500':
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: POST Customer Failed (Internal Error)
      security:
      - ApiKeyAuth: []
      summary: Create a new customer
      tags:
      - Customer
  /customers/{external_id}/external:
    get:
      description: 'Retrieve a specific customer by external ID

        '
      operationId: getCustomerByExternalId
      parameters:
      - deprecated: false
        description: Optional sub-partner UUID, if provided, the customer will be filtered for the sub-partner
        explode: true
        in: header
        name: X-SUB-PARTNER-ID
        required: false
        schema:
          type: string
      - deprecated: false
        description: the external ID of the Customer to GET
        explode: true
        in: path
        name: external_id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/XApiVersion'
      responses:
        '200':
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Customer'
          description: GET Customer Succeeded
        '401':
          content:
            application/json; charset=utf-8:
              schema:
                type: string
          description: GET Customer Failed (Unauthorized)
        '404':
          content:
            application/json; charset=utf-8:
              schema:
                type: string
          description: GET Customer Failed (Resource Not Found)
        '500':
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: GET Customer Failed (Internal Error)
      security:
      - ApiKeyAuth: []
      summary: Get a customer by external ID
      tags:
      - Customer
  /customers/{id}:
    get:
      description: 'Retrieve a specific customer by ID

        '
      operationId: getCustomerById
      parameters:
      - deprecated: false
        description: Optional sub-partner UUID, if provided, the customer will be filtered for the sub-partner
        explode: true
        in: header
        name: X-SUB-PARTNER-ID
        required: false
        schema:
          type: string
      - deprecated: false
        description: the ID of the Customer to GET
        explode: true
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      - $ref: '#/components/parameters/XApiVersion'
      responses:
        '200':
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Customer'
          description: GET Customer Succeeded
        '401':
          content:
            application/json; charset=utf-8:
              schema:
                type: string
          description: GET Customer Failed (Unauthorized)
        '404':
          content:
            application/json; charset=utf-8:
              schema:
                type: string
          description: GET Customer Failed (Resource Not Found)
        '500':
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: GET Customer Failed (Internal Error)
      security:
      - ApiKeyAuth: []
      summary: Get a customer by ID
      tags:
      - Customer
    put:
      description: 'Update a customer by ID

        '
      operationId: updateCustomer
      parameters:
      - deprecated: false
        description: Optional sub-partner UUID, if provided, the wallet address will be registered for the sub-partner
        explode: true
        in: header
        name: X-SUB-PARTNER-ID
        required: false
        schema:
          type: string
      - deprecated: false
        description: the ID of the Customer to update
        explode: true
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      - $ref: '#/components/parameters/XApiVersion'
      requestBody:
        content:
          application/json; charset=utf-8:
            schema:
              $ref: '#/components/schemas/UpdateCustomerParams'
        description: The customer data to be used for the update
        required: true
      responses:
        '204':
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Customer'
          description: PUT Customer Succeeded
        '400':
          content:
            application/json; charset=utf-8:
              schema:
                type: string
          description: PUT Customer Failed (Bad Request)
        '401':
          content:
            application/json; charset=utf-8:
              schema:
                type: string
          description: PUT Customer Failed (Unauthorized)
        '500':
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: PUT Customer Failed (Internal Error)
      security:
      - ApiKeyAuth: []
      summary: Update a customer
      tags:
      - Customer
  /customers/{id}/abilities:
    get:
      description: 'Retrieve the abilities/capabilities for a specific customer by ID

        '
      operationId: getCustomerAbilities
      parameters:
      - deprecated: false
        description: Optional sub-partner UUID, if provided, the customer will be filtered for the sub-partner
        explode: true
        in: header
        name: X-SUB-PARTNER-ID
        required: false
        schema:
          type: string
      - deprecated: false
        description: the ID of the Customer to GET abilities for
        explode: true
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      - $ref: '#/components/parameters/XApiVersion'
      responses:
        '200':
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/CustomerAbilities'
          description: GET Customer Abilities Succeeded
        '401':
          content:
            application/json; charset=utf-8:
              schema:
                type: string
          description: GET Customer Abilities Failed (Unauthorized)
        '404':
          content:
            application/json; charset=utf-8:
              schema:
                type: string
          description: GET Customer Abilities Failed (Not Found)
        '500':
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: GET Customer Abilities Failed (Internal Error)
      security:
      - ApiKeyAuth: []
      summary: Get customer abilities
      tags:
      - Customer
  /customers/{id}/archive:
    put:
      description: 'Archive a customer and all of their identifications. This is terminal and

        cannot be undone: the customer is completely and permanently blocked from

        using any services.

        '
      operationId: archiveCustomer
      parameters:
      - deprecated: false
        description: the ID of the Customer to archive
        explode: true
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      - $ref: '#/components/parameters/XApiVersion'
      responses:
        '200':
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Customer'
          description: Customer Archived
        '400':
          content:
            application/json; charset=utf-8:
              schema:
                type: string
          description: Archive Customer Failed (Bad Request)
        '401':
          content:
            application/json; charset=utf-8:
              schema:
                type: string
          description: Archive Customer Failed (Unauthorized)
        '500':
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Archive Customer Failed (Internal Error)
      security:
      - ApiKeyAuth: []
      summary: Archive a customer
      tags:
      - Customer
  /customers/{id}/identifications:
    get:
      description: 'Retrieve all identifications for this customer

        '
      operationId: getAllCustomerIdentifications
      parameters:
      - deprecated: false
        description: Optional sub-partner UUID, if provided, the identifications will be filtered for the sub-partner
        explode: true
        in: header
        name: X-SUB-PARTNER-ID
        required: false
        schema:
          type: string
      - deprecated: false
        description: the ID of the Customer to get Identifications for
        explode: true
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      - deprecated: false
        description: 'Paging: the cursor field from previous page'
        explode: false
        in: query
        name: cursor
        required: false
        schema:
          default: null
          format: uuid
          type: string
      - deprecated: false
        description: 'Paging: the requested page size (max 100)'
        explode: false
        in: query
        name: page_size
        required: false
        schema:
          default: 10
          format: uint32
          type: integer
      - $ref: '#/components/parameters/XApiVersion'
      responses:
        '200':
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/PagedList_Identification'
          description: GET ALL Identification Succeeded
        '401':
          content:
            application/json; charset=utf-8:
              schema:
                type: string
          description: GET ALL Identification Failed (Unauthorized)
        '404':
          content:
            application/json; charset=utf-8:
              schema:
                type: string
          description: GET ALL Identification Failed (Resource Not Found)
        '500':
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: GET ALL Identification Failed (Internal Error)
      security:
      - ApiKeyAuth: []
      summary: Get all customer Identifications
      tags:
      - Customer
  /customers/{id}/identifications/v2:
    post:
      description: 'This will create a new identification for the customer, dependent on the customer type a KYC or KYB will be created for the customer to complete.

        we support three types of identification:

        - Link: where a link is provided to the customer for access to the identification process.

        - Token: where a token is provided in the request from which verification data can be extracted and where the token is generated by the third party provider

        - Person: where the identification details of the person for which the identification process is being created are provided in the request'
      operationId: createCustomerIdentificationV2
      parameters:
      - deprecated: false
        description: a UUID ensuring an Customer Identification operation is only processed once
        explode: true
        in: header
        name: IDEMPOTENCY-KEY
        required: true
        schema:
          type: string
      - deprecated: false
        description: Optional sub-partner UUID, if provided, the identification will be created under scope of the sub-partner
        explode: true
        in: header
        name: X-SUB-PARTNER-ID
        required: false
        schema:
          type: string
      - deprecated: false
        description: the ID of the Customer to create an Identification for
        explode: true
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      - $ref: '#/components/parameters/XApiVersion'
      requestBody:
        content:
          application/json; charset=utf-8:
            schema:
              $ref: '#/components/schemas/IdentificationCreateParamsV2'
        description: The Identification data to be used for the identification
        required: true
      responses:
        '201':
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Identification'
          description: POST Customer Identification Succeeded
        '400':
          content:
            application/json; charset=utf-8:
              schema:
                type: string
          description: POST Customer Identification Failed (Invalid Request)
        '401':
          content:
            application/json; charset=utf-8:
              schema:
                type: string
          description: POST Customer Identification Failed (Unauthorized)
        '403':
          content:
            application/json; charset=utf-8:
              schema:
                type: string
          description: POST Customer Identification Failed (Forbidden)
        '404':
          content:
            application/json; charset=utf-8:
              schema:
                type: string
          description: POST Customer Identification Failed (Resource Not Found)
        '409':
          content:
            application/json; charset=utf-8:
              schema:
                type: string
          description: POST Customer Idenfication Failed (Has Pending Identification)
        '429':
          content:
            application/json; charset=utf-8:
              schema:
                type: string
          description: POST Customer Identification Failed (Creation Rate Limit Exceeded)
        '500':
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: POST Customer Identification Failed (Internal Error)
      security:
      - ApiKeyAuth: []
      summary: Create Customer Identification V2
      tags:
      - Customer
  /customers/{id}/microdeposits:
    get:
      description: 'Retrieve all microdeposits for a specific customer by ID

        '
      operationId: getCustomerMicrodeposits
      parameters:
      - deprecated: false
        description: Optional sub-partner UUID, if provided, the customer will be filtered for the sub-partner
        explode: true
        in: header
        name: X-SUB-PARTNER-ID
        required: false
        schema:
          type: string
      - deprecated: false
        description: the ID of the Customer to GET microdeposits for
        explode: true
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      - $ref: '#/components/parameters/XApiVersion'
      responses:
        '200':
          content:
            application/json; charset=utf-8:
              schema:
                items:
                  $ref: '#/components/schemas/Microdeposit'
                type: array
          description: GET Microdeposits Succeeded
        '401':
          content:
            application/json; charset=utf-8:
              schema:
                type: string
          description: GET Microdeposits Failed (Unauthorized)
        '404':
          content:
            application/json; charset=utf-8:
              schema:
                type: string
          description: GET Microdeposits Failed (Resource Not Found)
        '500':
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: GET Microdeposits Failed (Internal Error)
      security:
      - ApiKeyAuth: []
      summary: Get customer microdeposits
      tags:
      - Customer
  /customers/{id}/required-signings:
    get:
      description: 'Get all required signings for a customer

        '
      operationId: getCustomerRequiredSignings
      parameters:
      - deprecated: false
        description: Optional sub-partner UUID, if provided, the required signings will be filtered for the sub-partner
        explode: true
        in: header
        name: X-SUB-PARTNER-ID
        required: false
        schema:
          type: string
      - deprecated: false
        description: the ID of the Customer to get required signings for
        explode: true
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      - $ref: '#/components/parameters/XApiVersion'
      responses:
        '200':
          content:
            application/json; charset=utf-8:
              schema:
                items:
                  $ref: '#/components/schemas/TermsAndConditionsLink'
                type: array
          description: GET Required Signings Succeeded
        '401':
          content:
            application/json; charset=utf-8:
              schema:
                type: string
          description: GET Required Signings Failed (Unauthorized)
        '403':
          content:
            application/json; charset=utf-8:
              schema:
                type: string
          description: GET Required Signings Failed (Forbidden)
        '404':
          content:
            application/json; charset=utf-8:
              schema:
                type: string
          description: GET Required Signings Failed (Not Found)
        '409':
          content:
            application/json; charset=utf-8:
              schema:
                type: string
          description: GET Required Signings Failed (Conflict)
        '500':
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: GET Required Signings Failed (Internal Error)
      security:
      - ApiKeyAuth: []
      summary: Get customer required signings
      tags:
      - Customer
  /customers/{id}/requirements:
    get:
      description: 'Retrieve a requirements view of a customer:

        four buckets — `complete`, `pending`, `missing`, `issues` — plus a

        coarse `requirements_due` summary of categories that still need

        attention. Each requirement carries a stable typed `code` (switch on

        this) and, when available, a verbatim `description` from the upstream

        KYC provider''s moderation comment. **NOTE**: The `description` field is subject to change without notice.


        Computed on demand from the customer''s identifications and

        customer-level state; no separate ingestion step is needed.'
      operationId: getCustomerRequirements
      parameters:
      - deprecated: false
        description: Optional sub-partner UUID, if provided, the customer will be filtered for the sub-partner
        explode: true
        in: header
        name: X-SUB-PARTNER-ID
        required: false
        schema:
          type: string
      - deprecated: false
        description: the ID of the Customer to GET requirements for
        explode: true
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      - $ref: '#/components/parameters/XApiVersion'
      responses:
        '200':
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/CustomerRequirements'
          description: GET Customer Requirements Succeeded
        '401':
          content:
            application/json; charset=utf-8:
              schema:
                type: string
          description: GET Customer Requirements Failed (Unauthorized)
        '404':
          content:
            application/json; charset=utf-8:
              schema:
                type: string
          description: GET Customer Requirements Failed (Resource Not Found)
        '500':
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: GET Customer Requirements Failed (Internal Error)
      security:
      - ApiKeyAuth: []
      summary: Get customer requirements
      tags:
      - Customer
  /customers/{id}/signings:
    get:
      description: 'Retrieve all signings for a customer, representing the various legal agreements and consents gathered from the customer.

        See The KYC/Compliance section of our documentation for more info.

        '
      operationId: getSignings
      parameters:
      - deprecated: false
        description: Optional sub-partner UUID, if provided, the signings will be filtered for the sub-partner
        explode: true
        in: header
        name: X-SUB-PARTNER-ID
        required: false
        schema:
          type: string
      - deprecated: false
        description: the ID of the Customer to get Signings for
        explode: true
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      - deprecated: false
        description: 'Paging: the cursor field from previous page'
        explode: false
        in: query
        name: cursor
        required: false
        schema:
          default: null
          format: uuid
          type: string
      - deprecated: false
        description: 'Paging: the requested page size (max 100)'
        explode: false
        in: query
        name: page_size
        required: false
        schema:
          default: 10
          format: uint32
          type: integer
      - $ref: '#/components/parameters/XApiVersion'
      responses:
        '200':
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/PagedList_Signing'
          description: GET Signings Succeeded
        '401':
          content:
            application/json; charset=utf-8:
              schema:
                type: string
          description: GET Signings Failed (Unauthorized)
        '404':
          content:
            application/json; charset=utf-8:
              schema:
                type: string
          description: GET Signings Resource Not found
        '500':
          content:
            application

# --- truncated at 32 KB (110 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/unstoppable-finance/refs/heads/main/openapi/unstoppable-finance-customer-api-openapi.yml