> ## 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.
# Account holder onboarding
> The data schema and document slots for the account_holder onboarding type: company information, legal representatives, transactional profile, and shareholders.
`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](/guides/business-accounts/entities/onboard-an-entity-by-api). This page covers only what is specific to the `account_holder` type.
**Availability**
`account_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:
```json theme={null}
{
"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 mode**
`settlement_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.
```json theme={null}
{
"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](/guides/business-accounts/entities/onboard-an-entity-by-api) for the full flow, including the uploads, the submission, and the review.
* [KYC requirements for Mexico](/guides/business-accounts/kyc-requirements/mexico) for the documents Fintoc's compliance team reviews.
* [The Onboarding object](/api/business-accounts-api/onboardings/onboarding-object) for the response attributes.