Create new submission

Creates a submission in one of your markets with status pending. Next, upload documents and call Run business verification.

Send country_code for a market enabled on your account. Accounts created before 2026-09-08 (UTC) with Mexico enabled may omit it to use mx; other accounts must send it.

Mexico (`mx`)

Send business_type, or a valid RFC (Registro Federal de Contribuyentes) in tax_id_number. Without business_type, a 12-character RFC selects legal_entity and a 13-character RFC selects sole_proprietor. The response uses persona_moral and persona_fisica, respectively.

Send RFCs in uppercase without punctuation. On create, an RFC is not validated when business_type is explicitly supplied.

Chile (`cl`)

Send tax_id_number as a RUT (Rol Único Tributario), including its check digit. business_type is inferred when omitted. Only legal entities are supported; sole_proprietor returns 422.

Colombia (`co`)

Send tax_id_number as a NIT (Número de Identificación Tributaria) or a sole proprietor's cédula. business_type is inferred when omitted. The verification digit is optional; when supplied, it must be correct.

Brazil (`br`)

Send tax_id_number as a CNPJ (Cadastro Nacional da Pessoa Jurídica), with valid check digits. Every Brazilian submission is a legal_entity, including individual business registrations.

Niva looks the CNPJ up in the registry of the Receita Federal (Brazil's federal tax authority) during the request and fills in the legal name, trade name, address, owners, and legal representatives. If the registry is unavailable or the CNPJ is not found, the request returns 500 and no submission is created.

The Brazilian sample CNPJ demonstrates valid formatting and check digits. For a live request, use the registered CNPJ of the business you are verifying; the registry lookup must succeed.

Your reference data

external_id must be unique within your account; Get submission accepts it in place of the submission ID. custom is stored as sent and returned in inputs.custom.

Validation errors

Common 422 errors include:

country_code: is required or is not supported.

tax_id_number: must be a valid tax ID number in cl and co, must be a valid CNPJ in br, or must be valid when business_type is missing in mx.

Sole proprietor is not supported in this country for Chile.

policy_id: policy not found.

external_id: has already been taken.

Request

Authorization

Add parameter in header

apiKey

Example:

apiKey: ********************

Header Params

Body Params application/json

Examples

MexicoChileColombiaBrazil

{
    "country_code": "mx",
    "tax_id_number": "NVA120409XD2",
    "legal_name": "Nueva Vista Alimentos S.A. de C.V.",
    "trade_name": "Nueva Vista",
    "address": "Av. Insurgentes Sur 1602, Crédito Constructor, Benito Juárez, 03940 Ciudad de México, CDMX",
    "website": "https://nuevavista.mx",
    "external_id": "acct-10293",
    "applicant": {
        "first_name": "José Luis",
        "last_name": "Saavedra Ruiz",
        "email": "jose.saavedra@nuevavista.mx",
        "phone": "+52 55 1234 5678"
    }
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢201Created

application/json

Success

Bodyapplication/json

Example

{
  "id": "sub_3ZMd9KJnvAdYt4mOyW7YQRAp",
  "token": "YOUR_SUBMISSION_TOKEN",
  "country_code": "mx",
  "status": "pending",
  "business_type": "persona_moral",
  "legal_name": "Nueva Vista Alimentos S.A. de C.V.",
  "tax_id_number": "NVA120409XD2",
  "tax_id_label": "rfc",
  "created_at": "2026-10-23T21:31:32.501Z",
  "updated_at": "2026-10-23T21:31:32.501Z",
  "external_id": "acct-10293",
  "policy_id": "pol_gMPYprwdJXy9CNezk6A93zEN",
  "dashboard_url": "https://app.niva.co/dashboard/submissions/sub_3ZMd9KJnvAdYt4mOyW7YQRAp/details"
}

🟠401Unauthorized

🟠422Unprocessable Content

🔴500Internal Server Error

Create new submission

Mexico (mx)#

Chile (cl)#

Colombia (co)#

Brazil (br)#

Your reference data#

Validation errors#