Requesting NIGO Results

Which checks run, and against which fields, depends entirely on the document type:

Requesting validation

Both settings live on an attachment requirement, which is nested inside a role. Set them when you create or update the role, or when you create the package.

{
  "id": "role1",
  "type": "SIGNER",
  "signers": [
    { "email": "jane@example.com", "firstName": "Jane", "lastName": "Doe" }
  ],
  "attachmentRequirements": [
    {
      "id": "attachment-1",
      "name": "Proof of address",
      "description": "Upload a recent bank statement",
      "required": true,
      "attachmentType": "BANK_STATEMENT",
      "extractionEnabled": true
    }
  ]
}

POST or PUT this to /aws/rest/services/packages/{packageId}/roles[/{roleId}], or include it in the package creation payload.

extractionEnabled is a nullable boolean: null and false are equivalent, and both mean off. It is nullable so that an omitted field can never accidentally enable extraction — only an explicit true does.

Validation errors

The request is rejected if you ask for something the account is not entitled to:

Tamper detection has no per-requirement field. It is controlled solely by the account-level Document Authenticity setting, and applies to every eligible attachment on the account.

Retrieving results

GET /aws/rest/services/packages/{packageId}/attachment/verifications

Note that the path segment is attachment, singular.

The response is a bare array, not an object with a named field. There is no pagination.

This endpoint requires transaction edit privileges — sender, owner or delegate. Signers receive 403. Validation results are not exposed anywhere in the signer-facing API.

Classification is synchronous; extraction is asynchronous. Classification completes during the upload, so classificationResult is available as soon as the upload returns. Extraction runs afterwards, and its result appears at this endpoint once it completes — until then the file's element reports extractionStatus: "NOT_PERFORMED" with a null reasonCode and no extractionResult. Results are assembled on each request: the extraction result is fetched from the validation service and the content checks are evaluated at that moment, so read this endpoint when you need current results rather than caching it.

Detecting completion

Extraction is asynchronous, no event announces its completion (see Callbacks and events), and PACKAGE_ATTACHMENT fires before it finishes — so a client that needs extraction results has to re-read this endpoint until each file reaches a final state.

This endpoint is not rate limited, so limit yourself. Every call fetches the current extraction result for every validated file on the transaction from the validation service and re-evaluates the content checks. Do not loop tightly. Recommended: start on the PACKAGE_ATTACHMENT callback (per upload) or on SIGNER_COMPLETE (once the signer is done), re-read no more than once every 10 seconds per transaction — one call covers all of the transaction's files — and stop after 5 minutes, treating any file still without a final state as unavailable. These are recommendations, not measured limits: there is no published bound on extraction time.

Decide per file, on each read:

If you only need the classification, there is nothing to wait for.

Response shape

Each array element:

classificationResult:

extractionResult:

Which extractionStatus and reasonCode to read. Both appear twice — on the array element and inside extractionResult. Read the element-level ones: they are always present. When extractionResult is non-null, its extractionStatus and reasonCode are identical to the element's (the element copies them from it), and its failed is simply extractionStatus not being COMPLETED. When extractionResult is null, the element-level fields are the only ones, and say why there is no result. One edge case: if the validation service ever reports a status this release does not know, the nested value is null and the element reports NOT_PERFORMED.

Null fields are present in the JSON, not omitted. Do not treat the presence of a key as evidence that it has a value. Conversely, new fields may be added in later releases — ignore keys you do not recognise.

Example — a successful result

[
  {
    "attachmentUuid": "attachment-1",
    "fileName": "statement-june",
    "fileId": "8842",
    "extension": "pdf",
    "classificationResult": {
      "documentUuid": "9f2c1d84-3b7e-4a15-9c2d-6e8f1a4b7c30",
      "documentType": "BANK_STATEMENT",
      "confidenceScore": 0.95,
      "confidenceLevel": "HIGH",
      "providerName": "bedrock",
      "failed": false,
      "errorCode": null,
      "failureMessage": null
    },
    "extractionResult": {
      "documentUuid": "9f2c1d84-3b7e-4a15-9c2d-6e8f1a4b7c30",
      "extractedFields": {
        "accountHolderName": "JANE DOE",
        "financialInstitutionName": "Bank of Example",
        "statementDate": "2026-06-30",
        "statementPeriodStart": "2026-06-01",
        "statementPeriodEnd": "2026-06-30"
      },
      "providerName": "bedrock",
      "verificationCheckResults": [
        {
          "ruleName": "data_completeness",
          "fields": [],
          "status": "PASS",
          "message": "esl.error.attachment_verification_check.data_completeness_pass"
        },
        {
          "ruleName": "date_validation",
          "fields": ["statementDate"],
          "status": "PASS",
          "message": "esl.error.attachment_verification_check.date_recent"
        }
      ],
      "extractionStatus": "COMPLETED",
      "reasonCode": null,
      "failureMessage": null,
      "preflight": {
        "checks": [
          {
            "check": "SOURCE",
            "status": "PASS",
            "messageKey": "esl.error.preflight_check.source_verified",
            "params": {}
          },
          {
            "check": "EDITS_AFTER_CREATION",
            "status": "PASS",
            "messageKey": "esl.error.preflight_check.no_edits_after_creation",
            "params": {}
          },
          {
            "check": "FILE_DATES",
            "status": "PASS",
            "messageKey": "esl.error.preflight_check.file_dates_consistent",
            "params": {}
          },
          {
            "check": "PERIOD_DATE",
            "status": "PASS",
            "messageKey": "esl.error.preflight_check.period_date_within",
            "params": {}
          }
        ],
        "verifiability": { "inputType": "VERIFIABLE_PDF" },
        "tier": "CLEAR"
      },
      "failed": false
    },
    "extractionStatus": "COMPLETED",
    "reasonCode": null,
    "typeMatch": true
  }
]

Example — the file could not be classified

[
  {
    "attachmentUuid": "attachment-1",
    "fileName": "photo",
    "fileId": "8843",
    "extension": "jpg",
    "classificationResult": {
      "documentUuid": "1a4b7c30-9f2c-4a15-8e6d-3b7e5c2d9f10",
      "documentType": null,
      "confidenceScore": 0.0,
      "confidenceLevel": null,
      "providerName": null,
      "failed": true,
      "errorCode": "esl.error.attachment_verification.image_too_blurry",
      "failureMessage": "Document is difficult to read"
    },
    "extractionResult": null,
    "extractionStatus": "NOT_PERFORMED",
    "reasonCode": "CLASSIFICATION_QUALITY_WARNING",
    "typeMatch": false
  }
]

Document types and extraction fields

The following document types are supported. The Extraction fields column lists every key that can appear in extractedFields for that type. Keys marked (date) are returned in ISO YYYY-MM-DD form; every other value is returned as printed on the document.

Two fields are constrained to a fixed set of values:

• utilityType — one of electric, gas, water, internet, mobile, other

• payFrequency — one of weekly, bi-weekly, monthly, undefined

taxYear is a plain string, not a date. It is returned as printed on the document.

Note that classification can report a document as an unrecognised type, in which case documentType is "UNKNOWN". UNKNOWN is not a valid attachmentType and cannot be requested.

Handling extracted fields

extractedFields is sparse. It contains only the keys that were actually found and legible. A field that was absent from the document, unreadable, or that the extractor declined to guess at is omitted from the map entirely — it is not returned as null or as an empty string.

This applies to every key, including the ones the checks require. Your code must handle any key being missing, and must not assume that every key listed for a document type will be present in every response.

All values are strings.

• Dates are normalized to ISO YYYY-MM-DD. This normalization is performed by the extractor and constrained by its output schema, but it is not re-validated afterwards. Treat a well-formed ISO date as the expected case, and handle a value that does not parse rather than assuming it will.

• Monetary amounts are returned exactly as printed — for example "65000.00", "$75,000 per year", or "120,000 00". They are not normalized to numbers. Parse them yourself, defensively.

• Everything else is returned as printed on the document.

Extracted data is produced by the validation service and surfaced through this endpoint. It is not editable through the API, and there is no endpoint to correct or override an extracted value.

Verification check results

extractionResult.verificationCheckResults is an array of check results, present only when extraction completed. Each element:

There are four checks. Which of them run, and against which fields, is determined entirely by the document type.

All message keys are prefixed esl.error.attachment_verification_check.

A missing or unparseable date always produces WARNING, never FAIL. Only a date that was read successfully and found to be out of range produces FAIL. Do not treat WARNING as a soft failure of the document — in most cases it means the check could not be performed.

Per-type configuration:

Note that data_completeness requires some fields the extractor treats as optional — payDate on a pay stub and totalIncome on a tax return are examples. A data_completeness failure naming those fields means they were not found on the document, not that something went wrong.

"No results" states

An empty result is never an error. 204 means nothing has been validated on this transaction, which is the normal state for a transaction that does not use the feature.

Reconcile this array against the files you know were uploaded. Every uploaded file is listed in attachmentRequirements[].files[] on the role. A file in that list but absent from this array was never validated — the service was unreachable when it was uploaded, or validation was not configured for its requirement at the time. Treat that as an explicit not validated state and surface it as such: re-reading this endpoint will not change it, and the only way to validate the file is for the signer to replace it. Do not confuse it with a file that is present with extractionStatus: NOT_PERFORMED and a null reasonCode — resolve that one with the decision tree under reasonCode.

Mark as Reviewed through the API

PUT    /aws/rest/services/packages/{packageId}/attachment/{attachmentId}/file/{fileId}/reviewed
DELETE /aws/rest/services/packages/{packageId}/attachment/{attachmentId}/file/{fileId}/reviewed

PUT marks the file as reviewed; DELETE undoes it. Neither takes a request body. Both return 200 with the updated AttachmentFile, and both require transaction edit privileges. A fileId that does not belong to the given attachmentId returns 404 error.validation.AttachmentFileNotFound.

The API field name is reviewed, and the feature is Mark as Reviewed; the audit trail records it as Mark as Verified. For what the action means and does not do — always available, never re-runs or clears results, never notifies the signer — see Mark as Reviewed in the Sender UI topic.

Five fields on AttachmentFile carry the state. They are also returned on AttachmentRequirement.files[] wherever a role or package is read, so you can see review state without calling the verifications endpoint:

• Marking sets reviewed, reviewedBy and reviewedAt, and clears unreviewedBy and unreviewedAt.

• Undoing sets reviewed to false and records unreviewedBy and unreviewedAt, while preserving the original reviewedBy and reviewedAt as history.

• Undoing a file that was never marked, or is already unmarked, is a no-op that returns the current state.

• Replacing or deleting a file discards its review state.

Audit trail

Marking a file as reviewed and undoing it produce the audit entries Mark as Verified and Undo Verification — the audit-trail names for those actions — alongside the existing Upload File Attachment and Download File Attachment, all retrievable from GET /aws/rest/services/packages/{packageId}/audit. No classification outcome, extracted value, verification check result or integrity finding produces an audit entry — if you need a durable record of what validation reported at a point in time, capture it from the verifications endpoint yourself.