Document upload widget
<niva-document-input> to collect a document and show its validation result. Start with Overview to load the script, create a submission on your backend, and obtain a public API key and submission token.Basic usage
apiKey and externalId; public-token, submission-token, and external_id are not widget attributes.Choose the document type
mx) and the other markets.documentType to the specific document identifier and omit documentSubtype:| Document | documentType |
|---|---|
| Incorporation deed | acta_constitutiva |
| Shareholders' meeting minutes | acta_asamblea |
| Power of attorney | poderes |
| Tax status certificate | csf |
| Photo identification | ine |
| Proof of address | address_proof |
| Bank statement | bank_statement |
| Another document | other, with documentName |
br), Chile (cl), and Colombia (co), set documentType and documentSubtype to the market's document_type and document_subtype from Supported document types. You can omit the subtype for photo identification and proof of address when the document should be detected automatically.multiple to accept multiple documents of the same kind.Component attributes
apiKey: Required string. Your public API key.token: Required string. The submission token, valid for 24 hours after issue.documentType: Required string. The document identifier described above.documentSubtype: String. The market-specific subtype outside Mexico; see Choose the document type.countryCode: Optional string. The document's country code; defaults to the submission's market.documentName: String. A descriptive name when collecting an other document.name: Optional string. Field name when the widget is inside a form.externalId: Optional string. Your reference for the uploaded document.validations: Optional JSON object. Custom validation data; see Custom validations.required: Boolean attribute. Marks the field as required when you call checkValidity(). See Form submission.disabled: Boolean attribute. Disables interaction.multiple: Boolean attribute. Allows multiple documents of the configured kind.locale: Optional string. en (default) or es. Other locales are not supported.Validation states
valid and warning trigger success; a warning is displayed but the document is accepted. incomplete asks the user for the missing part, such as the other side of an identity document. fail reports a blocking problem. Upload or network errors require recovery before proceeding.Handle events
event.detail.widget-initialized: Existing documents were loaded. Detail: { documentType, files }. It does not fire when the submission has no matching documents.upload-started: A selected file passed local type and size checks. Detail: { file }.success: Validation returned valid or warning. Detail: { file }.delete-success: A document was removed. Detail includes key: "deletion_success" and file.error: An upload, validation, loading, or deletion problem. Detail includes key and message, and may include file, error, or response.invalid_token: The API rejected the submission token. This replaces the error event for that response.invalid_api_key: The API rejected the public API key. This replaces the error event for that response.widget.onSuccess or widget.onError to callback functions. onError runs only for the error event; handle authentication events separately.error event's detail key identifies the problem:initialization_failed: Existing documents could not be loaded.upload_error: Uploading or retrieving a validation result failed.document_validation_failed: Local file validation or a document check failed. For a local rejection, the file's validation_error.error identifies file_size_too_big or unsupported_file_type.document_incomplete: Another part of the document is needed.validation_timeout: A document remained in validation beyond the widget's polling limit.deletion_failed: A document could not be removed.invalid_token, request a fresh token from your backend using Get submission, then replace the widget element with a new one configured with that token. Changing token on an already connected widget does not update its requests.Read a file result
{
"id": "doc_xYzEa982Abe",
"name": "tax-certificate.pdf",
"size": 1024000,
"type": "application/pdf",
"status": "valid",
"url": "TEMPORARY_DOWNLOAD_URL",
"validation_error": null
}id is unavailable before a document is created. type can be null for previously uploaded documents. validation_error is null or an object with error and error_message. Treat url as a temporary link because it depends on the submission token.Form submission
value is a document ID, or an array of IDs when multiple is enabled. Read validation results before allowing the applicant to continue. required alone does not initialize browser validation; call checkValidity() from your submit handler. A document ID alone does not prove that validation passed.required on that widget and provide a visible instruction explaining that an accepted document is needed. Recheck the submission on your backend before running verification.Custom validations
validations to compare a document against a specific person or company instead of the submission's default name:name affects name-matching checks. entity_type is person or company and affects entity-type checks. These values only affect checks enabled for the document by your account's policy; they do not add a new check.