Get Verify Run | Extend Documentation

{
  "object": "verify_run",
  "id": "vr_xK9mLPqRtN3vS8wF5hB2cQ",
  "file": {
    "object": "file",
    "id": "file_xK9mLPqRtN3vS8wF5hB2cQ",
    "name": "Invoices.pdf",
    "type": "PDF",
    "parentFileId": "file_Zk9mNP12Qw4yTv8BdR3H",
    "metadata": {
      "pageCount": 30,
      "parentSplit": {
        "id": "string",
        "type": "Invoice",
        "identifier": "other_2_9",
        "startPage": 1,
        "endPage": 10
      }
    },
    "createdAt": "2024-03-21T16:45:00Z",
    "updatedAt": "2024-03-21T16:45:00Z"
  },
  "status": "PROCESSED",
  "output": {
    "riskLevel": "LOW",
    "summary": "The document was modified after it was digitally signed: a later revision replaced page content that the signature had sealed.",
    "signals": [
      {
        "id": "vs_xK9mLPqRtN3vS8wF5hB2cQ",
        "type": "DIGITAL_SIGNATURE_INTEGRITY",
        "riskAssessment": {
          "type": "LEVEL",
          "level": "HIGH"
        },
        "summary": "Content changed after the document was signed, outside the changes the signature permits.",
        "evidence": [
          {
            "type": "value_comparison",
            "data": {
              "code": "DOCUMENT_LIFECYCLE_TIMESTAMPS",
              "values": [
                {
                  "name": "modification_time",
                  "raw": "D:20200101090000-05'00'",
                  "normalized": "2020-01-01T14:00:00Z",
                  "locationIds": [
                    "loc_1"
                  ]
                }
              ]
            },
            "evidenceId": "meta.timestamp_conflict:001",
            "locations": [
              {
                "locationId": "loc_1",
                "page": {
                  "number": 1,
                  "width": 612,
                  "height": 792
                },
                "boundingBox": {
                  "left": 325.4,
                  "top": 262.976,
                  "right": 360.66,
                  "bottom": 273.215
                },
                "objectRefs": [
                  "26 0 R"
                ],
                "byteRange": {
                  "offset": 102334,
                  "length": 537
                }
              }
            ]
          }
        ]
      }
    ]
  },
  "failureReason": "FILE_TYPE_NOT_SUPPORTED",
  "failureMessage": "This file type is not supported for verification.",
  "metadata": {},
  "metrics": {
    "processingTimeMs": 4210,
    "pageCount": 7
  },
  "config": {
    "engine": "verify_agentic",
    "engineVersion": "0.1.0",
    "advancedOptions": {
      "requireParsing": true
    }
  },
  "usage": {
    "credits": 9,
    "totalCredits": 15,
    "breakdown": [
      {
        "object": "parse_run",
        "id": "pr_3UZSj69pYZDKHFuuX57ic",
        "credits": 6,
        "charges": [
          {
            "product": "extraction_performance",
            "unit": "page",
            "quantity": 10,
            "credits": 30
          },
          {
            "product": "review_agent",
            "unit": "page",
            "quantity": 10,
            "credits": 10
          },
          {
            "product": "agentic_text_correction",
            "unit": "page",
            "quantity": 3,
            "credits": 3,
            "pages": [
              2,
              4,
              7
            ]
          }
        ]
      }
    ]
  },
  "source": "API",
  "sourceId": "apireq_Xj8mK2pL9nR4vT7qY5wZ",
  "createdAt": "2024-03-21T16:45:00Z",
  "updatedAt": "2024-03-21T16:45:00Z"
}

Retrieve the status and result of a verify run.

Use this endpoint to poll a run created with POST /verify_runs. When status is PROCESSED, output contains the document-level riskLevel, summary, and detected signals. When status is FAILED, read failureReason and failureMessage.

For a zero-retention run, the first GET that returns the result also schedules its purge, so store what you need from that response.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

idstringRequired

The unique identifier for the verify run.

Example: "vr_xK9mLPqRtN3vS8wF5hB2cQ"

Headers

Response

Successfully retrieved verify run

objectenum

The type of object. Will always be "verify_run".

Allowed values:

idstring

A unique identifier for the verify run.

Example: "vr_xK9mLPqRtN3vS8wF5hB2cQ"

fileobject or null

The file that was verified. null once the input file has been deleted.

statusenum

The status of the verify run:

"PROCESSING" - The document is still being checked
"PROCESSED" - Verification completed successfully; read output
"FAILED" - Verification failed (see failureReason for details)
"CANCELLED" - The run was cancelled before it completed

Allowed values:

outputobject or null

The verification result.

Availability: Present when status is "PROCESSED". For a zero-retention run the result is delivered once, in the synchronous response or the first GET, and purged afterwards; it is purged in any case one hour after the run reaches a terminal status.

failureReasonstring or null

The reason for failure.

Availability: Present when status is "FAILED".

Possible values include:

FILE_TYPE_NOT_SUPPORTED
NO_APPLICABLE_SIGNALS
PARSE_FAILED
REQUEST_ABORTED
INTERNAL_ERROR

Note: Additional failure reasons may be added in the future. Your integration should handle unknown values gracefully.

failureMessagestring or null

A human-readable description of the failure.

Availability: Present when status is "FAILED".

metadatamap from strings to any or null

Any metadata that was provided when creating the verify run.

Availability: Present when metadata was provided during creation.

metricsobject or null

Metrics about the verification process.

Availability: Present when status is "PROCESSED".

configobject

The configuration that ran, with defaults applied: the engine, the concrete engineVersion that "latest" resolved to, and advancedOptions.requireParsing as it applied to this run.

usageobject or null

Usage credits consumed by this verify run. Always null in the current release: verify runs are not metered during the beta.

sourceenum

How the run was created.

Allowed values:

sourceIdstring or null

An identifier for the request that created the run. For API-created runs this is the request ID, the same value returned as requestId on errors, which you can quote to support.

createdAtstringformat: "date-time"

The time (in UTC) at which the object was created. Will follow the RFC 3339 format.

Example: "2024-03-21T16:45:00Z"

updatedAtstringformat: "date-time"

The time (in UTC) at which the object was last updated. Will follow the RFC 3339 format.

Example: "2024-03-21T16:45:00Z"

Errors

400

Bad Request Error

401

Unauthorized Error

402

Payment Required Error

403

Forbidden Error

404

Not Found Error

422

Unprocessable Entity Error

429

Too Many Requests Error

500

Internal Server Error