account_holder is the onboarding type for opening a client 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 each country.
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.
Availability
account_holder supports companies in Chile and Mexico. The Entity’s country_code selects the schema: see Chile or Mexico. Creating an account_holder onboarding for an Entity in any other country returns 422 Unprocessable Entity with the code country_not_supported. An Entity whose holder_id identifies an individual returns 422 Unprocessable Entity with the code holder_type_not_supported.The request shape
Sendtype and data at the top level of the create request. The keys inside data depend on the country, and every key is required:
data as a free-form object, because its shape depends on type and on the country; this page is the schema for account_holder.
Validation errors
A request with invalid data returns400 Bad Request with a single error, even when several fields fail. Fix the reported field and resend to find the next one. param names the failing field with its full path, using a dot for each nested key and brackets for each array index, such as legal_representatives[0].email.
Some errors carry a code:
Other validation failures, such as an empty
legal_representatives array, return 400 Bad Request with param set to the failing field and no code.
Chile
A Chileanaccount_holder onboarding sends seven blocks in data: company_basics, company_information, senior_management, legal_representatives, shareholders, transactional_profile, and plaft. Fintoc’s compliance team reviews the documents and answers described in Know Your Customer (KYC) requirements in Chile.
company_basics
How the company was incorporated and the name it trades under:
When
incorporation_type is one_day_company, Fintoc verifies at submission that the company’s RUT is registered as an Empresa en un Día company. If the company is not, submitting returns 422 Unprocessable Entity with the code not_one_day_company.
company_information
The company’s activity, legal structure, and addresses. Every field is required:senior_management
The company’s senior management.senior_management is an object with a single key, also named senior_management, that holds an array of members. Declare at least one member. Every field is required for every member:
An empty array returns
400 Bad Request with param set to senior_management.senior_management.
legal_representatives
The people authorized to act for the company. Declare at least one. Fintoc enforces no maximum:
An empty array returns
400 Bad Request with param set to legal_representatives. Two legal representatives with the same identification_number return 400 Bad Request with param set to the second entry, such as legal_representatives[1].identification_number.
shareholders
The company’s ownership tree. Declare at least one shareholder; an empty array returnsinvalid_shareholder_structure with reason set to shareholders_required. Every node in the tree, at the root and at any depth, takes these fields:
Four rules constrain the tree. Each structure error returns the code
invalid_shareholder_structure, with reason set to the value in parentheses:
- Each level sums to
100or less. Chile sets no minimum sum. A level above100fails (shareholder_participation_exceeded). - Only a
legal_entitynests. Anatural_personcarryingchildrenfails (only_legal_entity_can_nest). Fintoc sets no limit on nesting depth. - Each
holder_idis unique within its level. Two shareholders at the root, or under the same parent, with the sameholder_idfail (duplicate_shareholder). The sameholder_idcan appear at different levels. - At least one effective controller. Fintoc checks this rule when you submit, not when you create the onboarding. With no shareholder set to
effective_controller: true, submitting returns422 Unprocessable Entitywith the codeeffective_controller_required.
transactional_profile
The sources of the company’s equity and funds, and how the company uses Fintoc. Every field is required, and each one is an array that takes at least one value:business_relationship_purposes accepts these values:
equity_origins accepts these values:
resource_origins accepts these values:
A value outside these lists, including a Mexican value such as
trusts, returns invalid_enum.
plaft
The company’s declaration on anti-money laundering and terrorist financing prevention (PLAFT):Chilean document slots
Creating the onboarding opens every company slot thatcompany_basics.incorporation_type selects, each one reporting missing until you upload a file. The maximum file size is 20 MB for every slot. Fintoc reads the content type of a company slot from the file bytes, and every company slot accepts application/pdf only.
The top-level documents array lists these company slots:
Each legal representative gets its own
documents array with two slots. Fintoc checks the part’s declared Content-Type for these slots, so send it as one of the accepted types:
Chilean shareholders have no document slot. Each shareholder returns
document set to null.
A traditional company with uaf_obligated set to false and one legal representative needs six files to submit: e_rut, activities_start_certificate, good_standing_certificate, incorporation_deed, and the two identification sides.
Chilean example
This payload declares one legal representative, one senior manager, and two root shareholders. One root shareholder nests a third shareholder. Every value is test data that belongs to no real company or person.Mexico
A Mexicanaccount_holder onboarding sends four blocks in data: company_information, legal_representatives, transactional_profile, and shareholders. Fintoc’s compliance team reviews the documents and answers described in KYC requirements in Mexico.
company_information
The company’s identity and settlement details. Every field is required:sector accepts these values:
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:
An empty array returns
400 Bad Request with param set to legal_representatives. An invalid entry returns param with the index of the failing entry, such as legal_representatives[0].email.
transactional_profile
The volume, the source, and the purpose of the money theEntity expects to move:
Former
monthly_amount_range valuesFintoc still accepts the former values 1_500000, 500001_1000000, and gt_1000000, which counted amounts in US dollars. Fintoc maps 1_500000 to 2000001_10000000; it maps both 500001_1000000 and gt_1000000 to gt_10000000. The response returns the converted value. Send the MXN values in new integrations.account_purpose accepts these values:
resource_origins accepts these values:
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 returnsinvalid_shareholder_structure with reason set to shareholders_required. Every node in the tree, at the root and at any depth, takes these fields:
Two rules constrain the tree. Each structure error returns the code
invalid_shareholder_structure, with reason set to the value in parentheses:
- The root sums to between
76and100. The root percentages must sum to at least76(participation_below_threshold) and at most100(shareholder_participation_exceeded). Eachchildrenarray must sum to100or less, with no minimum. - Only a
legal_entitynests. Anatural_personcarryingchildrenfails (only_legal_entity_can_nest). Alegal_entitywith nochildrenis valid. Fintoc sets no limit on nesting depth.
Mexican document slots
Creating the onboarding opens every slot the type requires, each one reportingmissing 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:
Each legal representative gets its own
documents array with two slots:
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:
A company with one legal representative and three shareholders therefore opens ten slots: five company slots, two for the representative, and one per shareholder.
Every Mexican
account_holder slot accepts a single file, so uploading again with PUT replaces the existing file. Each uploaded entry in the top-level documents array carries an id that you can pass to DELETE .../documents/{slot_key}/{document_id} to remove the file. See Manage files in a slot.
Mexican 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. Thesettlement_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.
What’s next
- Onboard an entity by API for the full flow, including the uploads, the submission, and the review.
- KYC requirements in Chile and KYC requirements in Mexico for the documents Fintoc’s compliance team reviews.
- The Onboarding object for the response attributes.