Verify File (Sync) | Extend Documentation

curl -X POST https://api.extend.ai/verify \
     -H "x-extend-api-version: 2026-02-09" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "file": {
    "id": "file_xK9mLPqRtN3vS8wF5hB2cQ"
  },
  "config": {
    "engine": "verify_light",
    "engineVersion": "latest",
    "advancedOptions": {
      "requireParsing": true
    }
  },
  "metadata": {
    "customerDocumentId": "credential-48391"
  }
}'

{
  "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"
}

Check a single document for evidence of tampering, forgery, or AI generation and wait for the result. This endpoint has a timeout of 5 minutes on both engines. If processing takes longer, the request usually fails with 504 Gateway Timeout, and the response has no runId. Less often it fails with 500 INTERNAL_ERROR and retryable: false, and that error body includes the runId. Either way the run keeps processing in the background, so don’t resubmit the file. verify_agentic runs often take longer than 5 minutes, so use POST /verify_runs for them.

Note: For production workloads, use POST /verify_runs and poll GET /verify_runs/{id} instead. The asynchronous API is more reliable for large files and avoids request timeout issues.

The response is a completed verify_run. Read output.riskLevel for the document-level risk, output.summary for a plain-language explanation, and output.signals for each detected Public Signal with its supporting evidence. An empty signals array means no Public Signals were detected; it is not a claim that the document is authentic.

Beta: Verify is available to organizations enrolled in the beta. Requests from other organizations return 404 NOT_FOUND. Contact support@extend.ai to request access.

For more details, see the Verify guide. See Verify Error Handling for HTTP errors and run failure reasons.

Authentication

AuthorizationBearer

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

Headers

Request

This endpoint expects an object.

fileobjectRequired

The file to verify, as a public URL or an Extend file ID. Verify runs against the exact submitted bytes, so text and base64 inputs are not accepted. Supported inputs are PDF, JPEG, PNG, and WebP files; other types fail with FILE_TYPE_NOT_SUPPORTED.

configobjectOptional

Configuration for a verify run. Every field is optional on a request, and unknown keys are rejected with 400. Runs echo the resolved configuration, with defaults applied, in config.

metadatamap from strings to anyOptional

An optional object that can be passed in to identify the run. It will be returned back to you in the response and webhooks. Maximum size is 10KB.

To categorize runs for billing and usage tracking, include extend:usage_tags with an array of string values (e.g., {"extend:usage_tags": ["production", "team-eng", "customer-123"]}). Tags must contain only alphanumeric characters, hyphens, and underscores; any special characters will be automatically removed.

Response

Successfully verified the file

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.

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