Designing an upload flow

The Document upload widget handles file selection, progress, and validation messages. Add the surrounding labels and guidance so the applicant knows what to upload and what to do next.

Explain each document

Give each upload field a visible heading and a short description of the document's purpose. Expand local document names the first time they appear: for example, a Mexican Constancia de Situación Fiscal (CSF) is a tax status certificate.

Requirements differ across Mexico (mx), Brazil (br), Chile (cl), and Colombia (co). Use Supported document types and your account's policy to decide which documents to request.

Show the file requirements

State that the default accepted formats are PDF, JPEG, and PNG, with a maximum file size of 100 MB. Explain any requirements for issue dates, complete pages, signatures, or both sides of an identity document. Match those instructions to your policy rather than applying one country's requirements to every applicant.

Place the field below its instructions

Use one <niva-document-input> per document kind. For example, a Chilean tax identification card:

The e-RUT is Chile's electronic Rol Único Tributario card. Replace the credentials and select the correct configuration for the applicant's market.

If you need several documents of the same kind, enable multiple. Split long forms into clear sections and leave enough room for the upload controls and validation messages on mobile devices.

Make progress and recovery clear

Keep the applicant on the page while a file is uploading or validating. Allow continuation after the required documents report valid or warning.

Explain warnings without presenting them as rejections. For incomplete, show which additional part is needed; for fail, ask for a corrected document.

Listen for error, invalid_token, and invalid_api_key. Authentication errors are separate events and are not sent to onError.

When a submission token expires, obtain a fresh token through your backend and replace the widget element. Updating the token attribute on an existing widget does not refresh its requests.

If a request fails, check the submission's documents before asking the applicant to upload the same file again.

See Document upload widget for event payloads, form validation, and token refresh details. Once collection is complete, your backend can start Run business verification.

Designing an upload flow

Explain each document#

Show the file requirements#

Place the field below its instructions#

Make progress and recovery clear#

Explain each document

Show the file requirements

Place the field below its instructions

Make progress and recovery clear