Identity Document Verification

Verify identity documents provided by the client (not the consumer). Useful when you already have document images and need verification without consumer interaction.

Identity Document Verification checks are in preview and are available in the v1alpha2 API.

Overview

Use Case: Verify identity documents when the client has already collected them and needs verification without involving the consumer in the flow.

Key Features:

Client uploads document images via API
Document verification and analysis
AML screening (sanctions/PEP checks)
No consumer interaction required
Completes once documents are uploaded and processed

Subject Type: Individual

Template ID: checkTemplates/identity-document-verification-check-v1-0-0

When to Use This Check

✅ Good for:

Verifying documents already collected by the client
Batch processing of existing document images
Situations where consumer cannot use mobile app
Integration with existing document collection systems

❌ Not suitable for:

Full identity verification with consumer in the flow (use Identity Verification instead)
Quick screening without documents (use Client-Only Verification instead)
Source of funds verification (use Source of Funds instead)

Prerequisites

Thirdfort account with API access
Client credentials (Client ID and Secret)
Document images: High-quality images of identity documents (passport, driving license, ID card)
Subject data: Name, date of birth from the document

Parameters Reference

Required Parameters

Parameter	Type	Description
`displayName`	string	Human-readable name for the check
`clientReference`	string	Your own reference ID for tracking
`template`	string	Must be `checkTemplates/identity-document-verification-check-v1-0-0`
`params.@type`	string	Must be `type.googleapis.com/thirdfort.client.checks.type.v1alpha2.IdentityDocumentVerificationCheckParams`
`params.subject.givenName`	string	First name from the document
`params.subject.familyName`	string	Last name from the document
`params.documentImages`	array	Array of document image references (uploaded separately)

Optional Parameters

Parameter	Type	Default	Description
`params.subject.otherNames`	string	-	Middle names from document
`params.subject.dateOfBirth`	Date	-	Date of birth from document (structured object: `{year, month, day}`)
`params.enableOngoingMonitoring`	bool	false	Continuous AML screening monitoring

Document Upload Flow

Step 1: Upload Document Images

Before creating the check, upload document images:

# Upload document image (example - actual endpoint may vary)
curl -X POST "https://api.thirdfort.dev/client/api/v1alpha2/organizations/{org_id}/teams/{team_id}/documents" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@passport-front.jpg" \
  -F "documentType=PASSPORT"

Response:

{
  "name": "organizations/.../teams/.../documents/abc123",
  "documentType": "PASSPORT",
  "uploadTime": "2026-03-06T14:00:00Z"
}

Save the document resource name for use in the check.

Step 2: Create Check with Document References

curl -X POST "https://api.thirdfort.dev/client/api/v1alpha2/organizations/{org_id}/teams/{team_id}/checks" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Document verification for Jane Smith",
    "clientReference": "doc-verify-12345",
    "template": "checkTemplates/identity-document-verification-check-v1-0-0",
    "params": {
      "@type": "type.googleapis.com/thirdfort.client.checks.type.v1alpha2.IdentityDocumentVerificationCheckParams",
      "subject": {
        "givenName": "Jane",
        "familyName": "Smith",
        "dateOfBirth": {
          "year": 1990,
          "month": 6,
          "day": 15
        }
      },
      "documentImages": [
        "organizations/.../teams/.../documents/abc123"
      ],
      "enableOngoingMonitoring": true
    }
  }'

Note: The endpoint includes the parent (team) in the URL path. Replace {org_id} and {team_id} with your actual organization and team IDs.

Response

{
  "name": "organizations/NT6bqXp6k47SbagGAUHHG7/teams/gZzg3caveKLhe3VXjRiyXL/checks/eaa99a49-7c7c-43e0-a929-ec2dddec8a85",
  "displayName": "Document verification for Jane Smith",
  "clientReference": "doc-verify-12345",
  "state": "ACTIVE",
  "createTime": "2026-03-06T14:06:59.758655Z",
  "updateTime": null,
  "template": "checkTemplates/identity-document-verification-check-v1-0-0",
  "params": { ... },
  "relatedSubjects": [ ... ],
  "creator": "partners/thirdfort/integrations/4",
  "ongoingMonitoring": {
    "enabled": true,
    "activeUntil": null
  },
  ...
}

Summary Response

{
  "name": "organizations/.../teams/.../checks/.../checkSummary",
  "createTime": "2026-03-06T14:07:00.537001Z",
  "payload": {
    "@type": "type.googleapis.com/thirdfort.client.checks.type.v1alpha2.IdentityDocumentVerificationCheckSummary",
    "overallRecommendation": {
      "recommendation": "CLEAR",
      "description": "No concerning issues found"
    },
    "documentVerificationResult": { ... },
    "screeningCheckResult": { ... },
    "providedSubjectData": { ... }
  },
  "sourceFindings": [ ... ],
  "reportUrl": "https://files.thirdfort.dev/client/downloads/objects/6ff46f10-ae87-42e6-8601-1f0c32ed5ba6",
  "summaryReportUrl": "https://files.thirdfort.dev/client/downloads/objects/8df632f9-e3f9-4e9e-88aa-ca449debf3b8"
}

Result Fields

Field	Description
`payload.overallRecommendation`	Overall check recommendation object with `recommendation` and `description`
`payload.documentVerificationResult`	Document verification results - always included
`payload.screeningCheckResult`	AML screening results (sanctions/PEP) - always included
`payload.providedSubjectData`	Echo of the subject data you provided
`reportUrl`	Download link for full PDF report (top-level field)
`summaryReportUrl`	Download link for summary PDF report (top-level field)
`sourceFindings`	Array of finding resource names that contributed to this summary

Recommendation Values

CLEAR: No concerning issues found - proceed with confidence
CONSIDER: Anomalies detected that may be explainable - review findings
FAIL: Serious anomalies detected, unlikely explainable - high risk

Downloading PDF Reports

Download PDF reports using the URLs from the summary:

# Download full PDF report
curl -X GET "https://files.thirdfort.dev/client/downloads/objects/6ff46f10-ae87-42e6-8601-1f0c32ed5ba6" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -o doc-verify-report.pdf

# Download summary PDF report
curl -X GET "https://files.thirdfort.dev/client/downloads/objects/8df632f9-e3f9-4e9e-88aa-ca449debf3b8" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -o doc-verify-summary.pdf

Note:

PDF downloads require the same OAuth 2.0 access token used for API calls
Use the complete URLs from reportUrl and summaryReportUrl fields directly
URLs include /objects/ in the path

Document Requirements

Supported Document Types

Passport: Photo page
Driving License: Front and back (if applicable)
National ID Card: Front and back

Image Quality Requirements

For best results, document images should:

Be in focus and clearly readable
Have good lighting (no glare or shadows)
Show the entire document (all edges visible)
Be high resolution (minimum 300 DPI recommended)
Be in color (not black and white)
Be in JPEG or PNG format

Common Image Issues

❌ Poor quality:

Blurry or out of focus
Dark or overexposed
Partial document (edges cut off)
Low resolution

✅ Good quality:

Sharp and in focus
Well-lit with no glare
Complete document visible
High resolution

Best Practices

Provide Complete Subject Data

Include all available information from the document:

{
  "subject": {
    "givenName": "Jane",
    "otherNames": "Marie",
    "familyName": "Smith",
    "dateOfBirth": {
      "year": 1990,
      "month": 6,
      "day": 15
    }
  }
}

Upload High-Quality Images

Use original images, not photocopies
Ensure good lighting when capturing images
Verify images are readable before uploading
Upload both sides of two-sided documents

Document Naming

Use clear, descriptive names for documents:

passport-photo-page.jpg
driving-license-front.jpg
driving-license-back.jpg

Common Configurations

Basic Document Verification

Minimal configuration for document verification:

{
  "displayName": "Document verification for Jane Smith",
  "clientReference": "doc-verify-12345",
  "template": "checkTemplates/identity-document-verification-check-v1-0-0",
  "params": {
    "@type": "type.googleapis.com/thirdfort.client.checks.type.v1alpha2.IdentityDocumentVerificationCheckParams",
    "subject": {
      "givenName": "Jane",
      "familyName": "Smith"
    },
    "documentImages": [
      "organizations/.../teams/.../documents/abc123"
    ]
  }
}

With Ongoing Monitoring

Enable continuous sanctions monitoring:

{
  "params": {
    "@type": "type.googleapis.com/thirdfort.client.checks.type.v1alpha2.IdentityDocumentVerificationCheckParams",
    "subject": { ... },
    "documentImages": [ ... ],
    "enableOngoingMonitoring": true
  }
}

Troubleshooting

Common Issues

400 Bad Request - "field required"

Ensure displayName and clientReference are included
Verify @type field is present in params
Check that documentImages array is not empty
Ensure subject name fields are provided

400 Bad Request - "invalid document reference"

Verify document was uploaded successfully
Check document resource name is correct
Ensure document belongs to the same team

Check stuck in ACTIVE state

Document processing may take time for large images
Check for document quality issues
Contact support if stuck for more than 5 minutes

Poor verification results

Check document image quality
Ensure document is not expired
Verify subject data matches document
Re-upload higher quality images if needed

404 Not Found

Verify the endpoint includes parent in URL: /v1alpha2/{parent}/checks
Check that organization and team IDs are correct
Ensure endpoint is /checkSummary not /summary

Check will process documents and transition to INACTIVE when complete

Check States

ACTIVE: The check is actively processing documents
INACTIVE: The check has completed and results are available
CANCELLED: The check has been permanently cancelled
DELETED: The check has been soft-deleted

For document verification checks: Checks typically move from ACTIVE to INACTIVE within seconds to minutes once document processing completes.

Understanding Results

Get Check Summary

curl -X GET "https://api.thirdfort.dev/client/api/v1alpha2/organizations/{org_id}/teams/{team_id}/checks/{check_id}/checkSummary" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Note: The endpoint is /checkSummary (camelCase), not /summary.

Overview​

When to Use This Check​

Prerequisites​

Parameters Reference​

Required Parameters​

Optional Parameters​

Document Upload Flow​

Step 1: Upload Document Images​

Step 2: Create Check with Document References​

Response​

Summary Response​

Result Fields​

Recommendation Values​

Downloading PDF Reports​

Document Requirements​

Supported Document Types​

Image Quality Requirements​

Common Image Issues​

Best Practices​

Provide Complete Subject Data​

Upload High-Quality Images​

Document Naming​

Common Configurations​

Basic Document Verification​

With Ongoing Monitoring​

Troubleshooting​

Common Issues​

Check States​

Understanding Results​

Get Check Summary​