Upload document (public)

Production

https://api.niva.co/v1

POST

/public/submissions/{submission_token}/documents

Uploads a document from the browser, e.g. from your own upload UI. Send your public API key in the apiKey header and the submission's token in the path; see Public Documents API. Otherwise this endpoint behaves exactly like its private counterpart.

Identify the document with country_code, document_type and document_subtype (pairs per market under Supported document types; the subtype may be omitted for photo_identification and address_proof). Send exactly one of file or files (PDF, JPG or PNG, 100 MB in total). Niva validates the document before responding; see Upload document for the validation rules, custom validation inputs, the timeout behaviour and the 422 messages.

TIP

Send only the fields you need: a blank field counts as sent.

Request

Authorization

Add parameter in header

apiKey

Example:

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

Path Params

Header Params

Body Params multipart/form-data

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location 'https://api.niva.co/v1/public/submissions/YOUR_SUBMISSION_TOKEN/documents' \
--header 'Accept-Language: en' \
--header 'apiKey: <api-key>' \
--form 'document_type="formation"' \
--form 'document_subtype="acta_constitutiva"' \
--form 'country_code="mx"' \
--form 'file=@"acta_constitutiva.pdf"'

Responses

🟢201Created

application/json

Success

Bodyapplication/json

Examples

Valid documentDocument with a warning

{
  "id": "doc_MAXm5v0B7kZVHorQL8YjV2y9",
  "submission_id": "sub_3ZMd9KJnvAdYt4mOyW7YQRAp",
  "validation_status": "valid",
  "country_code": "mx",
  "document_type": "formation",
  "document_subtype": "acta_constitutiva",
  "uploaded_at": "2026-10-23T21:31:32.588Z",
  "validation_errors": [],
  "source": "user",
  "external_id": "acta-001",
  "document_name": null,
  "file": {
    "name": "acta_constitutiva.pdf",
    "byte_size": 482113
  },
  "data": {
    "business": {
      "entity_type": null,
      "legal_name": "Nueva Vista Alimentos S.A. de C.V.",
      "previous_legal_names": [],
      "merged_company_legal_names": [],
      "incorporation_date": null
    },
    "document": {
      "document_type": "acta_constitutiva",
      "date_of_deed": "2012-04-09",
      "boleta": {
        "is_present": true,
        "entry_number": "N-2012012345"
      }
    },
    "officers": null
  },
  "parent_document_id": null,
  "merged_documents": []
}

🟠401Unauthorized

🟠404Not Found

🟠422Unprocessable Content

🔴500Internal Server Error

List documents (public)

Get document (public)