Uploading documents

Upload documents to a submission, check the validation result, and keep your application's document list in sync with Niva. All paths below are relative to https://api.niva.co/v1; send your private API key in the apiKey header.

1. List documents

List documents returns the submission's current documents:

Optional filters are country_code, document_type, document_subtype, document_name, and external_id. Filters combine with AND. Omit filters you do not need: a blank value counts as a filter and can return an empty list.

2. Upload a document

Send multipart/form-data to Upload document. For example, upload a Mexican incorporation deed:

Replace the submission ID and file with your own. Use file for one file or files for multiple files that form one document. Multiple files are combined into one PDF. Accepted formats are PDF, JPEG, and PNG, up to 100 MB combined.

Choose country_code, document_type, and document_subtype from Supported document types. You may omit document_subtype for photo_identification and address_proof, where Niva detects it. The country must match the submission's market, except that Mexican submissions accept photo identification from another issuing country. For other / other, also send document_name.

Send only the fields you need. In particular, send exactly one of file or files; even a blank field counts as sent.

For a document belonging to a person or another business, optional validation_inputs[name] changes the name used for matching, and validation_inputs[entity_type] sets the expected holder to person or company.

NOTE

On Mexican submissions, photo identification is returned with document_subtype set to ine, including passports and residence permits. Match an upload to its result by id or external_id, rather than assuming the returned subtype will equal the one you sent.

3. Read the validation result

A successful upload returns 201 with the document. Read validation_status:

Status	Meaning
`valid`	The instant checks passed.
`warning`	Non-blocking concerns were found.
`fail`	A blocking check failed.
`incomplete`	The identity document needs its other side.
`validating`	Instant checks are still running.

validation_errors contains one entry per failed or warning check. A failure can be visible while other checks are still running. For example, this fragment shows a name mismatch:

{
  "validation_status": "fail",
  "validation_errors": [
    {
      "type": "fail",
      "error": "business_name_mismatch",
      "error_message": "The name on the document does not match the business.",
      "display_message": "The name on the document does not match your business. Please upload a document with the correct business."
    }
  ]
}

The type of an error is fail or warn. Treat error as its machine-readable code and display_message as text for the applicant. Wording depends on the check and language.

Uploads are kept by default, including failed documents. Set persist_invalid=false to remove a document when its blocking checks require it to be archived. The upload response still contains that document.

4. Recover an interrupted upload

Upload waits for instant validation. If it takes longer than about 100 seconds, the request can return 500 after the document has been saved; validation continues. A network error can also prevent you from receiving the response.

Before retrying an upload, use List documents with the external_id you sent:

Document external_id values are not required to be unique and do not make uploads idempotent. Re-uploading the same request can create another document.

Once you have its id, use Get document for the current validation result and extracted data. You can also listen for document.created and document.validated; see Webhooks.

5. Correct or remove a document

For corrected custom validation data, use Rerun validations. To replace a file, upload the corrected document and remove the old one with Delete document. There is no endpoint for replacing an uploaded file in place.

Deletion is allowed only while the submission is pending or pending_rfi; otherwise it returns 409. Removing a document sends document.deleted.

Handle document merging

Some uploads contain separate parts of the same document. For example, when configured for your account, Niva can combine an incorporation deed with its registration receipt. Contact support@niva.co about enabling corporate document merging.

A parent document is the combined document. Its merged_documents array identifies the original files. After a merge, List documents returns the parent in place of the originals.

If an upload response has a non-null parent_document_id, fetch that parent with Get document. The parent's response includes a fragment like:

{
  "merged_documents": [
    {"id": "doc_xYzEa982Abe", "name": "incorporation-deed.pdf", "size": 1245184},
    {"id": "doc_bC9pQ3rStV7", "name": "registration-receipt.pdf", "size": 803392}
  ]
}

Refresh your displayed document list after an upload. Replace merged originals with their parent so the applicant does not see duplicates or outdated validation results. For access to an original file, pass its merged_documents[].id to Download document file.

Uploading documents

1. List documents#

2. Upload a document#

3. Read the validation result#

4. Recover an interrupted upload#

5. Correct or remove a document#