Fin
Fin Customers API

Customer management and document upload operations
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.1.0
info:
  title: Fin.com Authentication Customers API
  version: 1.0.0
  description: A simple API specificationFo
servers:
- url: https://sandbox.api.fin.com
  description: Sandbox server
- url: https://api.fin.com
  description: Production server
tags:
- name: Customers
  description: Customer management and document upload operations
paths:
  /v2/customers:
    get:
      summary: List Customers V2
      description: Retrieve a list of customers filtered by type
      tags:
      - Customers
      security:
      - bearerAuth: []
      parameters:
      - name: type
        in: query
        description: Filter customers by type
        required: true
        schema:
          type: string
          enum:
          - INDIVIDUAL
          - BUSINESS
      - $ref: '#/components/parameters/PerPageParam'
      - $ref: '#/components/parameters/CurrentPageParam'
      responses:
        '200':
          description: List of customers retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      pagination:
                        type: object
                        properties:
                          current_page:
                            type: integer
                            example: 1
                          per_page:
                            type: integer
                            example: 40
                          total_page:
                            type: integer
                            example: 1
                          total:
                            type: integer
                            example: 4
                      customers:
                        type: array
                        items:
                          oneOf:
                          - type: object
                            title: Individual Customer
                            properties:
                              customer_id:
                                type: string
                                format: uuid
                                example: 56c41b8e-e650-4f55-94f6-26a888a9b64d
                              type:
                                type: string
                                enum:
                                - INDIVIDUAL
                              first_name:
                                type: string
                                example: John
                              last_name:
                                type: string
                                example: Doe
                              email:
                                type: string
                                format: email
                                example: john.doe@example.com
                              phone:
                                type: string
                                example: '+14155551234'
                              country_of_residence:
                                type: string
                                example: USA
                              customer_status:
                                type: string
                                example: INCOMPLETE
                              tos_policies_url:
                                type: string
                                format: uri
                                example: https://orchestration.fin.com/orchestration-customer-tos?customer_id=56c41b8e-e650-4f55-94f6-26a888a9b64d&tos_policies_value=e9414388-fbdf-4407-b5c2-bc39eae3645b
                              created_at:
                                type: string
                                format: date-time
                                example: '2026-04-01T12:03:03Z'
                              updated_at:
                                type: string
                                format: date-time
                                example: '2026-04-01T12:03:03Z'
                          - type: object
                            title: Business Customer
                            properties:
                              customer_id:
                                type: string
                                format: uuid
                                example: ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06
                              type:
                                type: string
                                enum:
                                - BUSINESS
                              business_name:
                                type: string
                                example: Fin.com
                              email:
                                type: string
                                format: email
                                example: m@tech.com
                              phone:
                                type: string
                                example: '+8801529876543'
                              country_of_incorporation:
                                type: string
                                example: BGD
                              customer_status:
                                type: string
                                example: IN_COMPLIANCE
                              tos_policies_url:
                                type: string
                                format: uri
                                example: https://orchestration.fin.com/orchestration-customer-tos?customer_id=ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06&tos_policies_value=6955e70b-f9f3-4076-b1ce-5c897085dd24
                              created_at:
                                type: string
                                format: date-time
                                example: '2026-04-13T11:38:57Z'
                              updated_at:
                                type: string
                                format: date-time
                                example: '2026-04-13T11:40:51Z'
              examples:
                OK:
                  summary: OK
                  value:
                    data:
                      pagination:
                        current_page: 1
                        per_page: 40
                        total_page: 1
                        total: 2
                      customers:
                      - customer_id: ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06
                        type: BUSINESS
                        business_name: Fin.com
                        email: m@tech.com
                        phone: '+8801529876543'
                        country_of_incorporation: BGD
                        customer_status: IN_COMPLIANCE
                        tos_policies_url: https://orchestration.fin.com/orchestration-customer-tos?customer_id=ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06&tos_policies_value=6955e70b-f9f3-4076-b1ce-5c897085dd24
                        created_at: '2026-04-13T11:38:57Z'
                        updated_at: '2026-04-13T11:40:51Z'
                      - customer_id: 56c41b8e-e650-4f55-94f6-26a888a9b64d
                        type: INDIVIDUAL
                        first_name: John
                        last_name: Doe
                        email: john.doe@example.com
                        phone: '+14155551234'
                        country_of_residence: USA
                        customer_status: INCOMPLETE
                        tos_policies_url: https://orchestration.fin.com/orchestration-customer-tos?customer_id=56c41b8e-e650-4f55-94f6-26a888a9b64d&tos_policies_value=e9414388-fbdf-4407-b5c2-bc39eae3645b
                        created_at: '2026-04-01T12:03:03Z'
                        updated_at: '2026-04-01T12:03:03Z'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/customers:
    get:
      summary: List Customers
      description: Retrieve a list of customers filtered by type
      x-mint:
        content: "<Warning>\n  This endpoint was deprecated on May 20, 2026. Use [List Customers V2](https://developer.fin.com/api-reference/customers/list-customers-v2) instead.\n</Warning>\n"
      tags:
      - Customers
      security:
      - bearerAuth: []
      parameters:
      - name: type
        in: query
        description: Filter customers by type
        required: true
        schema:
          type: string
          enum:
          - INDIVIDUAL
          - BUSINESS
      - $ref: '#/components/parameters/PerPageParam'
      - $ref: '#/components/parameters/CurrentPageParam'
      responses:
        '200':
          description: List of customers retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      pagination:
                        type: object
                        properties:
                          current_page:
                            type: integer
                            example: 1
                          per_page:
                            type: integer
                            example: 10
                          total_page:
                            type: integer
                            example: 1
                          total:
                            type: integer
                            example: 2
                      customers:
                        type: array
                        items:
                          oneOf:
                          - type: object
                            properties:
                              customer_id:
                                type: string
                                format: uuid
                                example: 56c41b8e-e650-4f55-94f6-26a888a9b64d
                              type:
                                type: string
                                enum:
                                - INDIVIDUAL
                              first_name:
                                type: string
                                example: John
                              last_name:
                                type: string
                                example: Doe
                              email:
                                type: string
                                format: email
                                example: john.doe@example.com
                              phone:
                                type: string
                                example: '+14724480512'
                              country_of_residence:
                                type: string
                                example: USA
                              customer_status:
                                type: string
                                example: INCOMPLETE
                              tos_policies_url:
                                type: string
                                format: uri
                              created_at:
                                type: string
                                format: date-time
                              updated_at:
                                type: string
                                format: date-time
                          - type: object
                            properties:
                              customer_id:
                                type: string
                                format: uuid
                                example: 94e6b847-4e19-49e3-b3ab-ffa95872eda9
                              type:
                                type: string
                                enum:
                                - BUSINESS
                              business_name:
                                type: string
                                example: Acme Corp Ltd
                              email:
                                type: string
                                format: email
                                example: contact@acmecorp.com
                              phone:
                                type: string
                                example: '+14155552671'
                              country_of_incorporation:
                                type: string
                                example: USA
                              customer_status:
                                type: string
                                example: INCOMPLETE
                              tos_policies_url:
                                type: string
                                format: uri
                              created_at:
                                type: string
                                format: date-time
                              updated_at:
                                type: string
                                format: date-time
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v2/customers/{customer_id}:
    get:
      summary: Get Customer Details V2
      description: Retrieve detailed information for a specific customer
      x-mint:
        content: "<Note>\n  Use this endpoint to fetch business customer details. For individual customer details, use [Get Customer Details](https://developer.fin.com/api-reference/customers/get-customer-details).\n</Note>\n"
      tags:
      - Customers
      security:
      - bearerAuth: []
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        example: ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06
      responses:
        '200':
          description: Customer details retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    oneOf:
                    - $ref: '#/components/schemas/IndividualCustomerDetailV2'
                    - $ref: '#/components/schemas/BusinessCustomerDetailV2'
              examples:
                Business:
                  summary: Business customer
                  value:
                    data:
                      customer_id: 671536f8-ddc5-4b1e-bd6f-27d0ed07a27c
                      type: BUSINESS
                      business_name: Fin.com
                      email: contact@fin.com
                      phone: '+14155552671'
                      country_of_incorporation: USA
                      verification_type: STANDARD
                      customer_status: ACTION_REQUIRED
                      tos_policies_url: https://orchestration.fin.com/orchestration-customer-tos?customer_id=671536f8-ddc5-4b1e-bd6f-27d0ed07a27c&tos_policies_value=4e0e505a-36f0-4c9e-8eb1-3916410f227c
                      associated_parties:
                      - id: 2e719a54-cdef-43f9-a5ac-f6ef679ea1dc
                        type: INDIVIDUAL
                        ownership_percent: 60
                        email: jane.smith@acmecorp.com
                        verification:
                          status: REJECTED
                          reason:
                            for_customer: null
                            for_developer: null
                          updated_at: '2026-05-04T12:36:42Z'
                      - id: 4ef045ea-c7a7-46dc-84a0-9a3d83186971
                        type: INDIVIDUAL
                        ownership_percent: 40
                        email: robert.chen@acmecorp.com
                        verification:
                          status: APPROVED
                          reason:
                            for_customer: null
                            for_developer: null
                          updated_at: '2026-05-04T12:29:47Z'
                      created_at: '2026-05-04T12:11:27Z'
                      updated_at: '2026-05-04T12:34:03Z'
                      last_status_updated_at: '2026-05-04T12:32:34.47927Z'
                      rejection_reason:
                        applicant:
                          moderation_comment: ''
                          reject_labels:
                          - LOW_QUALITY
                          - UNFILLED_ID
                          - DOCUMENT_TEMPLATE
                          - NOT_DOCUMENT
                        documents:
                        - uri: /ZuyUaH3a_testdoc1.png
                          category: SUPPORTING_DOCUMENTS
                          moderation_comment: "This document is not accepted.\n - The document should be of good quality."
                          reject_labels:
                          - LOW_QUALITY
                        - uri: /ZuyUaH3a_testdoc1.png
                          category: OWNERSHIP_DOCUMENTS
                          moderation_comment: "This document is not accepted.\n - The document is not authentic"
                          reject_labels:
                          - UNFILLED_ID
                        - uri: /ZuyUaH3a_testdoc1.png
                          category: OWNERSHIP_DOCUMENTS
                          moderation_comment: "This document is not accepted.\n - The uploaded file appears to be a document template."
                          reject_labels:
                          - DOCUMENT_TEMPLATE
                        - uri: /ZuyUaH3a_testdoc1.png
                          category: SUPPORTING_DOCUMENTS
                          moderation_comment: "This document is not accepted.\n - The file is not a document"
                          reject_labels:
                          - NOT_DOCUMENT
                        associated_parties:
                        - id: 2e719a54-cdef-43f9-a5ac-f6ef679ea1dc
                          applicant:
                            moderation_comment: ''
                            reject_labels:
                            - EXPIRATION_DATE
                          documents:
                          - uri: /OUkUie0z_approved_passport_sumsub.jpg
                            category: PROOF_OF_IDENTITY
                            moderation_comment: Your identity document must be valid for at least 2 month(s) from the date of submission.
                            reject_labels:
                            - EXPIRATION_DATE
                      request_for_information:
                      - scope: ASSOCIATED_PARTY
                        associated_party_id: 2e719a54-cdef-43f9-a5ac-f6ef679ea1dc
                        section: identifying_documents
                        categories:
                        - document_type: PASSPORT
                          fields:
                          - field_name: type
                            data_type: ENUM
                            status: INVALID
                            options: []
                          - field_name: expiry_date
                            data_type: DATE
                            status: INVALID
                            options: []
                          - field_name: issue_date
                            data_type: DATE
                            status: INVALID
                            options: []
                          - field_name: files
                            data_type: URI
                            status: INVALID
                            reason: User identity document is not valid for at least 2 month(s) from the date of submission.
                            options: []
                      - scope: CUSTOMER
                        section: formation_documents
                        categories:
                        - document_type: EVIDENCE_OF_DIRECTORS_AND_CONTROLLERS
                          fields:
                          - field_name: type
                            data_type: ENUM
                            status: INVALID
                            options: []
                          - field_name: files
                            data_type: URI
                            status: INVALID
                            reason: Unacceptable document.
                            options: []
                      - scope: CUSTOMER
                        section: supporting_documents
                        categories:
                        - document_type: PROOF_OF_SOURCE_OF_FUNDS
                          fields:
                          - field_name: type
                            data_type: ENUM
                            status: INVALID
                            options: []
                          - field_name: files
                            data_type: URI
                            status: INVALID
                            reason: Unacceptable document.
                            options: []
                      - scope: CUSTOMER
                        section: ownership_documents
                        categories:
                        - document_type: PROOF_OF_SIGNATORY_AUTHORITY
                          fields:
                          - field_name: type
                            data_type: ENUM
                            status: INVALID
                            options: []
                          - field_name: files
                            data_type: URI
                            status: INVALID
                            reason: Document appears to be corrupted
                            options: []
                Individual:
                  summary: Individual customer
                  value:
                    data:
                      customer_id: 1f45e58d-0420-4ad8-a790-413169bfab28
                      type: INDIVIDUAL
                      first_name: John
                      last_name: Doe
                      email: atkeyafahmida290@gmail.com
                      phone: '+8801748386269'
                      country_of_residence: BGD
                      verification_type: STANDARD
                      customer_status: ACTION_REQUIRED
                      tos_policies_url: https://orchestration.fin.com/orchestration-customer-tos?customer_id=1f45e58d-0420-4ad8-a790-413169bfab28&tos_policies_value=ffefb0cd-4f0a-4585-ad1c-f4ea76ba41b8
                      created_at: '2026-05-04T12:40:03Z'
                      updated_at: '2026-05-04T12:47:50Z'
                      last_status_updated_at: '2026-05-04T12:44:42.707598Z'
                      rejection_reason:
                        applicant:
                          moderation_comment: ''
                          reject_labels:
                          - EXPIRATION_DATE
                          - PROBLEMATIC_APPLICANT_DATA
                        documents:
                        - uri: /SuElNZpi_approved_passport_sumsub.jpg
                          category: PROOF_OF_IDENTITY
                          moderation_comment: Your identity document has expired and can't be used for verification. Please upload a different identity document.
                          reject_labels:
                          - EXPIRATION_DATE
                      request_for_information:
                      - scope: CUSTOMER
                        section: proof_of_identity
                        categories:
                        - document_type: PASSPORT
                          fields:
                          - field_name: type
                            data_type: ENUM
                            status: INVALID
                            options: []
                          - field_name: expiry_date
                            data_type: DATE
                            status: INVALID
                            options: []
                          - field_name: issue_date
                            data_type: DATE
                            status: INVALID
                            options: []
                          - field_name: files
                            data_type: URI
                            status: INVALID
                            reason: Expired Identity document. A new document has been requested.
                            options: []
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/customers/{customer_id}:
    get:
      summary: Get Customer Details
      description: Retrieve detailed information for a specific customer
      x-mint:
        content: "<Note>\n  Use this endpoint to fetch individual customer details. For business customer details, use [Get Customer Details V2](https://developer.fin.com/api-reference/customers/get-customer-details-v2).\n</Note>\n"
      tags:
      - Customers
      security:
      - bearerAuth: []
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        example: 55bd6b4e-c20a-4cc8-9535-91d5557a67d9
      responses:
        '200':
          description: Customer details retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    oneOf:
                    - $ref: '#/components/schemas/IndividualCustomerDetail'
                    - $ref: '#/components/schemas/BusinessCustomerDetail'
              examples:
                Individual Customer:
                  summary: Individual Customer
                  value:
                    data:
                      customer_id: 56c41b8e-e650-4f55-94f6-26a888a9b64d
                      type: INDIVIDUAL
                      first_name: John
                      last_name: Doe
                      email: john.doe@fin.com
                      phone: '+14724480512'
                      country_of_residence: USA
                      verification_type: STANDARD
                      customer_status: ON_HOLD
                      tos_policies_url: https://orchestration.fin.com/orchestration-customer-tos?customer_id=56c41b8e-e650-4f55-94f6-26a888a9b64d&tos_policies_value=e9414388-fbdf-4407-b5c2-bc39eae3645b
                      created_at: '2026-04-15T11:49:27Z'
                      updated_at: '2026-04-15T11:52:48Z'
                      last_status_updated_at: '2026-04-15T11:52:48Z'
                      capabilities:
                        on_ramp:
                        - currency: USD
                          status: false
                          methods:
                          - ACH
                          - FEDWIRE
                          reason:
                            for_customer: null
                            for_developer: null
                        off_ramp:
                        - currency: USD
                          status: false
                          methods:
                          - ACH
                          - FEDWIRE
                          - ACH_SAME_DAY
                          reason:
                            for_customer: null
                            for_developer: Customer is under review
                        - currency: EUR
                          status: false
                          methods:
                          - BANK
                          reason:
                            for_customer: null
                            for_developer: Customer is under review
                        - currency: BDT
                          status: false
                          methods:
                          - BANK
                          - E_WALLET
                          reason:
                            for_customer: null
                            for_developer: Customer is under review
                        - currency: AUD
                          status: false
                          methods:
                          - BANK
                          reason:
                            for_customer: null
                            for_developer: Customer is under review
                        - currency: INR
                          status: false
                          methods:
                          - BANK
                          reason:
                            for_customer: null
                            for_developer: Customer is under review
                        - currency: JPY
                          status: false
                          methods:
                          - BANK
                          reason:
                            for_customer: null
                            for_developer: Customer is under review
                        - currency: NPR
                          status: false
                          methods:
                          - BANK
                          reason:
                            for_customer: null
                            for_developer: Customer is under review
                        - currency: CAD
                          status: false
                          methods:
                          - BANK
                          reason:
                            for_customer: null
                            for_developer: Customer is under review
                        - currency: PKR
                          status: false
                          methods:
                          - BANK
                          reason:
                            for_customer: null
                            for_developer: Customer is under review
                        - currency: PHP
                          status: false
                          methods:
                          - BANK
                          reason:
                            for_customer: null
                            for_developer: Customer is under review
                        - currency: SGD
                          status: false
                          methods:
                          - BANK
                          reason:
                            for_customer: null
                            for_developer: Customer is under review
                        - currency: GBP
                          status: false
                          methods:
                          - BANK
                          reason:
                            for_customer: null
                            for_developer: Customer is under review
                      rejection_reason: null
                      request_for_information: []
                Business Customer:
                  summary: Business Customer
                  value:
                    data:
                      customer_id: 94e6b847-4e19-49e3-b3ab-ffa95872eda9
                      type: BUSINESS
                      business_name: Fin.com
                      email: contact@fin.com
                      phone: '+6591234567'
                      country_of_incorporation: SGP
                      verification_type: STANDARD
                      customer_status: APPROVED
                      tos_policies_url: https://orchestration.fin.com/orchestration-customer-tos?customer_id=94e6b847-4e19-49e3-b3ab-ffa95872eda9&tos_policies_value=6955e70b-f9f3-4076-b1ce-5c897085dd24
                      associated_parties:
                      - id: 42daffd3-09a0-4d48-8e73-2680a953d0e1
                        type: INDIVIDUAL
                        ownership_percent: 10
                        email: john.doe@fin.com
                        verification:
                          status: APPROVED
                          reason:
                            for_customer: null
                            for_developer: null
                          updated_at: '2026-04-15T11:29:08Z'
                      created_at: '2026-04-15T11:26:12Z'
                      updated_at: '2026-04-15T11:31:18Z'
                      last_status_updated_at: '2026-04-15T11:29:09Z'
                      capabilities:
                        on_ramp:
                        - currency: USD
                          status: false
                          methods:
                          - ACH
                          - FEDWIRE
                          reason:
                            for_customer: null
                            for_developer: null
                        off_ramp:
                        - currency: USD
                          status: false
                          methods:
                     

# --- truncated at 32 KB (194 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fin/refs/heads/main/openapi/fin-customers-api-openapi.yml
Fin Customers API

Documentation

Specifications

Other Resources

OpenAPI Specification
