Getting started

Use the Niva API to create a business verification submission, upload its documents, run verification, and retrieve the results.

Before you begin

Create a private API key in Settings › API Keys in the Niva dashboard. Send it from your server in the apiKey header. See Authentication for public keys and submission tokens used in browser integrations.

Production: https://api.niva.co/v1.

Demo: https://api.niva-demo.com/v1.

Use credentials issued for the environment you are calling. Paths in these guides are relative to the base URL.

1. Create a submission

Select a market enabled on your account with country_code. Send the business's tax ID in tax_id_number:

Market	Tax ID
Mexico (`mx`)	RFC (Registro Federal de Contribuyentes)
Chile (`cl`)	RUT (Rol Único Tributario)
Colombia (`co`)	NIT (Número de Identificación Tributaria)
Brazil (`br`)	CNPJ (Cadastro Nacional da Pessoa Jurídica)

For example, Create new submission for a Mexican business:

Replace the sample data with the business you are verifying. The following are alternative request bodies for the other markets:

Chile

Colombia

Brazil

{
  "country_code": "cl",
  "tax_id_number": "76.134.941-4",
  "legal_name": "Comercial Los Andes SpA",
  "external_id": "los-andes-001"
}

tax_id_number is required in Chile, Colombia, and Brazil. In Mexico, provide tax_id_number, business_type, or both, and send an uppercase RFC without spaces or punctuation. The other markets accept the punctuation shown above. When business_type is omitted, it is inferred from the tax ID in Mexico, Chile, and Colombia. New Brazilian submissions use legal_entity; Chile currently supports legal entities only.

Always send country_code in a new integration. Existing accounts created before September 8, 2026, with Mexico enabled may omit it and receive mx; other accounts must provide it. The market cannot be changed after creation.

The response is 201 Created with a submission summary. Store its id (sub_…) for later calls. Your external_id must be unique within your account. Some endpoints also accept external_id; check each endpoint's path parameter description. Creating the submission leaves it pending and does not start verification.

2. Upload documents

Use Upload document for each document. Send country_code, document_type, and the appropriate document_subtype from Supported document types. The subtype can be omitted for photo_identification and address_proof, where Niva detects it.

Read validation_status and validation_errors in the response. The Uploading documents guide explains validation, recovery after a timeout, and document merging.

3. Run verification

After collecting the required documents, call Run business verification:

Replace sub_12345AbCdE with the ID returned by Create new submission. The submission must be pending or pending_rfi and have at least one document. Legal entities need a usable formation document; see Verifying a new business for market-specific requirements.

4. Retrieve the result

Listen for submission.status_updated webhooks, then call Get submission for the full result and Get submission checks for completed checks. A processing status means verification is still running. Country-specific output is described in Country-specific fields.

Handle errors

Check both the HTTP status and the response body. For example, a missing API key returns 401:

{"errors": ["401 Unauthorized"]}

A market that is not enabled for your account returns 422:

{
  "errors": [
    {"field": "country_code", "message": "is not supported"}
  ]
}

Each endpoint documents its other errors. Contact support@niva.co if you need help enabling a market or configuring your verification policy.

Getting started

Before you begin#

1. Create a submission#

2. Upload documents#

3. Run verification#