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

# Upload a shareholder document

> Use this endpoint to upload the identity document for one onboarding shareholder. Send the file as `multipart/form-data`. The file must be a PDF, JPEG, or PNG and cannot exceed 20 MB. The expected document type depends on the shareholder type: an identification for a natural person, or the articles of incorporation for a legal entity. You can upload documents only while the onboarding is in progress.

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


## OpenAPI

````yaml reference/fintoc-api-v2.json PUT /entities/{entity_id}/onboardings/{id}/shareholders/{shareholder_id}/document
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/{id}/shareholders/{shareholder_id}/document:
    put:
      tags:
        - Onboardings
      summary: Upload a shareholder document
      description: >-
        Use this endpoint to upload the identity document for one onboarding
        shareholder. Send the file as `multipart/form-data`. The file must be a
        PDF, JPEG, or PNG and cannot exceed 20 MB. The expected document type
        depends on the shareholder type: an identification for a natural person,
        or the articles of incorporation for a legal entity. You can upload
        documents only while the onboarding is in progress.
      operationId: entities-onboardings-upload-shareholder-document
      parameters:
        - name: entity_id
          in: path
          description: >-
            The unique identifier of the entity (for example
            `ent_8anBwgZktbZH6ydyHa6Tm0eM`).
          required: true
          schema:
            type: string
        - name: id
          in: path
          description: >-
            The unique identifier of the onboarding (for example
            `onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K`).
          required: true
          schema:
            type: string
        - name: shareholder_id
          in: path
          description: >-
            The unique identifier of the shareholder (for example
            `onbsh_0ujsswThIGTUYm2K8FjOOfXtY1K`).
          required: true
          schema:
            type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: >-
                    The document to upload. Must be a PDF, JPEG, or PNG and
                    cannot exceed 20 MB.
              required:
                - file
        required: true
      responses:
        '200':
          description: >-
            Returns the onboarding after Fintoc uploads the document. The
            shareholder document `status` is `uploaded`.
          content:
            application/json:
              examples:
                shareholder_document_uploaded:
                  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:
                        legal_name: Acme SA de CV
                    legal_representatives: []
                    shareholders:
                      - id: onbsh_0ujsswThIGTUYm2K8FjOOfXtY1K
                        object: onboarding_shareholder
                        type: natural_person
                        name: Test
                        last_name: Customer
                        percentage: 40
                        holder_id: AAAA010101AAA
                        parent_id: null
                        document:
                          slot_key: identification
                          status: uploaded
                    documents: []
              schema:
                $ref: '#/components/schemas/onboarding'
        '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 onboarding or the shareholder does not exist, or the onboarding
            belongs to another organization or entity.
          content:
            application/json:
              examples:
                shareholder_not_found:
                  value:
                    error:
                      type: invalid_request_error
                      code: missing_resource
                      param: shareholder_id
                      message: 'No such shareholder: onbsh_0ujsswThIGTUYm2K8FjOOfXtY1K'
                      doc_url: https://docs.fintoc.com/reference/errors
              schema:
                $ref: '#/components/schemas/error_object'
        '422':
          description: >-
            Fintoc cannot process the upload: the onboarding is no longer in
            progress, or the file has an unsupported type or exceeds the size
            limit.
          content:
            application/json:
              examples:
                onboarding_immutable:
                  value:
                    error:
                      type: invalid_request_error
                      code: onboarding_immutable
                      message: >-
                        The onboarding is no longer in progress and cannot
                        accept documents
              schema:
                $ref: '#/components/schemas/error_object'
      security:
        - api_key: []
components:
  schemas:
    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

````