Skip to main content
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.
Availabilityaccount_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

Send type and data at the top level of the create request. The keys inside data depend on the country, and every key is required:
The API reference describes 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 returns 400 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 Chilean account_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. 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 returns invalid_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 100 or less. Chile sets no minimum sum. A level above 100 fails (shareholder_participation_exceeded).
  • Only a legal_entity nests. A natural_person carrying children fails (only_legal_entity_can_nest). Fintoc sets no limit on nesting depth.
  • Each holder_id is unique within its level. Two shareholders at the root, or under the same parent, with the same holder_id fail (duplicate_shareholder). The same holder_id can 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 returns 422 Unprocessable Entity with the code effective_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 that company_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 Mexican account_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:
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 param set to company_information.settlement_account.
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 the Entity 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 returns invalid_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 76 and 100. The root percentages must sum to at least 76 (participation_below_threshold) and at most 100 (shareholder_participation_exceeded). Each children array must sum to 100 or less, with no minimum.
  • Only a legal_entity nests. A natural_person carrying children fails (only_legal_entity_can_nest). A legal_entity with no children is valid. Fintoc sets no limit on nesting depth.

Mexican 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: 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. 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.

What’s next