Account holder onboarding

account_holder is the onboarding type for opening a Mexican Entity as an account holder. After Fintoc approves the review, the Entity can own Account objects. This page documents the schema you send in data when you create an account_holder onboarding and the document slots the onboarding opens. For the end-to-end flow, from creating the Entity to submitting for review, follow Onboard an entity by API. This page covers only what is specific to the account_holder type.

Availabilityaccount_holder supports Mexican Entity objects. Creating an account_holder onboarding for an Entity in another country returns 422 Unprocessable Entity with the code country_not_supported.

The request shape

Send type and data at the top level of the create request:

{
  "type": "account_holder",
  "data": {
    "company_information": { },
    "legal_representatives": [ ],
    "transactional_profile": { },
    "shareholders": [ ]
  }
}

The data object holds four keys, all required. The sections below document each one. The API reference describes data as a free-form object, because its shape depends on type; this page is the schema for account_holder. legal_representatives and shareholders report errors independently, so one response can carry errors from both blocks. company_information and transactional_profile are the exception. Fintoc validates them in that order and stops at the first block that fails. A request with errors in both blocks reports only company_information.

company_information

The company’s identity and settlement details. Every field is required:

Field	Type	Required	Description
`business_activity`	string	Required	Primary business activity of the company.
`business_address`	string	Required	Physical address where the company operates.
`fiscal_address`	string	Required	Address registered with the Mexican tax authority.
`incorporation_date`	string	Required	Date the company was incorporated, as an ISO 8601 date. The response returns this value as an ISO 8601 datetime in UTC.
`phone`	string	Required	Contact phone number in E.164 format: a leading `+` followed by 8 to 15 digits, the first of which cannot be `0`.
`settlement_account`	string	Required	Account that receives settlements, as an 18-digit standardized Mexican bank account number (CLABE).

CLABE validation differs by modesettlement_account must have 18 digits. Fintoc accepts the value when the first three digits match a supported Mexican institution and the CLABE control digit checks out. Fintoc also accepts its own CLABEs and skips the control digit for them. In test mode, this applies to sandbox bank codes. In live mode, this applies to Fintoc’s own bank code. A CLABE at a supported Mexican institution behaves the same in both modes. A sandbox CLABE that works in test returns an error in live. An invalid value returns 400 Bad Request with the code invalid_clabe and param set to company_information.settlement_account.

legal_representatives

The people authorized to act for the company. Declare at least one. Fintoc enforces no maximum, and every field is required for every entry:

Field	Type	Required	Description
`email`	string	Required	Email address of the legal representative.
`first_name`	string	Required	Given name of the legal representative.
`identification_number`	string	Required	Mexican Unique Population Registry Code (CURP) of the legal representative.
`last_name`	string	Required	Family name of the legal representative.
`nationality`	string	Required	Two-letter ISO 3166-1 alpha-2 country code of the legal representative’s nationality. Fintoc accepts uppercase and lowercase values. The response returns the value as you sent it.
`position`	string	Required	Role the legal representative holds in the company, such as `Director General`.

An empty array returns 400 Bad Request with the code legal_representatives_required. Errors on this block accumulate across entries, and param carries the index of the failing entry, such as legal_representatives.0.email.

transactional_profile

The volume and the source of the money the Entity expects to move. Every field is required:

Field	Type	Required	Description
`monthly_amount_range`	string	Required	Expected monthly transacted amount in Mexican pesos. One of `1_500000` for 1 to 500,000, `500001_1000000` for 500,001 to 1,000,000, or `gt_1000000` for more than 1,000,000.
`monthly_operations_range`	string	Required	Expected monthly number of operations. One of `1_15000` for 1 to 15,000, `15001_50000` for 15,001 to 50,000, or `gte_50001` for 50,001 or more.
`resource_origins`	array of string	Required	Where the money the `Entity` moves comes from. Send at least one value from the list below.

resource_origins accepts these values:

`resource_origins` value	Source of funds
`asset_sales`	Proceeds from selling assets.
`budget_allocations`	Budget assigned by another organization.
`donations`	Donations received.
`investments`	Returns on investments.
`profits`	Operating profits of the company.
`royalties`	Royalty payments.
`trusts`	Distributions from a trust.

The response echoes transactional_profile with declaration_accepted set to true, which Fintoc adds when it creates the onboarding. Do not send declaration_accepted; the API ignores it.

shareholders

The company’s ownership tree. Declare at least one shareholder; an empty array returns 400 Bad Request with the code shareholders_required. Every node in the tree, at the root and at any depth, takes these fields:

Field	Type	Required	Description
`children`	array of shareholder	Optional, `legal_entity` only	Shareholders that own this shareholder. Send this only when `type` is `legal_entity`.
`holder_id`	string	Required	Mexican tax ID (RFC) of the shareholder.
`last_name`	string	Optional, `natural_person` only	Family name of the shareholder. Send this only when `type` is `natural_person`. Sending it for a `legal_entity` returns `400 Bad Request` with the code `invalid_name`.
`name`	string	Required	Given name when `type` is `natural_person`, or business name when `type` is `legal_entity`.
`nationality`	string	Required	Two-letter ISO 3166-1 alpha-2 country code of the shareholder’s nationality. Fintoc accepts either case and returns the value as you sent it.
`percentage`	number	Required	Participation the shareholder holds, from `0` to `100`. Send a JSON number; the API rejects a numeric string.
`type`	string	Required	Kind of shareholder. One of `natural_person` or `legal_entity`.

Two rules constrain the tree:

Each level sums to between 76 and 100. The root percentages must sum to at least 76 and at most 100. Each children array must meet the same range. A level below 76 returns the code participation_below_threshold. A level above 100 returns the code shareholder_participation_exceeded.
Only a legal_entity nests. A natural_person carrying children returns the code only_legal_entity_can_nest. A legal_entity with no children is valid, and Fintoc runs no sum check on a level that does not exist. Fintoc sets no limit on nesting depth.

Unlike legal_representatives, this block reports one error at a time. Fix the reported node and resend.

Document slots

Creating the onboarding opens every slot the type requires, each one reporting missing until you upload a file. Every slot is required before you can submit. The maximum file size is 20 MB for every slot. For company slots and shareholder documents, Fintoc reads the content type from the file bytes. The content type your upload declares does not matter. The two legal representative slots check both values. Send the part’s Content-Type as one of the accepted types for that slot, because Fintoc rejects the upload before it inspects the bytes. The onboarding opens five company slots, listed in the top-level documents array:

`slot_key`	Accepted content types
`articles_of_incorporation`	`application/pdf`
`proof_of_address`	`application/pdf`, `image/jpeg`, `image/png`
`settlement_bank_statement`	`application/pdf`
`shareholder_structure`	`application/pdf`
`tax_registration_certificate`	`application/pdf`

Each legal representative gets its own documents array with two slots:

`slot_key`	Accepted content types
`identification`	`application/pdf`, `image/jpeg`, `image/png`
`power_of_attorney`	`application/pdf`

Each shareholder gets a single document object rather than an array, because a shareholder holds exactly one document. Fintoc picks the slot from the shareholder’s type, so the upload path carries no slot_key:

Shareholder `type`	`slot_key`	Accepted content types
`legal_entity`	`articles_of_incorporation`	`application/pdf`, `image/jpeg`, `image/png`
`natural_person`	`identification`	`application/pdf`, `image/jpeg`, `image/png`

A company with one legal representative and three shareholders therefore opens ten slots: five company slots, two for the representative, and one per shareholder.

A complete example

This payload declares one legal representative and two root shareholders. One root shareholder nests a third shareholder. Every value is test data that belongs to no real company or person. The settlement_account is a documented test CLABE. Fintoc accepts it because its bank code and control digit are valid. An all-zeros CLABE returns 400 Bad Request, because 000 is not a supported bank code.

{
  "type": "account_holder",
  "data": {
    "company_information": {
      "business_activity": "Servicios financieros",
      "business_address": "Av. Insurgentes 456, CDMX",
      "fiscal_address": "Av. Reforma 123, CDMX",
      "incorporation_date": "2020-01-15",
      "phone": "+521111111111",
      "settlement_account": "646969000000000000"
    },
    "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",
        "holder_id": "AAAA010101AAA",
        "nationality": "mx",
        "percentage": 60
      },
      {
        "type": "legal_entity",
        "name": "Test Entity 2",
        "holder_id": "AAA010101AAA",
        "nationality": "mx",
        "percentage": 40,
        "children": [
          {
            "type": "natural_person",
            "name": "Test Customer 3",
            "last_name": "Customer",
            "holder_id": "AAAA010101AAA",
            "nationality": "mx",
            "percentage": 80
          }
        ]
      }
    ]
  }
}

What’s next

Onboard an entity by API for the full flow, including the uploads, the submission, and the review.
KYC requirements for Mexico for the documents Fintoc’s compliance team reviews.
The Onboarding object for the response attributes.

​The request shape

​company_information

​legal_representatives

​transactional_profile

​shareholders

​Document slots

​A complete example

​What’s next

The request shape

company_information

legal_representatives

transactional_profile

shareholders

Document slots

A complete example

What’s next