26.R6 adds a callback event, ATTACHMENT_VALIDATION_RESULT, subscribed to like any other event. It fires once per signer per transaction, once that signer's upload step is complete and every extraction for their files has reached an outcome. Its message is FINISHED when every file's extraction completed, or FAILED when at least one did not; sessionUser identifies the signer and packageId the transaction. The event announces that results are ready and carries no per-file detail — on receiving it, read the verifications endpoint. It removes the need to re-read the endpoint on a timer.
Error and status reference
extractionStatus
Value | Meaning |
|---|---|
COMPLETED | Extraction ran and produced results. extractedFields and verificationCheckResults are populated |
NOT_PERFORMED | Extraction has not run, or was never attempted. Check reasonCode for why |
FAILED | Extraction was attempted and errored |
reasonCode
Value | Cause | What to do |
|---|---|---|
null with extractionStatus: NOT_PERFORMED | Extraction was never requested for this file, was skipped because the detected type did not match, has not completed yet, or could not be submitted or read because the validation service was unreachable. | Work through the decision tree below. Only its last branch is worth waiting on |
EXTRACTION_NOT_ENABLED | The requirement asked for extraction, but the account feature Attachment Data Extraction was off when the file was uploaded. Normally prevented when the role is created; it can occur if the feature is turned off afterwards. A requirement that simply does not have extractionEnabled set produces a null reason code, not this one | Configuration, not a failure. Confirm the account feature, then have the signer replace the file |
CLASSIFICATION_UNKNOWN | The document could not be identified as any supported type | The signer likely uploaded the wrong thing, or an unsupported document. Human review |
CLASSIFICATION_UNSUPPORTED_TYPE | The document was identified, but that type does not support field extraction | Every supported document type supports extraction. Reserved for future types |
CLASSIFICATION_QUALITY_WARNING | Two causes, told apart by classificationResult.failed. true: the file was rejected before classification — unreadable, wrong format, or out of size bounds — and classificationResult.errorCode names the problem. false: classification succeeded but with confidenceLevel MEDIUM or LOW, and the validation service declined to extract; documentType still shows what was detected | Ask the signer for a better copy. If failed is false and documentType is the type you requested, the signer very likely sent the right document; a clearer copy may let it be recognised |
EXTRACTION_ERROR | Extraction was attempted and errored. Always paired with extractionStatus: FAILED | Terminal for this file; re-reading will not change it. See What can and cannot be retried below |
Resolving a null reason code. Use the fields that are present to rule out the terminal causes before waiting on anything. classificationResult.failed never accompanies a null reason code — a failed classification always reports CLASSIFICATION_QUALITY_WARNING — so the tree starts from a successful classification:
classificationResultisnull— the stored classification could not be read, and extraction never ran. Terminal.The requirement did not have
extractionEnabled: true— extraction was never requested. Terminal, and expected.classificationResult.documentTypeis not theattachmentTypeyou requested — the detected type did not match, and extraction was never submitted. Terminal. (A correct type detected atMEDIUMorLOWconfidence does not reach this tree: it reportsCLASSIFICATION_QUALITY_WARNING.)Otherwise extraction was requested and no result is available yet: it is still running, it was refused at submission (for example the 1,024 px minimum for the six high-detail types), or the validation service could not be reached. These are not distinguished. Re-read this endpoint at intervals with backoff, and after a bounded time of your choosing treat the extraction result as unavailable for this file.
What can and cannot be retried. OneSpan Sign runs classification and extraction once per file, at upload, and neither retries them nor exposes a way to re-trigger them. Re-reading this endpoint only picks up an extraction that is still in progress — branch 4 above. EXTRACTION_ERROR, and a classificationResult.errorCode of upstream_service_error, are stored outcomes for that file and will not change on re-read; the only recovery is for the signer to replace the file, which runs validation again from the start. If either recurs across many files, the validation service is degraded — contact OneSpan support.
Distinguish configuration from failure. EXTRACTION_NOT_ENABLED means the feature was not turned on — nothing went wrong. Every other reason code describes something that happened to the document.
Limits you can check before uploading
The limits below belong to the validation service, and are separate from OneSpan Sign's own attachment upload limits (about 16 MB, and the file types allowed on the account). Exceeding the upload limits rejects the upload. Exceeding the limits below does not — the upload succeeds and classification fails with the error code shown. Checking them on the client avoids those errors entirely.
Limit | Value | Error code if exceeded |
|---|---|---|
Accepted formats | PDF (application/pdf), Word (application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document), JPEG, PNG, TIFF, BMP, GIF. The type is determined from the file's content and name, not from a declared MIME type | unsupported_content_type |
Minimum file size | 1,024 bytes | file_too_small |
Maximum file size | 10,485,760 bytes (10 MiB) — lower than the 16 MB upload limit | file_too_large |
Minimum image dimensions | 200 × 200 px, for an image upload and for each of the first two pages of a PDF or Word file | image_resolution_too_low |
Maximum image dimensions | None. Images over 1,568 px on the longest side are downscaled | — |
Extraction applies a stricter minimum for six document types. T4_SLIP_CA, AUTO_INSURANCE_CERTIFICATE, PROPERTY_INSURANCE, LIFE_INSURANCE_POLICY, VEHICLE_REGISTRATION and EMPLOYMENT_LETTER require 1,024 × 1,024 px when extraction runs. A file between 200 and 1,024 px passes classification, then extraction is refused before it starts and nothing is recorded — the file reports extractionStatus: NOT_PERFORMED with reasonCode: null. If extraction is on for one of these types, enforce 1,024 px on the client.
The remaining image checks — image_too_blurry, image_too_dark, image_low_contrast, image_glare_detected — measure the pixels and cannot be pre-validated by size or type. Blur and darkness apply to every input; contrast and glare apply only to photo uploads (JPEG, PNG, TIFF, BMP, GIF), never to PDF or Word pages. A born-digital PDF containing no images skips them entirely. For photos, guide the signer to a flat, evenly lit, in-focus capture without flash reflection.
classificationResult.errorCode
Populated only when classificationResult.failed is true, and only with one of the values below. These are translation keys, all prefixed esl.error.attachment_verification.
Key suffix | Cause |
|---|---|
image_resolution_too_low | Below 200 × 200 px (1,024 px for the six high-detail types at extraction) |
image_too_blurry | The image is out of focus |
image_low_contrast | The image has insufficient contrast |
image_glare_detected | Glare obscures the document |
image_too_dark | The image is underexposed |
document_corrupted | The file could not be decoded as an image or document |
file_too_large | Over 10,485,760 bytes |
file_too_small | Under 1,024 bytes |
unsupported_content_type | Not one of the accepted formats listed above |
upstream_service_error | The validation service reported a problem with no mapping here — an empty file, a missing filename or content type, or an image that could not be processed. Stored for the file and unchanged on re-read — see What can and cannot be retried above |
On the upload response. The signer's client receives the same keys immediately, as classificationErrorCode on each file in the response to the attachment upload or replace call, so that it can display an appropriate message. That response can additionally carry one key that never appears on classificationResult.errorCode: type_mismatch — the detected type does not match the requested type. A file carries at most one key there; a quality problem takes precedence over a mismatch. On the verifications endpoint a mismatch is expressed by typeMatch and documentType instead. The upload response also carries verificationResultUuid, the same value as classificationResult.documentUuid.