> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fintoc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create an onboarding

> Starts an onboarding process for the entity using the company information, legal representatives, transactional profile, and shareholders provided in the request. Further requests upload documents and submit the onboarding, whose country is taken from the entity.

**`v2`** · Base URL `https://api.fintoc.com/v2`


## OpenAPI

````yaml reference/fintoc-api-v2.json POST /entities/{entity_id}/onboardings
openapi: 3.1.0
info:
  title: fintoc-api-v2
  version: v2026-02-01
servers:
  - url: https://api.fintoc.com/v2
security: []
paths:
  /entities/{entity_id}/onboardings:
    post:
      tags:
        - Onboardings
      summary: Create an onboarding
      description: >-
        Starts an onboarding process for the entity using the company
        information, legal representatives, transactional profile, and
        shareholders provided in the request. Further requests upload documents
        and submit the onboarding, whose country is taken from the entity.
      operationId: entities-onboardings-create
      parameters:
        - name: entity_id
          in: path
          description: >-
            Unique identifier for the entity, such as
            `ent_8anBwgZktbZH6ydyHa6Tm0eM`.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                company_information:
                  type: object
                  description: Company information of the entity.
                  properties:
                    business_activity:
                      type: string
                      example: Servicios financieros
                      description: Primary business activity of the company.
                    business_address:
                      type: string
                      example: Av. Insurgentes 456, CDMX
                      description: Physical business address.
                    fiscal_address:
                      type: string
                      example: Av. Reforma 123, CDMX
                      description: Registered fiscal address.
                    incorporation_date:
                      type: string
                      format: date
                      example: '2020-01-15'
                      description: Incorporation date, as an ISO 8601 date.
                    phone:
                      type: string
                      example: '+521111111111'
                      description: Contact phone number in E.164 format.
                    settlement_account:
                      type: string
                      example: '000000000000000000'
                      description: >-
                        Settlement account as an 18-digit standardized Mexican
                        bank account number (CLABE).
                  required:
                    - incorporation_date
                    - business_activity
                    - fiscal_address
                    - business_address
                    - settlement_account
                    - phone
                legal_representatives:
                  type: array
                  description: >-
                    Legal representatives of the company. Must contain at least
                    one entry.
                  items:
                    $ref: '#/components/schemas/onboarding_legal_representative_input'
                transactional_profile:
                  type: object
                  description: Expected transactional profile of the entity.
                  properties:
                    monthly_amount_range:
                      type: string
                      enum:
                        - '1_500000'
                        - '500001_1000000'
                        - gt_1000000
                      example: '1_500000'
                      description: >-
                        Expected monthly transacted amount range, in MXN. Use
                        `1_500000` for 1 to 500,000 MXN, `500001_1000000` for
                        500,001 to 1,000,000 MXN, or `gt_1000000` for more than
                        1,000,000 MXN.
                    monthly_operations_range:
                      type: string
                      enum:
                        - '1_15000'
                        - '15001_50000'
                        - gte_50001
                      example: '1_15000'
                      description: >-
                        Expected monthly number of operations range. Use
                        `1_15000` for 1 to 15,000 operations, `15001_50000` for
                        15,001 to 50,000 operations, or `gte_50001` for 50,001
                        or more operations.
                    resource_origins:
                      type: array
                      items:
                        type: string
                        enum:
                          - trusts
                          - budget_allocations
                          - royalties
                          - asset_sales
                          - investments
                          - profits
                          - donations
                      example:
                        - trusts
                        - investments
                      description: >-
                        Declared origins of the entity's resources. One or more
                        of `trusts`, `budget_allocations`, `royalties`,
                        `asset_sales`, `investments`, `profits`, or `donations`.
                  required:
                    - resource_origins
                    - monthly_amount_range
                    - monthly_operations_range
                shareholders:
                  type: array
                  description: >-
                    Shareholder structure of the entity. Each level's
                    participation percentages must sum to at least 76 and at
                    most 100. Only `legal_entity` shareholders may declare
                    nested `children`.
                  items:
                    $ref: '#/components/schemas/onboarding_shareholder_input'
              required:
                - company_information
                - legal_representatives
                - transactional_profile
                - shareholders
            examples:
              create_onboarding:
                summary: Create an onboarding
                value:
                  company_information:
                    incorporation_date: '2020-01-15'
                    business_activity: Servicios financieros
                    fiscal_address: Av. Reforma 123, CDMX
                    business_address: Av. Insurgentes 456, CDMX
                    settlement_account: '000000000000000000'
                    phone: '+521111111111'
                  legal_representatives:
                    - first_name: Test Customer 1
                      last_name: Customer
                      email: rep@example.com
                      nationality: mx
                      identification_number: AAAA010101HDFAAA01
                      position: Director General
                  transactional_profile:
                    resource_origins:
                      - trusts
                      - investments
                    monthly_amount_range: '1_500000'
                    monthly_operations_range: '1_15000'
                  shareholders:
                    - type: natural_person
                      name: Test Customer 2
                      last_name: Customer
                      nationality: mx
                      percentage: 60
                      holder_id: AAAA010101AAA
                    - type: legal_entity
                      name: Acme SA
                      nationality: mx
                      percentage: 40
                      holder_id: AAA010101AAA
                      children:
                        - type: natural_person
                          name: Test Customer 3
                          last_name: Customer
                          nationality: mx
                          percentage: 80
                          holder_id: AAAA010101AAA
      responses:
        '201':
          description: >-
            The API starts the onboarding process from the provided data and
            returns the created onboarding.
          content:
            application/json:
              examples:
                onboarding_created:
                  value:
                    id: onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K
                    object: onboarding
                    entity_id: ent_8anBwgZktbZH6ydyHa6Tm0eM
                    status: in_progress
                    source: api
                    submitted_at: null
                    reviewed_at: null
                    submittable: false
                    data:
                      company_information:
                        incorporation_date: '2020-01-15T00:00:00.000Z'
                        business_activity: Servicios financieros
                        fiscal_address: Av. Reforma 123, CDMX
                        business_address: Av. Insurgentes 456, CDMX
                        settlement_account: '000000000000000000'
                        phone: '+521111111111'
                      transactional_profile:
                        resource_origins:
                          - trusts
                          - investments
                        monthly_amount_range: '1_500000'
                        monthly_operations_range: '1_15000'
                        declaration_accepted: true
                    legal_representatives:
                      - id: onblr_0ujsswThIGTUYm2K8FjOOfXtY1K
                        object: onboarding_legal_representative
                        first_name: Test Customer 1
                        last_name: Customer
                        email: rep@example.com
                        nationality: mx
                        identification_number: AAAA010101HDFAAA01
                        position: Director General
                        documents:
                          - slot_key: identification
                            status: missing
                          - slot_key: power_of_attorney
                            status: missing
                    shareholders:
                      - id: onbsh_0ujsswThIGTUYm2K8FjOOfXtY1K
                        object: onboarding_shareholder
                        type: natural_person
                        name: Test Customer 2
                        last_name: Customer
                        percentage: 60
                        holder_id: AAAA010101AAA
                        parent_id: null
                        document:
                          slot_key: identification
                          status: missing
                      - id: onbsh_8anBwgZktbZH6ydyHa6Tm0eM
                        object: onboarding_shareholder
                        type: legal_entity
                        name: Acme SA
                        percentage: 40
                        holder_id: AAA010101AAA
                        parent_id: null
                        document:
                          slot_key: articles_of_incorporation
                          status: missing
                      - id: onbsh_9bnCxhAlucAI7zezIb7Un1fN
                        object: onboarding_shareholder
                        type: natural_person
                        name: Test Customer 3
                        last_name: Customer
                        percentage: 80
                        holder_id: AAAA010101AAA
                        parent_id: onbsh_8anBwgZktbZH6ydyHa6Tm0eM
                        document:
                          slot_key: identification
                          status: missing
                    documents:
                      - slot_key: tax_registration_certificate
                        status: missing
                      - slot_key: settlement_bank_statement
                        status: missing
                      - slot_key: proof_of_address
                        status: missing
                      - slot_key: shareholder_structure
                        status: missing
                      - slot_key: articles_of_incorporation
                        status: missing
              schema:
                $ref: '#/components/schemas/onboarding'
        '400':
          description: >-
            The data failed validation: a required field is missing or invalid,
            or the shareholder structure is invalid (for example a level's
            participation percentages sum to more than 100).
          content:
            application/json:
              examples:
                invalid_shareholder_structure:
                  value:
                    error:
                      type: invalid_request_error
                      code: invalid_shareholder_structure
                      reason: shareholder_participation_exceeded
                      message: participation sum for this level exceeds 100
                      param: shareholders
                      doc_url: https://docs.fintoc.com/reference/errors
              schema:
                $ref: '#/components/schemas/error_object'
        '401':
          description: Invalid or missing API key.
          content:
            application/json:
              examples:
                invalid_api_key:
                  value:
                    error:
                      type: authentication_error
                      code: invalid_api_key
                      message: 'Invalid API Key: invalid-*oken'
              schema:
                $ref: '#/components/schemas/error_object'
        '404':
          description: The entity does not exist.
          content:
            application/json:
              examples:
                entity_not_found:
                  value:
                    error:
                      type: invalid_request_error
                      code: missing_resource
                      param: entity_id
                      message: 'No such entity: ent_8anBwgZktbZH6ydyHa6Tm0eM'
                      doc_url: https://docs.fintoc.com/reference/errors
              schema:
                $ref: '#/components/schemas/error_object'
        '409':
          description: >-
            An onboarding already exists for the entity. The response body
            includes the `active_onboarding_id` of the existing onboarding.
          content:
            application/json:
              examples:
                active_onboarding_exists:
                  value:
                    error:
                      type: conflicted_request_error
                      code: conflicted_request
                      message: An onboarding already exists for this entity
                      active_onboarding_id: onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K
              schema:
                $ref: '#/components/schemas/error_object'
        '422':
          description: The entity's country is not supported for onboarding.
          content:
            application/json:
              examples:
                country_not_supported:
                  value:
                    error:
                      type: invalid_request_error
                      code: country_not_supported
                      message: Onboarding is not available for foreign entities
              schema:
                $ref: '#/components/schemas/error_object'
      security:
        - api_key: []
components:
  schemas:
    onboarding_legal_representative_input:
      type: object
      properties:
        email:
          type: string
          description: Email address of the legal representative. Must use RFC 5322 format.
          example: rep@example.com
        first_name:
          type: string
          description: First name of the legal representative.
          example: Test Customer 1
        identification_number:
          type: string
          description: >-
            Mexican Unique Population Registry Code (CURP) of the legal
            representative. Must be 18 characters.
          example: AAAA010101HDFAAA01
        last_name:
          type: string
          description: Last name of the legal representative.
          example: Customer
        nationality:
          type: string
          description: Nationality as a two-letter ISO 3166-1 alpha-2 country code.
          example: mx
        position:
          type: string
          description: Position held in the company.
          example: Director General
      required:
        - first_name
        - last_name
        - email
        - nationality
        - identification_number
        - position
    onboarding_shareholder_input:
      type: object
      properties:
        children:
          type: array
          description: Nested shareholders. Only allowed when `type` is `legal_entity`.
          items:
            $ref: '#/components/schemas/onboarding_shareholder_input'
        holder_id:
          type: string
          description: Mexican tax ID (RFC) of the shareholder.
          example: AAAA010101AAA
        last_name:
          type: string
          description: Last name. Only allowed when `type` is `natural_person`.
          example: Customer
        name:
          type: string
          description: Given name of a natural person, or business name of a legal entity.
          example: Test Customer 1
        nationality:
          type: string
          description: Nationality as a two-letter ISO 3166-1 alpha-2 country code.
          example: mx
        percentage:
          type: number
          minimum: 0
          maximum: 100
          description: Participation percentage held by the shareholder.
          example: 60
        type:
          type: string
          enum:
            - natural_person
            - legal_entity
          description: Type of shareholder. One of `natural_person` or `legal_entity`.
          example: natural_person
      required:
        - type
        - name
        - holder_id
        - nationality
        - percentage
    onboarding:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the onboarding.
          example: onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K
        object:
          const: onboarding
          description: Type of the object. Always `onboarding`.
        data:
          type: object
          description: >-
            Reviewed data for the onboarding, grouped by type. Onboardings
            created through the API include `company_information` and
            `transactional_profile`. Fintoc sets `declaration_accepted` to
            `true` on creation and returns `incorporation_date` as an ISO 8601
            datetime in UTC.
          example:
            company_information:
              incorporation_date: '2020-01-15T00:00:00.000Z'
              business_activity: Servicios financieros
              fiscal_address: Av. Reforma 123, CDMX
              business_address: Av. Insurgentes 456, CDMX
              settlement_account: '000000000000000000'
              phone: '+521111111111'
            transactional_profile:
              resource_origins:
                - trusts
                - investments
              monthly_amount_range: '1_500000'
              monthly_operations_range: '1_15000'
              declaration_accepted: true
        documents:
          type: array
          description: Document slots for the onboarding, with their upload status.
          items:
            $ref: '#/components/schemas/onboarding_document'
        entity_id:
          type:
            - string
            - 'null'
          description: >-
            Identifier of the entity this onboarding belongs to. `null` if not
            associated with an entity.
          example: ent_8anBwgZktbZH6ydyHa6Tm0eM
        legal_representatives:
          type: array
          description: Legal representatives declared for the entity.
          items:
            $ref: '#/components/schemas/onboarding_legal_representative'
        reviewed_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            ISO 8601 datetime, in UTC, of when the onboarding was reviewed.
            `null` until it is reviewed.
          example: '2026-01-16T09:00:00Z'
        shareholders:
          type: array
          description: Shareholders declared for the entity.
          items:
            $ref: '#/components/schemas/onboarding_shareholder'
        source:
          type: string
          enum:
            - api
            - dashboard
          description: >-
            Channel the onboarding is being completed through. One of `api` or
            `dashboard`.
          example: api
        status:
          type: string
          enum:
            - pending
            - in_progress
            - submitted
            - approved
            - rejected
            - cancelled
          description: >-
            Current status of the onboarding. One of `pending`, `in_progress`,
            `submitted`, `approved`, `rejected` or `cancelled`.
          example: pending
        submittable:
          type: boolean
          description: >-
            Whether the onboarding has every required field and document
            completed and can be submitted for review.
          example: false
        submitted_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            ISO 8601 datetime, in UTC, of when the onboarding was submitted for
            review. `null` until it is submitted.
          example: '2026-01-15T14:30:00Z'
      required:
        - id
        - object
        - entity_id
        - status
        - source
        - submitted_at
        - reviewed_at
        - submittable
        - data
        - legal_representatives
        - shareholders
        - documents
    error_object:
      type: object
      properties:
        error:
          type: object
          description: Details of the error that caused the request to fail.
          properties:
            code:
              type: string
              description: >-
                Machine-readable code identifying the specific error, for
                example `invalid_api_key`. Not returned by every error.
              example: invalid_api_key
            doc_url:
              type: string
              description: >-
                URL of a documentation page with more details about the error.
                Not returned by every error.
              example: https://docs.fintoc.com/reference/errors
            message:
              type: string
              description: Human-readable message describing the error.
              example: 'Invalid API Key: invalid-*oken'
            param:
              type:
                - string
                - 'null'
              description: >-
                Name of the request parameter that caused the error. `null` when
                the error cannot be tied to a single parameter, and not returned
                by every error.
              example: amount
            type:
              type: string
              description: >-
                Category of the error, for example `invalid_request_error`,
                `authentication_error`, or `api_error`.
              example: invalid_request_error
          required:
            - type
            - message
    onboarding_document:
      type: object
      properties:
        filename:
          type: string
          description: >-
            Original filename of the uploaded document. Only present when
            `status` is `uploaded`.
          example: csf.pdf
        slot_key:
          type: string
          description: Key identifying the document slot.
          example: tax_registration_certificate
        status:
          type: string
          enum:
            - uploaded
            - missing
          description: Whether the slot has a document. One of `uploaded` or `missing`.
          example: uploaded
        uploaded_at:
          type: string
          format: date-time
          description: >-
            ISO 8601 datetime, in UTC, of when the document was uploaded. Only
            present when `status` is `uploaded`.
          example: '2026-01-15T14:30:00Z'
      required:
        - slot_key
        - status
    onboarding_legal_representative:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the legal representative.
          example: onblr_0ujsswThIGTUYm2K8FjOOfXtY1K
        object:
          const: onboarding_legal_representative
          description: Type of the object. Always `onboarding_legal_representative`.
        documents:
          type: array
          description: >-
            Identification and power of attorney document slots for the
            representative, with their upload status.
          items:
            $ref: '#/components/schemas/onboarding_document'
        email:
          type: string
          description: Email address of the legal representative. Must use RFC 5322 format.
          example: rep@example.com
        first_name:
          type: string
          description: First name of the legal representative.
          example: Test Customer 1
        identification_number:
          type: string
          description: >-
            Mexican Unique Population Registry Code (CURP) of the legal
            representative. Must be 18 characters.
          example: AAAA010101HDFAAA01
        last_name:
          type: string
          description: Last name of the legal representative.
          example: Customer
        nationality:
          type: string
          description: Nationality as a two-letter ISO 3166-1 alpha-2 country code.
          example: mx
        position:
          type: string
          description: Position held in the company.
          example: Director General
      required:
        - id
        - object
        - first_name
        - last_name
        - email
        - nationality
        - identification_number
        - position
        - documents
    onboarding_shareholder:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the shareholder.
          example: onbsh_0ujsswThIGTUYm2K8FjOOfXtY1K
        object:
          const: onboarding_shareholder
          description: Type of the object. Always `onboarding_shareholder`.
        document:
          $ref: '#/components/schemas/onboarding_document'
        holder_id:
          type:
            - string
            - 'null'
          description: Mexican tax ID (RFC) of the shareholder. `null` if not provided.
          example: AAAA010101AAA
        last_name:
          type: string
          description: Last name. Only present when `type` is `natural_person`.
          example: Customer
        name:
          type: string
          description: Given name of a natural person, or business name of a legal entity.
          example: Test Customer 1
        parent_id:
          type:
            - string
            - 'null'
          description: >-
            Identifier of the parent shareholder when nested. `null` for root
            shareholders.
          example: onbsh_8anBwgZktbZH6ydyHa6Tm0eM
        percentage:
          type: number
          description: Participation percentage held by the shareholder.
          example: 40
        type:
          type: string
          enum:
            - natural_person
            - legal_entity
          description: Type of shareholder. One of `natural_person` or `legal_entity`.
          example: natural_person
      required:
        - id
        - object
        - type
        - name
        - percentage
        - holder_id
        - parent_id
        - document
  securitySchemes:
    api_key:
      type: apiKey
      name: Authorization
      in: header

````