--- title: "Create an onboarding" method: POST path: "/entities/{entity_id}/onboardings" tags: ["Onboardings"] --- # Create an onboarding `POST /entities/{entity_id}/onboardings` Starts an onboarding process for the entity using the company information, legal representatives, transactional profile, and shareholders provided in the request. Further requests upload documents and submit the onboarding, whose country is taken from the entity. ## Path parameters - `entity_id` string, required ## Request body - object - `company_information` object, required — Company information of the entity. - `business_activity` string, required — Primary business activity of the company. - `business_address` string, required — Physical business address. - `fiscal_address` string, required — Registered fiscal address. - `incorporation_date` string, date, required — Incorporation date, as an ISO 8601 date. - `phone` string, required — Contact phone number in E.164 format. - `settlement_account` string, required — Settlement account as an 18-digit standardized Mexican bank account number (CLABE). - `legal_representatives` OnboardingLegalRepresentativeInput[], required — Legal representatives of the company. Must contain at least one entry. - `email` string, required — Email address of the legal representative. Must use RFC 5322 format. - `first_name` string, required — First name of the legal representative. - `identification_number` string, required — Mexican Unique Population Registry Code (CURP) of the legal representative. Must be 18 characters. - `last_name` string, required — Last name of the legal representative. - `nationality` string, required — Nationality as a two-letter ISO 3166-1 alpha-2 country code. - `position` string, required — Position held in the company. - `transactional_profile` object, required — Expected transactional profile of the entity. - `monthly_amount_range` '1_500000' | '500001_1000000' | 'gt_1000000', required — Expected monthly transacted amount range, in MXN. Use `1_500000` for 1 to 500,000 MXN, `500001_1000000` for 500,001 to 1,000,000 MXN, or `gt_1000000` for more than 1,000,000 MXN. - `monthly_operations_range` '1_15000' | '15001_50000' | 'gte_50001', required — Expected monthly number of operations range. Use `1_15000` for 1 to 15,000 operations, `15001_50000` for 15,001 to 50,000 operations, or `gte_50001` for 50,001 or more operations. - `resource_origins` string[], required — Declared origins of the entity's resources. One or more of `trusts`, `budget_allocations`, `royalties`, `asset_sales`, `investments`, `profits`, or `donations`. - `shareholders` OnboardingShareholderInput[], required — Shareholder structure of the entity. Each level's participation percentages must sum to at least 76 and at most 100. Only `legal_entity` shareholders may declare nested `children`. - `children` OnboardingShareholderInput[] — Nested shareholders. Only allowed when `type` is `legal_entity`. - `holder_id` string, required — Mexican tax ID (RFC) of the shareholder. - `last_name` string — Last name. Only allowed when `type` is `natural_person`. - `name` string, required — Given name of a natural person, or business name of a legal entity. - `nationality` string, required — Nationality as a two-letter ISO 3166-1 alpha-2 country code. - `percentage` number, required — Participation percentage held by the shareholder. - `type` 'natural_person' | 'legal_entity', required — Type of shareholder. One of `natural_person` or `legal_entity`. ## Response `201` The API starts the onboarding process from the provided data and returns the created onboarding. - Onboarding - `id` string, required — Unique identifier of the onboarding. - `object` 'onboarding', required — Type of the object. Always `onboarding`. - `data` object, required — 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. - `documents` OnboardingDocument[], required — Document slots for the onboarding, with their upload status. - `filename` string — Original filename of the uploaded document. Only present when `status` is `uploaded`. - `slot_key` string, required — Key identifying the document slot. - `status` 'uploaded' | 'missing', required — Whether the slot has a document. One of `uploaded` or `missing`. - `uploaded_at` string, date-time — ISO 8601 datetime, in UTC, of when the document was uploaded. Only present when `status` is `uploaded`. - `entity_id` string, nullable, required — Identifier of the entity this onboarding belongs to. `null` if not associated with an entity. - `legal_representatives` OnboardingLegalRepresentative[], required — Legal representatives declared for the entity. - `id` string, required — Unique identifier of the legal representative. - `object` 'onboarding_legal_representative', required — Type of the object. Always `onboarding_legal_representative`. - `documents` OnboardingDocument[], required — Identification and power of attorney document slots for the representative, with their upload status. - `filename` string — Original filename of the uploaded document. Only present when `status` is `uploaded`. - `slot_key` string, required — Key identifying the document slot. - `status` 'uploaded' | 'missing', required — Whether the slot has a document. One of `uploaded` or `missing`. - `uploaded_at` string, date-time — ISO 8601 datetime, in UTC, of when the document was uploaded. Only present when `status` is `uploaded`. - `email` string, required — Email address of the legal representative. Must use RFC 5322 format. - `first_name` string, required — First name of the legal representative. - `identification_number` string, required — Mexican Unique Population Registry Code (CURP) of the legal representative. Must be 18 characters. - `last_name` string, required — Last name of the legal representative. - `nationality` string, required — Nationality as a two-letter ISO 3166-1 alpha-2 country code. - `position` string, required — Position held in the company. - `reviewed_at` string, date-time, nullable, required — ISO 8601 datetime, in UTC, of when the onboarding was reviewed. `null` until it is reviewed. - `shareholders` OnboardingShareholder[], required — Shareholders declared for the entity. - `id` string, required — Unique identifier of the shareholder. - `object` 'onboarding_shareholder', required — Type of the object. Always `onboarding_shareholder`. - `document` OnboardingDocument, required - `filename` string — Original filename of the uploaded document. Only present when `status` is `uploaded`. - `slot_key` string, required — Key identifying the document slot. - `status` 'uploaded' | 'missing', required — Whether the slot has a document. One of `uploaded` or `missing`. - `uploaded_at` string, date-time — ISO 8601 datetime, in UTC, of when the document was uploaded. Only present when `status` is `uploaded`. - `holder_id` string, nullable, required — Mexican tax ID (RFC) of the shareholder. `null` if not provided. - `last_name` string — Last name. Only present when `type` is `natural_person`. - `name` string, required — Given name of a natural person, or business name of a legal entity. - `parent_id` string, nullable, required — Identifier of the parent shareholder when nested. `null` for root shareholders. - `percentage` number, required — Participation percentage held by the shareholder. - `type` 'natural_person' | 'legal_entity', required — Type of shareholder. One of `natural_person` or `legal_entity`. - `source` 'api' | 'dashboard', required — Channel the onboarding is being completed through. One of `api` or `dashboard`. - `status` 'pending' | 'in_progress' | 'submitted' | 'approved' | 'rejected' | 'cancelled', required — Current status of the onboarding. One of `pending`, `in_progress`, `submitted`, `approved`, `rejected` or `cancelled`. - `submittable` boolean, required — Whether the onboarding has every required field and document completed and can be submitted for review. - `submitted_at` string, date-time, nullable, required — ISO 8601 datetime, in UTC, of when the onboarding was submitted for review. `null` until it is submitted. ## Other responses - `400` — The data failed validation: a required field is missing or invalid, or the shareholder structure is invalid (for example a level's participation percentages sum to more than 100). - `401` — Invalid or missing API key. - `404` — The entity does not exist. - `409` — An onboarding already exists for the entity. The response body includes the `active_onboarding_id` of the existing onboarding. - `422` — The entity's country is not supported for onboarding. --- [API](https://skmtc.net/fintoc/apis/fintoc-api.md) · [All operations](https://skmtc.net/fintoc/apis/fintoc-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/fintoc/fintoc-api/revisions/9dafa63688a3/schema)