Onboard an entity by API

Use the API to create and onboard an Entity that can own Account objects after approval, without using the dashboard. This flow is for platforms that create an Entity for each client, such as marketplaces or wallets that hold balances under each client’s legal name. To create Account objects under your own root Entity, see Create more accounts instead.

AvailabilityOnboarding by API supports client Entity objects in Chile and Mexico. This guide covers the account_holder type, which opens a company as an account holder. An Entity that only receives its share of split payments uses the settlement_recipient type instead. See Accept split payments.

Complete the flow through the APIAn onboarding you create through the API carries source set to api and stays in that channel. You cannot continue that onboarding from the dashboard: uploading the documents, submitting for review, and tracking the result all happen through the API.

The flow is the same in both countries. The tabs in each step show what changes between Chile and Mexico: the tax ID, the data fields, the document slots, and the account number format. Chilean onboardings have no shareholder documents, so they skip Step 5.

Before you start

You need a secret key from the dashboard, under Developers → API Keys. The key you send selects the mode: sk_test_... runs in test, and sk_live_... runs in live. Use test mode to build and verify your integration. Use live mode to onboard each real client. These are separate activities, not two phases of one flow. A test onboarding is a different object from a live onboarding and never becomes a live onboarding. Onboarding a client in test does not advance that client’s live onboarding. The examples below use a test key. Your organization also needs its own root Entity (is_root set to true) in the same mode as the API key you send. Fintoc checks this requirement when you create a client Entity. To onboard clients in live, your organization needs a live root Entity. To build in test, your organization needs a test root Entity.

Step 1: Create the entity

An Entity is the legal account holder. Create one for your client with their legal name and tax ID. The account_holder type onboards companies only, so holder_id must identify a company.

Chile
Mexico

Set country_code to cl, and set holder_id to the company’s Chilean tax ID (RUT). holder_id is required and must be a valid RUT, with or without dots and hyphen. An invalid RUT returns 400 Bad Request with the code invalid_holder_id.

curl --request POST \
     --url https://api.fintoc.com/v2/entities \
     --header 'Authorization: YOUR_TEST_SECRET_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "country_code": "cl",
  "holder_name": "Test Entity 1",
  "holder_id": "77.777.777-7"
}
'

{
  "id": "ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
  "object": "entity",
  "country_code": "cl",
  "holder_id": "777777777",
  "holder_name": "Test Entity 1",
  "is_root": false,
  "mode": "test",
  "status": "waiting_initialization"
}

Fintoc stores the RUT without dots or hyphen. A RUT that belongs to an individual creates the Entity, but creating its account_holder onboarding returns 422 Unprocessable Entity with the code holder_type_not_supported.

Set country_code to mx, and set holder_id to the company’s Mexican tax ID (RFC).

curl --request POST \
     --url https://api.fintoc.com/v2/entities \
     --header 'Authorization: YOUR_TEST_SECRET_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "country_code": "mx",
  "holder_name": "Test Entity 1",
  "holder_id": "AAA010101AAA"
}
'

{
  "id": "ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
  "object": "entity",
  "country_code": "mx",
  "holder_id": "AAA010101AAA",
  "holder_name": "Test Entity 1",
  "is_root": false,
  "mode": "test",
  "status": "waiting_initialization"
}

A 13-character RFC belongs to an individual. That Entity is created, but creating its account_holder onboarding returns 422 Unprocessable Entity with the code holder_type_not_supported.

Save the Entity ID (ent_...); every onboarding call uses this value. See The Entity object for the full attribute list. If your organization has no root Entity in the mode of your API key, Fintoc rejects the request with 422 Unprocessable Entity, type set to invalid_request_error, and code set to organization_without_operational_root_entity:

Error response

{
  "error": {
    "type": "invalid_request_error",
    "code": "organization_without_operational_root_entity",
    "message": "The organization does not have an operational root entity",
    "doc_url": "https://docs.fintoc.com/reference/errors"
  }
}

Check that you are using the key for the right mode. If your organization has no root Entity in that mode, contact Fintoc support before you create client Entity objects.

Step 2: Create the onboarding

The Onboarding holds the Know Your Customer review for one Entity. The review covers the company, its legal representatives, its transactional profile, and its shareholders. Create one onboarding per Entity. The request body has two top-level fields, both required. Set type to account_holder, the type this guide covers. The other accepted value, settlement_recipient, has its own flow in Accept split payments. Send the review data in data. The keys of data depend on the Entity’s country, and every key is required. See Account holder onboarding for every field, enum value, and validation rule. Omitting type or data returns 400 Bad Request with the code missing_parameter. A type outside the accepted values returns 400 Bad Request with the code invalid_enum. The error message names the accepted values. An Entity holds at most one onboarding per mode, so the same Entity can hold one live onboarding and one test onboarding at the same time. A second onboarding in the same mode returns 409 Conflict, even when the first one is already rejected.

Chile
Mexico

A Chilean onboarding sends seven keys in data: company_basics, company_information, senior_management, legal_representatives, shareholders, transactional_profile, and plaft.

curl --request POST \
     --url https://api.fintoc.com/v2/entities/ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN/onboardings \
     --header 'Authorization: YOUR_TEST_SECRET_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "type": "account_holder",
  "data": {
    "company_basics": {
      "incorporation_type": "traditional",
      "fantasy_name": "Test Company"
    },
    "company_information": {
      "activities_start_date": "2019-03-01",
      "business_activity_code": "620200",
      "company_type": "spa",
      "business_address": "Av. Apoquindo 100, Santiago",
      "fiscal_address": "Av. Apoquindo 100, Santiago"
    },
    "senior_management": {
      "senior_management": [
        {
          "name": "Test Customer 1",
          "nationality": "cl",
          "identification_number": "11.111.111-1",
          "position": "Gerente General"
        }
      ]
    },
    "legal_representatives": [
      {
        "first_name": "Test Customer 1",
        "last_name": "Customer",
        "email": "jon@snow.com",
        "nationality": "cl",
        "identification_number": "11.111.111-1",
        "position": "Representante legal",
        "phone": "+56911111111"
      }
    ],
    "shareholders": [
      {
        "type": "natural_person",
        "name": "Test Customer 1",
        "last_name": "Customer",
        "holder_id": "11.111.111-1",
        "nationality": "cl",
        "percentage": 60,
        "address": "Av. Apoquindo 100, Santiago",
        "fiscal_address": "Av. Apoquindo 100, Santiago",
        "effective_controller": true
      },
      {
        "type": "legal_entity",
        "name": "Test Entity 2",
        "holder_id": "88.888.888-8",
        "nationality": "cl",
        "percentage": 40,
        "address": "Av. Apoquindo 100, Santiago",
        "fiscal_address": "Av. Apoquindo 100, Santiago",
        "effective_controller": false,
        "children": [
          {
            "type": "natural_person",
            "name": "Test Customer 2",
            "last_name": "Customer",
            "holder_id": "22.222.222-2",
            "nationality": "cl",
            "percentage": 100,
            "address": "Av. Apoquindo 100, Santiago",
            "fiscal_address": "Av. Apoquindo 100, Santiago",
            "effective_controller": false
          }
        ]
      }
    ],
    "transactional_profile": {
      "equity_origins": ["capital_contributions"],
      "business_relationship_purposes": ["customer_collections", "supplier_payments"],
      "resource_origins": ["operating_income"]
    },
    "plaft": {
      "uaf_obligated": false
    }
  }
}
'

{
  "id": "onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K",
  "object": "onboarding",
  "entity_id": "ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
  "type": "account_holder",
  "status": "in_progress",
  "source": "api",
  "submittable": false,
  "submitted_at": null,
  "reviewed_at": null,
  "legal_representatives": [
    {
      "id": "onblr_0ujsswThIGTUYm2K8FjOOfXtY1K",
      "object": "onboarding_legal_representative",
      "documents": [
        { "slot_key": "identification_front", "status": "missing" },
        { "slot_key": "identification_back", "status": "missing" }
      ]
    }
  ],
  "shareholders": [
    {
      "id": "onbsh_0ujsswThIGTUYm2K8FjOOfXtY1K",
      "object": "onboarding_shareholder",
      "type": "natural_person",
      "parent_id": null,
      "effective_controller": true,
      "document": null
    },
    {
      "id": "onbsh_8anBwgZktbZH6ydyHa6Tm0eM",
      "object": "onboarding_shareholder",
      "type": "legal_entity",
      "parent_id": null,
      "effective_controller": false,
      "document": null
    },
    {
      "id": "onbsh_9bnCxhAlucAI7zezIb7Un1fN",
      "object": "onboarding_shareholder",
      "type": "natural_person",
      "parent_id": "onbsh_8anBwgZktbZH6ydyHa6Tm0eM",
      "effective_controller": false,
      "document": null
    }
  ],
  "documents": [
    { "slot_key": "e_rut", "status": "missing" },
    { "slot_key": "activities_start_certificate", "status": "missing" },
    { "slot_key": "good_standing_certificate", "status": "missing" },
    { "slot_key": "power_of_attorney", "status": "missing" },
    { "slot_key": "incorporation_deed", "status": "missing" },
    { "slot_key": "incorporation_amendments", "status": "missing" },
    { "slot_key": "uaf_registration_certificate", "status": "missing" },
    { "slot_key": "plaft_manual_and_policies", "status": "missing" }
  ]
}

Four details to note in the Chilean response:

documents depends on company_basics.incorporation_type. A traditional company opens the slots above. A one_day_company (Empresa en un Día) opens current_shareholders_certificate instead of activities_start_certificate and good_standing_certificate.
documents always lists uaf_registration_certificate and plaft_manual_and_policies. You upload them only when plaft.uaf_obligated is true.
Each legal representative has its own documents array with two slots: the front and the back of the identity document.
Each shareholder has document set to null, because Chile requires no document per shareholder.

The legal representative’s identification_number and each shareholder’s holder_id take a Chilean tax ID (RUT) when nationality is cl. A foreign legal representative uses a passport number.

A Mexican onboarding sends four keys in data: company_information, legal_representatives, transactional_profile, and shareholders.

curl --request POST \
     --url https://api.fintoc.com/v2/entities/ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN/onboardings \
     --header 'Authorization: YOUR_TEST_SECRET_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "type": "account_holder",
  "data": {
    "company_information": {
      "business_activity": "Servicios financieros",
      "sector": "ecommerce",
      "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_2000000",
      "monthly_operations_range": "1_15000",
      "account_purpose": "own_sales_collection"
    },
    "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
          }
        ]
      }
    ]
  }
}
'

{
  "id": "onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K",
  "object": "onboarding",
  "entity_id": "ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
  "type": "account_holder",
  "status": "in_progress",
  "source": "api",
  "submittable": false,
  "submitted_at": null,
  "reviewed_at": null,
  "legal_representatives": [
    {
      "id": "onblr_0ujsswThIGTUYm2K8FjOOfXtY1K",
      "object": "onboarding_legal_representative",
      "documents": [
        { "slot_key": "identification", "status": "missing" },
        { "slot_key": "power_of_attorney", "status": "missing" }
      ]
    }
  ],
  "shareholders": [
    {
      "id": "onbsh_0ujsswThIGTUYm2K8FjOOfXtY1K",
      "object": "onboarding_shareholder",
      "type": "natural_person",
      "parent_id": null,
      "document": { "slot_key": "identification", "status": "missing" }
    },
    {
      "id": "onbsh_8anBwgZktbZH6ydyHa6Tm0eM",
      "object": "onboarding_shareholder",
      "type": "legal_entity",
      "parent_id": null,
      "document": { "slot_key": "articles_of_incorporation", "status": "missing" }
    },
    {
      "id": "onbsh_9bnCxhAlucAI7zezIb7Un1fN",
      "object": "onboarding_shareholder",
      "type": "natural_person",
      "parent_id": "onbsh_8anBwgZktbZH6ydyHa6Tm0eM",
      "document": { "slot_key": "identification", "status": "missing" }
    }
  ],
  "documents": [
    { "slot_key": "tax_registration_certificate", "status": "missing" },
    { "slot_key": "settlement_bank_statement", "status": "missing" },
    { "slot_key": "proof_of_address", "status": "missing" },
    { "slot_key": "shareholder_structure", "status": "missing" },
    { "slot_key": "articles_of_incorporation", "status": "missing" }
  ]
}

Every Mexican onboarding opens five company slots, two slots per legal representative, and one slot per shareholder. The onboarding above declares one legal representative and three shareholders, so it opens ten slots in total.Some fields use Mexico-specific identifiers. The legal representative’s identification_number is a Mexican Unique Population Registry Code (CURP). The settlement_account is an 18-digit standardized Mexican bank account number (CLABE). The settlement_account above is a documented test value that belongs to no real account. 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.transactional_profile.account_purpose is required. When you set it to other, also send account_purpose_details with a description of how the company uses the account.

A block labeled Response (abridged) shows only the fields that the step changes, not the whole object. The full response also returns data, which echoes the step data you sent, except legal_representatives and shareholders. Each legal representative and shareholder also carries the identity fields from the request. See The Onboarding object for the full shape. Three details apply in both countries:

submittable is false until every required field and document is in place.
documents lists each company document slot and its status, either missing or uploaded. Read this array to identify outstanding documents.
A legal_entity shareholder can include nested children.

Steps 3, 4, and 5 fill the slots.

Step 3: Upload the company documents

Upload one file to each company document slot in the documents array with PUT .../documents/{slot_key}. Send the file as multipart/form-data in the file field. The maximum file size is 20 MB. A slot accepts either one file or multiple files. On a single-file slot, PUT replaces the existing file. On a multi-file slot, PUT adds a file and keeps the files already uploaded. See Manage files in a slot.

Chile
Mexico

Every Chilean company slot accepts application/pdf only. The slots you must fill depend on the data you sent in Step 2:

`slot_key`	Opens when	Required to submit	Files
`e_rut`	Always	Yes	One
`activities_start_certificate`	`incorporation_type` is `traditional`	Yes	One
`good_standing_certificate`	`incorporation_type` is `traditional`	Yes	One
`current_shareholders_certificate`	`incorporation_type` is `one_day_company`	Yes	One
`power_of_attorney`	Always	No	One
`incorporation_deed`	Always	Yes	One
`incorporation_amendments`	Always	No	Multiple
`uaf_registration_certificate`	Always	If `uaf_obligated` is `true`	One
`plaft_manual_and_policies`	Always	If `uaf_obligated` is `true`	Multiple

A PUT to a slot the onboarding does not open, such as current_shareholders_certificate on a traditional company, returns 422 Unprocessable Entity with the code unknown_document_slot.

curl --request PUT \
     --url https://api.fintoc.com/v2/entities/ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN/onboardings/onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K/documents/e_rut \
     --header 'Authorization: YOUR_TEST_SECRET_KEY' \
     --header 'accept: application/json' \
     --form 'file=@e_rut.pdf'

{
  "id": "onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K",
  "object": "onboarding",
  "documents": [
    {
      "id": "onbdoc_3cpDyiBmvdBJ8a0aJc8Vo2gO",
      "slot_key": "e_rut",
      "status": "uploaded",
      "filename": "e_rut.pdf",
      "uploaded_at": "2026-01-15T14:30:00Z"
    }
  ]
}

Repeat for each remaining required slot. Add the files for incorporation_amendments and plaft_manual_and_policies one at a time, as Manage files in a slot shows.

Every Mexican company slot accepts one file and is required to submit. Each slot accepts its own content types:

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

curl --request PUT \
     --url https://api.fintoc.com/v2/entities/ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN/onboardings/onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K/documents/tax_registration_certificate \
     --header 'Authorization: YOUR_TEST_SECRET_KEY' \
     --header 'accept: application/json' \
     --form 'file=@tax_registration_certificate.pdf'

{
  "id": "onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K",
  "object": "onboarding",
  "documents": [
    {
      "id": "onbdoc_3cpDyiBmvdBJ8a0aJc8Vo2gO",
      "slot_key": "tax_registration_certificate",
      "status": "uploaded",
      "filename": "tax_registration_certificate.pdf",
      "uploaded_at": "2026-01-15T14:30:00Z"
    }
  ]
}

Repeat for each remaining slot: settlement_bank_statement, proof_of_address, shareholder_structure, and articles_of_incorporation.

A file whose content type the slot does not accept returns 422 Unprocessable Entity with the code unsupported_content_type. The error message lists the content types the slot accepts.

Manage files in a slot

The documents array returns one entry per uploaded file. Each uploaded entry carries its own id. A multi-file slot with three files appears three times in documents, once per file, with the same slot_key. A slot with no files appears once, with status set to missing and no id. To add a file to a multi-file slot, call POST .../documents/{slot_key} with the same multipart/form-data body as PUT. The example below uses incorporation_amendments, a multi-file slot of a Chilean onboarding that accepts application/pdf only. A Mexican account_holder onboarding has no multi-file slot:

curl --request POST \
     --url https://api.fintoc.com/v2/entities/ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN/onboardings/onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K/documents/incorporation_amendments \
     --header 'Authorization: YOUR_TEST_SECRET_KEY' \
     --header 'accept: application/json' \
     --form 'file=@incorporation_amendment_2025.pdf'

{
  "id": "onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K",
  "object": "onboarding",
  "documents": [
    {
      "id": "onbdoc_3cpDyiBmvdBJ8a0aJc8Vo2gO",
      "slot_key": "incorporation_amendments",
      "status": "uploaded",
      "filename": "incorporation_amendment_2024.pdf",
      "uploaded_at": "2026-01-15T14:30:00Z"
    },
    {
      "id": "onbdoc_4dqEzjCnweCK9b1bKd9Wp3hP",
      "slot_key": "incorporation_amendments",
      "status": "uploaded",
      "filename": "incorporation_amendment_2025.pdf",
      "uploaded_at": "2026-01-15T14:32:00Z"
    }
  ]
}

POST on a single-file slot returns 422 Unprocessable Entity with the code single_file_document_slot. Use PUT to replace the file in a single-file slot. To remove one file, call DELETE .../documents/{slot_key}/{document_id} with the file’s id from the documents array:

curl --request DELETE \
     --url https://api.fintoc.com/v2/entities/ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN/onboardings/onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K/documents/tax_registration_certificate/onbdoc_3cpDyiBmvdBJ8a0aJc8Vo2gO \
     --header 'Authorization: YOUR_TEST_SECRET_KEY' \
     --header 'accept: application/json'

{
  "id": "onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K",
  "object": "onboarding",
  "documents": [
    { "slot_key": "tax_registration_certificate", "status": "missing" }
  ]
}

The POST and DELETE calls return the updated onboarding. An id that does not belong to that slot returns 404 Not Found with the code missing_resource. Once you submit the onboarding, you can no longer add or remove files. To replace one file in a multi-file slot, call DELETE for that file and then POST the new file.

Step 4: Upload each legal representative’s documents

Each legal representative needs two documents. Use the legal representative id (onblr_...) from the Step 2 response, and pass the slot as the last path segment. The two slots depend on the country:

Chile
Mexico

`slot_key`	Accepted content types
`identification_front`	`application/pdf`, `image/jpeg`, `image/png`
`identification_back`	`application/pdf`, `image/jpeg`, `image/png`

Upload the front and the back of the identity document as two files. The certificate of authority (personería) is not a legal representative slot in Chile. Upload it to the company slot power_of_attorney in Step 3.

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

A slot that does not belong to the onboarding’s country returns 422 Unprocessable Entity with the code unknown_document_slot. The example uploads the Mexican identification slot. A Chilean onboarding uses the same path with identification_front or identification_back.

curl --request PUT \
     --url https://api.fintoc.com/v2/entities/ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN/onboardings/onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K/legal_representatives/onblr_0ujsswThIGTUYm2K8FjOOfXtY1K/documents/identification \
     --header 'Authorization: YOUR_TEST_SECRET_KEY' \
     --header 'accept: application/json' \
     --form 'file=@identification.pdf'

{
  "id": "onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K",
  "object": "onboarding",
  "legal_representatives": [
    {
      "id": "onblr_0ujsswThIGTUYm2K8FjOOfXtY1K",
      "object": "onboarding_legal_representative",
      "documents": [
        {
          "slot_key": "identification",
          "status": "uploaded",
          "filename": "identification.pdf",
          "uploaded_at": "2026-01-15T14:30:00Z"
        },
        { "slot_key": "power_of_attorney", "status": "missing" }
      ]
    }
  ]
}

Repeat for the second slot, and for every other legal representative you declared.

Step 5: Upload each shareholder’s document

Only Mexican onboardings require a document per shareholder. A Chilean onboarding skips this step: each Chilean shareholder has document set to null, and uploading to that shareholder returns 422 Unprocessable Entity with the code shareholder_document_not_required. In Mexico, each declared shareholder needs one document. Use the shareholder id (onbsh_...) from the Step 2 response. This path carries no slot, because Fintoc derives the slot from the shareholder’s type: identification for a natural_person, and articles_of_incorporation for a legal_entity. The slot accepts application/pdf, image/jpeg, and image/png.

curl --request PUT \
     --url https://api.fintoc.com/v2/entities/ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN/onboardings/onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K/shareholders/onbsh_0ujsswThIGTUYm2K8FjOOfXtY1K/document \
     --header 'Authorization: YOUR_TEST_SECRET_KEY' \
     --header 'accept: application/json' \
     --form 'file=@identification.pdf'

{
  "id": "onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K",
  "object": "onboarding",
  "shareholders": [
    {
      "id": "onbsh_0ujsswThIGTUYm2K8FjOOfXtY1K",
      "object": "onboarding_shareholder",
      "document": {
        "slot_key": "identification",
        "status": "uploaded",
        "filename": "identification.pdf",
        "uploaded_at": "2026-01-15T14:30:00Z"
      }
    }
  ]
}

Step 6: Submit for review

Once submittable is true, submit the onboarding for Fintoc to review. The onboarding must be in_progress and include every required field and document. After submission, the onboarding moves to submitted and you can no longer modify it.

curl --request POST \
     --url https://api.fintoc.com/v2/entities/ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN/onboardings/onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K/submit \
     --header 'Authorization: YOUR_TEST_SECRET_KEY' \
     --header 'accept: application/json'

{
  "id": "onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K",
  "object": "onboarding",
  "entity_id": "ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
  "type": "account_holder",
  "status": "submitted",
  "source": "api",
  "submittable": false,
  "submitted_at": "2026-01-15T15:00:00Z",
  "reviewed_at": null
}

submittable turns false once the onboarding is submitted, because a submitted onboarding can no longer accept changes. If a required field or document is missing, or the onboarding is no longer in_progress, the call returns a 422 Unprocessable Entity error. The param field names the slot or field that blocks the submission:

Error response

{
  "error": {
    "type": "invalid_request_error",
    "code": "required_document_missing",
    "message": "A required document is missing.",
    "param": "tax_registration_certificate",
    "doc_url": "https://docs.fintoc.com/reference/errors"
  }
}

A Chilean onboarding runs two more checks when you submit it:

Empresa en un Día status. When incorporation_type is one_day_company, Fintoc verifies that the company’s RUT is registered as an Empresa en un Día company. If the company is not, or Fintoc cannot confirm it, the call returns the code not_one_day_company with param set to incorporation_type. If the registry rejects the Entity’s RUT as invalid, the call returns the code invalid_rut with param set to rut.
Effective controller. At least one shareholder must have effective_controller set to true. Otherwise, the call returns the code effective_controller_required with param set to shareholders.

Step 7: Track the review

An onboarding moves through pending, in_progress, submitted, and then approved, rejected, or cancelled. Fintoc sends one of these webhook events when it approves or rejects the onboarding:

Event	Onboarding result
`entity.onboarding.approved`	The `Entity` passed review and is ready to transact.
`entity.onboarding.rejected`	The review failed. Contact Fintoc support to review the case.

Subscribe to these events in the dashboard under Developers → Webhooks. Each event carries the full reviewed onboarding, including the step data in data, the documents, and the declared legal_representatives and shareholders, so you do not need to call the API to read what Fintoc reviewed. See the Entity onboarding payload. You cannot retry a rejected onboarding through the API. Creating a new onboarding for the same Entity returns 409 Conflict, as Step 2 explains. Fintoc can review a rejected onboarding again and approve it, so your handler may receive entity.onboarding.approved after entity.onboarding.rejected for the same onboarding. See Retry after a rejection. If you don’t use webhooks, poll the onboarding directly:

curl --request GET \
     --url https://api.fintoc.com/v2/entities/ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN/onboardings/onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K \
     --header 'Authorization: YOUR_TEST_SECRET_KEY' \
     --header 'accept: application/json'

{
  "id": "onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K",
  "object": "onboarding",
  "entity_id": "ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
  "type": "account_holder",
  "status": "approved",
  "source": "api",
  "submittable": false,
  "submitted_at": "2026-01-15T15:00:00Z",
  "reviewed_at": "2026-01-16T09:00:00Z"
}

Check status to track the onboarding. Once status is approved, the Entity is ready to transact.

Step 8: Get the main account

When the onboarding reaches approved, Fintoc creates the Entity’s main Account with active status, together with its root account number. You do not need to create the main Account. Before approval, the Entity owns no Account, so no Account is ever pending. Both modes behave the same: an approved test onboarding creates a test main Account, and an approved live onboarding creates a live one. List the entity’s accounts to retrieve the main Account, then store the id (acc_...) and the root_account_number for that client. The account number format and the currency depend on the country:

Chile
Mexico

A Chilean main Account holds CLP, and its root_account_number is a Chilean bank account number.

curl --request GET \
     --url 'https://api.fintoc.com/v2/accounts?entity_id=ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN' \
     --header 'Authorization: YOUR_TEST_SECRET_KEY' \
     --header 'accept: application/json'

[
  {
    "id": "acc_8anBwgZktbZH6ydyHa6Tm0eM",
    "object": "account",
    "mode": "test",
    "status": "active",
    "description": null,
    "is_root": true,
    "root_account_number": "000000001",
    "root_account_number_id": "acno_0ujsswThIGTUYm2K8FjOOfXtY1K",
    "available_balance": 0,
    "currency": "CLP",
    "entity": {
      "id": "ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
      "holder_id": "777777777",
      "holder_name": "Test Entity 1",
      "is_root": false
    }
  }
]

A Mexican main Account holds MXN, and its root_account_number is an 18-digit standardized Mexican bank account number (CLABE).

curl --request GET \
     --url 'https://api.fintoc.com/v2/accounts?entity_id=ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN' \
     --header 'Authorization: YOUR_TEST_SECRET_KEY' \
     --header 'accept: application/json'

[
  {
    "id": "acc_8anBwgZktbZH6ydyHa6Tm0eM",
    "object": "account",
    "mode": "test",
    "status": "active",
    "description": null,
    "is_root": true,
    "root_account_number": "646180111800000004",
    "root_account_number_id": "acno_0ujsswThIGTUYm2K8FjOOfXtY1K",
    "available_balance": 0,
    "currency": "MXN",
    "entity": {
      "id": "ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
      "holder_id": "AAA010101AAA",
      "holder_name": "Test Entity 1",
      "is_root": false
    }
  }
]

Create additional accounts

The main Account is enough to send and receive money. Create more Account objects under the same Entity when the client needs separate balances, one per cost center. Pass the Entity ID as entity_id. Each Account has its own balance and root account number. Outbound transfer receipts show the client’s legal name. See Create more accounts for account creation details.

curl --request POST \
     --url https://api.fintoc.com/v2/accounts \
     --header 'Authorization: YOUR_TEST_SECRET_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "entity_id": "ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
  "description": "Client settlement account"
}
'

{
  "id": "acc_9bnCxhAlucAI7zezIb7Un1fN",
  "object": "account",
  "mode": "test",
  "status": "active",
  "description": "Client settlement account",
  "is_root": false,
  "root_account_number": "646180111800000017",
  "root_account_number_id": "acno_2fJkRm7tBvQxNzYpLc5WsHaDfT3",
  "available_balance": 0,
  "currency": "MXN",
  "entity": {
    "id": "ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
    "holder_name": "Test Entity 1",
    "holder_id": "AAA010101AAA"
  }
}

Test the integration

In test mode, run the full sequence above with your sk_test_... key. Create the Entity and onboarding, upload a sample file to every required slot, and submit the onboarding. Confirm that submittable turns true only after every required slot reports uploaded. Fintoc selects the mode from the API key you send, not from a request parameter. Onboarding request and response bodies do not carry a mode field. Onboardings are isolated per mode. A test key cannot read or act on a live onboarding, and a live key cannot read or act on a test onboarding. Both cases return 404 Not Found with the code missing_resource. Fintoc resolves entity_id in the API key’s mode, so a test key must reference an Entity that exists in test mode.

For a Chilean test onboarding, set incorporation_type to traditional. A one_day_company triggers the Empresa en un Día check from Step 6 against the Entity’s RUT, in test mode too, so a test RUT can block the submission.

Force a review outcome

In live mode, submitting starts a real Know Your Customer review that Fintoc’s compliance team decides. In test mode, submitting triggers a simulated review. Use the simulated review to exercise the approved and rejected paths without waiting. Fintoc decides the simulated review from a magic value in the step data you sent. This mechanism works like a test card number: a magic value forces a specific outcome. The field that carries the value depends on the country:

Chile
Mexico

`company_basics.fantasy_name`	Resulting `status`	Webhook event
`illegal`	`rejected`	`entity.onboarding.rejected`
`suspicious`	`submitted`	No event
Any other value, or no `fantasy_name`	`approved`	`entity.onboarding.approved`

`company_information.business_activity`	Resulting `status`	Webhook event
`illegal`	`rejected`	`entity.onboarding.rejected`
`suspicious`	`submitted`	No event
Any other value	`approved`	`entity.onboarding.approved`

The suspicious case leaves reviewed_at set to null. Use it to model an onboarding that is still under review, and check how your integration behaves while it waits for a decision. A test onboarding follows the same one-per-mode rule, so after a simulated rejection the Entity cannot start a new test onboarding. To run the flow again, create another Entity.

Fintoc compares the whole string exactly, including case and surrounding whitespace. ILLEGAL, Illegal, and "illegal " with a trailing space all fall through to approved.

Read the simulated result

POST .../submit returns 200 OK with status set to submitted and reviewed_at set to null, in both modes. The simulated review runs after the response, so do not treat the submit response as the review outcome. Poll the onboarding as shown in Step 7, or listen for the webhook event. Fintoc delivers entity.onboarding.approved and entity.onboarding.rejected to the webhook endpoints registered in test mode, and the event carries "mode": "test".

Webhook event (abridged)

{
  "id": "evt_2xK9mP4nQrStUvWxYz1234567",
  "object": "event",
  "type": "entity.onboarding.approved",
  "mode": "test",
  "created_at": "2026-01-16T09:00:00.000Z",
  "data": {
    "object": "onboarding",
    "object_name": "onboarding_process",
    "id": "onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K",
    "entity_id": "ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
    "entity": {
      "id": "ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
      "holder_id": "AAA010101AAA",
      "holder_name": "Test Entity 1",
      "nationality": "mx"
    },
    "type": "account_holder",
    "source": "api",
    "status": "approved",
    "submitted_at": "2026-01-15T15:00:00Z",
    "reviewed_at": "2026-01-16T09:00:00Z",
    "data": {
      "company_information": {
        "business_activity": "Servicios financieros",
        "settlement_account": "646969000000000000"
      }
    },
    "legal_representatives": [
      {
        "id": "onblr_0ujsswThIGTUYm2K8FjOOfXtY1K",
        "object": "onboarding_legal_representative",
        "first_name": "Test Customer 1",
        "last_name": "Customer"
      }
    ],
    "shareholders": [
      {
        "id": "onbsh_0ujsswThIGTUYm2K8FjOOfXtY1K",
        "object": "onboarding_shareholder",
        "type": "natural_person"
      }
    ],
    "documents": [
      {
        "id": "onbdoc_3cpDyiBmvdBJ8a0aJc8Vo2gO",
        "slot_key": "tax_registration_certificate",
        "status": "uploaded"
      }
    ]
  }
}

The event’s data carries the reviewed onboarding with the same fields as The Onboarding object, except submittable. It also keeps object_name and entity for backward compatibility. The example shows a Mexican onboarding and trims data, legal_representatives, shareholders, and documents. See the Entity onboarding payload for the full payload. The rejected event carries the same payload, with the event type set to entity.onboarding.rejected and data.status set to rejected.

What test mode does not simulate

In test mode, Fintoc reproduces the review outcome and the webhook, and nothing else in the compliance flow:

No rejection reason. A rejected onboarding exposes no field that explains the decision, in the API or in the webhook payload.
No emails. Fintoc sends no submission notification to the legal representatives in test mode.

What’s next

Account holder onboarding for the data schema and the document slots of the account_holder type, in Chile and Mexico.
Know Your Customer (KYC) requirements in Chile and KYC requirements in Mexico for the documents Fintoc’s compliance team reviews.
Create more accounts for an approved Entity.
Review The Onboarding object and the onboarding endpoints in the API reference.

Home

Resources

Payments

Business Accounts

Movements

Skeleton group medium 9

Onboard an entity by API

Before you start

Step 1: Create the entity

Step 2: Create the onboarding

Step 3: Upload the company documents

Manage files in a slot

Step 4: Upload each legal representative’s documents

Step 5: Upload each shareholder’s document

Step 6: Submit for review

Step 7: Track the review

Step 8: Get the main account

Create additional accounts

Test the integration

Force a review outcome

Read the simulated result

What test mode does not simulate

What’s next

Home

Resources

Payments

Business Accounts

Movements

Skeleton group medium 9

​Before you start

​Step 1: Create the entity

​Step 2: Create the onboarding

​Step 3: Upload the company documents

​Manage files in a slot

​Step 4: Upload each legal representative’s documents

​Step 5: Upload each shareholder’s document

​Step 6: Submit for review

​Step 7: Track the review

​Step 8: Get the main account

​Create additional accounts

​Test the integration

​Force a review outcome

​Read the simulated result

​What test mode does not simulate

​What’s next

Before you start

Step 1: Create the entity

Step 2: Create the onboarding

Step 3: Upload the company documents

Manage files in a slot

Step 4: Upload each legal representative’s documents

Step 5: Upload each shareholder’s document

Step 6: Submit for review

Step 7: Track the review

Step 8: Get the main account

Create additional accounts

Test the integration

Force a review outcome

Read the simulated result

What test mode does not simulate

What’s next