curl --request POST \
--url https://api.fintoc.com/v2/entities/{entity_id}/onboardings \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"type": "account_holder",
"data": {
"company_information": {
"incorporation_date": "2020-01-15",
"business_activity": "Servicios financieros",
"fiscal_address": "Av. Reforma 123, CDMX",
"business_address": "Av. Insurgentes 456, CDMX",
"settlement_account": "646180357600000013",
"phone": "+521111111111"
},
"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",
"nationality": "mx",
"percentage": 60,
"holder_id": "AAAA010101AAA"
},
{
"type": "legal_entity",
"name": "Acme SA",
"nationality": "mx",
"percentage": 40,
"holder_id": "AAA010101AAA",
"children": [
{
"type": "natural_person",
"name": "Test Customer 3",
"last_name": "Customer",
"nationality": "mx",
"percentage": 80,
"holder_id": "AAAA010101AAA"
}
]
}
]
}
}
'{
"id": "onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K",
"object": "onboarding",
"entity_id": "ent_8anBwgZktbZH6ydyHa6Tm0eM",
"type": "account_holder",
"status": "in_progress",
"source": "api",
"submitted_at": null,
"reviewed_at": null,
"submittable": false,
"data": {
"company_information": {
"incorporation_date": "2020-01-15T00:00:00.000Z",
"business_activity": "Servicios financieros",
"fiscal_address": "Av. Reforma 123, CDMX",
"business_address": "Av. Insurgentes 456, CDMX",
"settlement_account": "000000000000000000",
"phone": "+521111111111"
},
"transactional_profile": {
"resource_origins": [
"trusts",
"investments"
],
"monthly_amount_range": "1_500000",
"monthly_operations_range": "1_15000",
"declaration_accepted": true
}
},
"legal_representatives": [
{
"id": "onblr_0ujsswThIGTUYm2K8FjOOfXtY1K",
"object": "onboarding_legal_representative",
"first_name": "Test Customer 1",
"last_name": "Customer",
"email": "rep@example.com",
"nationality": "mx",
"identification_number": "AAAA010101HDFAAA01",
"position": "Director General",
"documents": [
{
"slot_key": "identification",
"status": "missing"
},
{
"slot_key": "power_of_attorney",
"status": "missing"
}
]
}
],
"shareholders": [
{
"id": "onbsh_0ujsswThIGTUYm2K8FjOOfXtY1K",
"object": "onboarding_shareholder",
"type": "natural_person",
"name": "Test Customer 2",
"last_name": "Customer",
"percentage": 60,
"holder_id": "AAAA010101AAA",
"parent_id": null,
"document": {
"slot_key": "identification",
"status": "missing"
}
},
{
"id": "onbsh_8anBwgZktbZH6ydyHa6Tm0eM",
"object": "onboarding_shareholder",
"type": "legal_entity",
"name": "Acme SA",
"percentage": 40,
"holder_id": "AAA010101AAA",
"parent_id": null,
"document": {
"slot_key": "articles_of_incorporation",
"status": "missing"
}
},
{
"id": "onbsh_9bnCxhAlucAI7zezIb7Un1fN",
"object": "onboarding_shareholder",
"type": "natural_person",
"name": "Test Customer 3",
"last_name": "Customer",
"percentage": 80,
"holder_id": "AAAA010101AAA",
"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"
}
]
}{
"error": {
"type": "invalid_request_error",
"code": "invalid_shareholder_structure",
"reason": "shareholder_participation_exceeded",
"message": "participation sum for this level exceeds 100",
"param": "shareholders",
"doc_url": "https://docs.fintoc.com/reference/errors"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "Invalid API Key: invalid-*oken"
}
}{
"error": {
"type": "invalid_request_error",
"code": "missing_resource",
"param": "entity_id",
"message": "No such entity: ent_8anBwgZktbZH6ydyHa6Tm0eM",
"doc_url": "https://docs.fintoc.com/reference/errors"
}
}{
"error": {
"type": "conflicted_request_error",
"code": "conflicted_request",
"message": "An onboarding already exists for this entity",
"active_onboarding_id": "onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K"
}
}{
"error": {
"type": "invalid_request_error",
"code": "country_not_supported",
"message": "Onboarding is not available for foreign entities"
}
}Create an onboarding
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.
curl --request POST \
--url https://api.fintoc.com/v2/entities/{entity_id}/onboardings \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"type": "account_holder",
"data": {
"company_information": {
"incorporation_date": "2020-01-15",
"business_activity": "Servicios financieros",
"fiscal_address": "Av. Reforma 123, CDMX",
"business_address": "Av. Insurgentes 456, CDMX",
"settlement_account": "646180357600000013",
"phone": "+521111111111"
},
"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",
"nationality": "mx",
"percentage": 60,
"holder_id": "AAAA010101AAA"
},
{
"type": "legal_entity",
"name": "Acme SA",
"nationality": "mx",
"percentage": 40,
"holder_id": "AAA010101AAA",
"children": [
{
"type": "natural_person",
"name": "Test Customer 3",
"last_name": "Customer",
"nationality": "mx",
"percentage": 80,
"holder_id": "AAAA010101AAA"
}
]
}
]
}
}
'{
"id": "onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K",
"object": "onboarding",
"entity_id": "ent_8anBwgZktbZH6ydyHa6Tm0eM",
"type": "account_holder",
"status": "in_progress",
"source": "api",
"submitted_at": null,
"reviewed_at": null,
"submittable": false,
"data": {
"company_information": {
"incorporation_date": "2020-01-15T00:00:00.000Z",
"business_activity": "Servicios financieros",
"fiscal_address": "Av. Reforma 123, CDMX",
"business_address": "Av. Insurgentes 456, CDMX",
"settlement_account": "000000000000000000",
"phone": "+521111111111"
},
"transactional_profile": {
"resource_origins": [
"trusts",
"investments"
],
"monthly_amount_range": "1_500000",
"monthly_operations_range": "1_15000",
"declaration_accepted": true
}
},
"legal_representatives": [
{
"id": "onblr_0ujsswThIGTUYm2K8FjOOfXtY1K",
"object": "onboarding_legal_representative",
"first_name": "Test Customer 1",
"last_name": "Customer",
"email": "rep@example.com",
"nationality": "mx",
"identification_number": "AAAA010101HDFAAA01",
"position": "Director General",
"documents": [
{
"slot_key": "identification",
"status": "missing"
},
{
"slot_key": "power_of_attorney",
"status": "missing"
}
]
}
],
"shareholders": [
{
"id": "onbsh_0ujsswThIGTUYm2K8FjOOfXtY1K",
"object": "onboarding_shareholder",
"type": "natural_person",
"name": "Test Customer 2",
"last_name": "Customer",
"percentage": 60,
"holder_id": "AAAA010101AAA",
"parent_id": null,
"document": {
"slot_key": "identification",
"status": "missing"
}
},
{
"id": "onbsh_8anBwgZktbZH6ydyHa6Tm0eM",
"object": "onboarding_shareholder",
"type": "legal_entity",
"name": "Acme SA",
"percentage": 40,
"holder_id": "AAA010101AAA",
"parent_id": null,
"document": {
"slot_key": "articles_of_incorporation",
"status": "missing"
}
},
{
"id": "onbsh_9bnCxhAlucAI7zezIb7Un1fN",
"object": "onboarding_shareholder",
"type": "natural_person",
"name": "Test Customer 3",
"last_name": "Customer",
"percentage": 80,
"holder_id": "AAAA010101AAA",
"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"
}
]
}{
"error": {
"type": "invalid_request_error",
"code": "invalid_shareholder_structure",
"reason": "shareholder_participation_exceeded",
"message": "participation sum for this level exceeds 100",
"param": "shareholders",
"doc_url": "https://docs.fintoc.com/reference/errors"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "Invalid API Key: invalid-*oken"
}
}{
"error": {
"type": "invalid_request_error",
"code": "missing_resource",
"param": "entity_id",
"message": "No such entity: ent_8anBwgZktbZH6ydyHa6Tm0eM",
"doc_url": "https://docs.fintoc.com/reference/errors"
}
}{
"error": {
"type": "conflicted_request_error",
"code": "conflicted_request",
"message": "An onboarding already exists for this entity",
"active_onboarding_id": "onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K"
}
}{
"error": {
"type": "invalid_request_error",
"code": "country_not_supported",
"message": "Onboarding is not available for foreign entities"
}
}Autorizaciones
Parámetros de ruta
Unique identifier for the entity, such as ent_8anBwgZktbZH6ydyHa6Tm0eM.
Cuerpo
Type of onboarding to create: account_holder or settlement_recipient.
account_holder, settlement_recipient Onboarding data for the entity, grouped into company_information, legal_representatives, transactional_profile, and shareholders.
Respuesta
The API starts the onboarding process from the provided data and returns the created onboarding.
Unique identifier of the onboarding.
"onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K"
Type of the object. Always onboarding.
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.
{
"company_information": {
"incorporation_date": "2020-01-15T00:00:00.000Z",
"business_activity": "Servicios financieros",
"fiscal_address": "Av. Reforma 123, CDMX",
"business_address": "Av. Insurgentes 456, CDMX",
"settlement_account": "000000000000000000",
"phone": "+521111111111"
},
"transactional_profile": {
"resource_origins": ["trusts", "investments"],
"monthly_amount_range": "1_500000",
"monthly_operations_range": "1_15000",
"declaration_accepted": true
}
}
Document slots for the onboarding, with their upload status.
Show child attributes
Show child attributes
Identifier of the entity this onboarding belongs to. null if not associated with an entity.
"ent_8anBwgZktbZH6ydyHa6Tm0eM"
Legal representatives declared for the entity.
Show child attributes
Show child attributes
ISO 8601 datetime, in UTC, of when the onboarding was reviewed. null until it is reviewed.
"2026-01-16T09:00:00Z"
Shareholders declared for the entity.
Show child attributes
Show child attributes
Channel the onboarding is being completed through. One of api or dashboard.
api, dashboard "api"
Current status of the onboarding. One of pending, in_progress, submitted, approved, rejected or cancelled.
pending, in_progress, submitted, approved, rejected, cancelled "pending"
Whether the onboarding has every required field and document completed and can be submitted for review.
false
ISO 8601 datetime, in UTC, of when the onboarding was submitted for review. null until it is submitted.
"2026-01-15T14:30:00Z"
Type of the onboarding: account_holder or settlement_recipient.
account_holder, settlement_recipient "account_holder"
¿Esta página le ayudó?