Verify Configuration | Extend Documentation

A verify request has three top-level fields. Only file is required.

{
  "file": { "id": "file_xK9mLPqRtN3vS8wF5hB2cQ" },
  "config": {
    "engine": "verify_light",
    "engineVersion": "latest",
    "advancedOptions": { "requireParsing": true }
  },
  "metadata": { "customerDocumentId": "credential-48391" }
}

The same body is accepted by the synchronous POST /verify and asynchronous POST /verify_runs endpoints. The response echoes the resolved configuration in config, including defaults that were applied. Every supported check runs on every run; there is no way to select a subset of signals.

File

Verify analyzes the exact bytes you submit:

Input	Shape	Notes
Public URL	`{ "url": "https://...", "name": "optional.pdf" }`	Must be a public HTTP(S) URL. Localhost and private-network destinations are rejected with `400`.
Extend file ID	`{ "id": "file_..." }`	A file from `POST /files/upload` or produced by another run. Purged files return `404 FILE_PURGED`.

Supported file types

Type	What runs
PDF	All file-structure, signature, provenance, revision, layer, text, and form checks, plus image checks on embedded images and page renders. With a parse, the OCR text-layer comparison and the content checks as well.
JPEG, PNG, WebP	Provenance and image-based checks (content credentials, generator watermarks, and the image manipulation and AI-generation models). An animated WebP is checked on its first frame.

Any other type fails with FILE_TYPE_NOT_SUPPORTED. A file whose extension or declared type disagrees with its actual bytes still runs, and the mismatch is reported under FILE_FORMAT_AND_PDF_STRUCTURE.

Config

config is validated strictly: a key that is not listed here returns 400.

`engine`

Selects which checks run and whether the document is parsed first.

Engine	Behavior	When to use
`verify_agentic` (default)	Parses the file and runs every check, including the checks that read the parse, and leverages an agent harness optimized for tamper detection: an agent reads the parsed document for arithmetic, sequence, date, and identity conflicts.	Difficult cases of document fraud, and any workload where coverage matters more than latency. Slower and more expensive than `verify_light`.
`verify_light`	Faster checks that do not require parsing, but will use parsed results if the file has already been parsed in Extend. Covers all checks except the agentic checks around content and OCR. Parses only when `advancedOptions.requireParsing` is `true`.	High-volume screening where you want the fastest result.

`engineVersion`

Pins the engine release. Each release fixes the set of checks, the assessment model, and the risk policy together, so results for the same file are stable within a version.

Value	Behavior
`"latest"` (default)	Uses the newest release. The response records the resolved version in `config.engineVersion`.
A specific version, for example `"0.1.0"`	Uses exactly that release. Unsupported versions return `400 INVALID_REQUEST` listing the supported values.

Pin a version in production if you compare results over time or have tuned review thresholds against a particular release.

`advancedOptions`

Advanced options for the run. Unknown keys return 400.

`requireParsing`

If true, this forces the verify run to parse the document if it has not already been parsed in Extend. Parsing is for checks that require OCR, like detecting mismatches with the text layer. verify_agentic requires this to be true, and rejects false with 400. verify_light parses only when this is true. Defaults to false for verify_light to reduce latency.

Engine	`requireParsing` omitted	`true`	`false`
`verify_agentic`	Parses (always)	Parses	`400`: the agentic engine always parses
`verify_light`	Does not parse	Parses, adding the parse-backed checks	Does not parse

In both cases, if the file has already been parsed in Extend with Verify’s default parse settings and you reuse the fileId without zero data retention (ZDR), the parsed results are used instead of parsing again. The response always reports what happened in config.advancedOptions.requireParsing. On verify_light, enabling the parse adds the parse-backed checks only; the content checks require verify_agentic.

{ "config": { "engine": "verify_light", "advancedOptions": { "requireParsing": true } } }

Metadata

metadata is a free-form JSON object, up to 10 KB, that is stored with the run and returned on every read. Use it to carry your own identifiers.

{ "metadata": { "customerDocumentId": "credential-48391", "extend:usage_tags": ["production", "onboarding"] } }

The reserved extend:usage_tags key takes an array of strings for categorizing runs; tags may contain only letters, numbers, hyphens, and underscores. See How Credits Work for how usage tags appear in reporting.

Rate limits

POST /verify and POST /verify_runs count against your organization’s run-endpoint limit, GET /verify_runs and GET /verify_runs/{id} against the read limit, and cancel and delete against the write limit. See Rate Limits.

Full example

Python

TypeScript

Java

Go

cURL

from extend_ai import Extend
client = Extend()
run = client.verify(
    file={"id": "file_xK9mLPqRtN3vS8wF5hB2cQ"},
    config={
        "engine": "verify_light",
        "engine_version": "0.1.0",
        "advanced_options": {"require_parsing": True},
    },
    metadata={"customerDocumentId": "credential-48391"},
)
print(run.config.engine_version, run.config.advanced_options.require_parsing, run.output.risk_level)

For the full request schema, see the Verify File API reference.