Home
Home
  1. Guides
  • Getting started
  • Authentication
  • Webhooks
  • Embeddable widgets
    • Overview
    • Document upload widget
      • Designing an upload flow
  • Guides
    • Verifying a new business
    • Verifying bank accounts
    • Uploading documents
    • Country-specific fields
    • Supported document types
  • API reference
    • Submissions
      • Reports
        • List available report templates
        • Download a report
      • Create new submission
      • Get submission
      • Update submission
      • Update submission status
      • Run a submission pre-flight check
      • Run business verification
      • Get submission checks
      • Delete submission
      • List submissions
    • Documents
      • Public documents API
        • List documents (public)
        • Upload document (public)
        • Get document (public)
        • Delete document (public)
        • Download document file (public)
        • Rerun validations (public)
      • List documents
      • Upload document
      • Get document
      • Delete document
      • Download document file
      • Rerun validations
    • RPC search
      • RPC search
      • Get company with ID
      • Look up company by RFC
      • Search companies by name
      • Download RPC document
    • Utilities
      • Matcher
        • Run name matching
  1. Guides

Verifying a new business

Verify a business by creating a submission, collecting its documents, and explicitly starting Know Your Business (KYB) verification.

1. Create a submission#

Call Create new submission from your backend. Select Mexico (mx), Chile (cl), Colombia (co), or Brazil (br) with country_code; the market must be enabled on your account. Use the request examples in Getting started.
Keep the returned submission id for subsequent calls. Its initial status is pending. Creating a submission does not start verification.
If you need to correct the business inputs before starting, use Update submission. Read its replacement rules first: omitted inputs are cleared, and custom data is not preserved by an update.

2. Upload and validate documents#

Call Upload document for each required document. Use multipart/form-data with:
file for one file, or files for several files that form one document. PDF, JPEG, and PNG are supported, up to 100 MB combined.
country_code and document_type for the document's country and category.
document_subtype for the market-specific kind. You may omit it for photo_identification and address_proof, where Niva detects it.
document_name when uploading an other document.
external_id to help find the document if your connection is interrupted.
Use the combinations in Supported document types. The document's country must match the submission's market, except that a Mexican submission accepts a photo_identification from another issuing country.
Upload waits for instant validation. Read validation_status and validation_errors in the response: valid and warning indicate a usable document; fail requires correction, and incomplete means another part is needed. Instant validation checks do not replace full business verification.
NOTE
An upload can fail with 500 if validation takes longer than about 100 seconds, even though the document was saved. Do not immediately upload it again. Use List documents with the external_id you sent, or wait for document.validated. See Uploading documents.

3. Run a pre-flight check (optional)#

Run a submission pre-flight check checks the collected documents together without starting full verification. It requires a pending or pending_rfi submission and a policy with instant submission checks enabled. Contact Niva if you need this enabled.
The synchronous response contains id, validation_status, and validation_errors. The status is valid, warning, fail, or validating. Correct any problems and repeat the check as needed. A successful pre-flight check does not start the submission automatically.

4. Run business verification#

Call Run business verification. The submission must be pending or pending_rfi and have at least one document. Additional formation requirements are:
MarketRequirement
MexicoA legal entity needs a usable acta constitutiva (incorporation deed).
Chile and ColombiaA legal entity needs a usable formation document from the submission's market.
BrazilLegal entities need a usable formation document from Brazil. Create new submission sets Brazilian businesses to legal_entity, including individual businesses registered with a CNPJ (Cadastro Nacional da Pessoa Jurídica).
If a requirement is missing, the endpoint returns 422 and explains what to correct. A successful request returns 201, changes the status to processing, and sends submission.status_updated.

5. Retrieve status and results#

Listen for submission.status_updated webhooks, or call Get submission. The first webhook after running a submission reports processing; it does not mean verification has finished.
StatusMeaning
pendingCreated and waiting to be run.
processingVerification or Niva's review is in progress.
needs_reviewReady for your review and decision.
pending_rfiMore information has been requested from the applicant.
approvedApproved.
rejectedRejected.
Once processing has finished, Get submission checks returns the completed checks with their outcome and message. It returns 400 while processing is still in progress or no processing result exists. See Country-specific fields for the business and people data returned for each market.
Use Update submission status to record your decision. To collect more documents and run a processed submission again, first set its status to pending_rfi.
Previous
Designing an upload flow
Next
Verifying bank accounts