from didit import Didit
# Reads DIDIT_API_KEY.
client = Didit()
result = client.document_ai.analyze(
document=open("document.pdf", "rb"),
fields="[{\"key\": \"employer_name\", \"name\": \"Employer name\", \"instruction\": \"The employer or company issuing the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": false}, {\"key\": \"employee_name\", \"name\": \"Employee name\", \"instruction\": \"The full name of the employee as printed on the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": true}, {\"key\": \"net_pay\", \"name\": \"Net pay\", \"instruction\": \"The net amount paid to the employee for the period.\", \"type\": \"number\", \"required\": true, \"is_full_name\": false}, {\"key\": \"pay_date\", \"name\": \"Pay date\", \"instruction\": \"The payment date shown on the payslip.\", \"type\": \"date\", \"required\": false, \"is_full_name\": false}]",
)
print(result)import Didit, { fileFromPath } from "@didit-protocol/sdk-node";
// Reads DIDIT_API_KEY.
const didit = new Didit();
const result = await didit.documentAi.analyze({
document: await fileFromPath("document.pdf"),
fields: "[{\"key\": \"employer_name\", \"name\": \"Employer name\", \"instruction\": \"The employer or company issuing the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": false}, {\"key\": \"employee_name\", \"name\": \"Employee name\", \"instruction\": \"The full name of the employee as printed on the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": true}, {\"key\": \"net_pay\", \"name\": \"Net pay\", \"instruction\": \"The net amount paid to the employee for the period.\", \"type\": \"number\", \"required\": true, \"is_full_name\": false}, {\"key\": \"pay_date\", \"name\": \"Pay date\", \"instruction\": \"The payment date shown on the payslip.\", \"type\": \"date\", \"required\": false, \"is_full_name\": false}]",
});
console.log(result);ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()
result, err := client.DocumentAi.Analyze(ctx, didit.DocumentAiAnalyzeParams{
Document: didit.FileFromPath("document.pdf"),
Fields: "[{\"key\": \"employer_name\", \"name\": \"Employer name\", \"instruction\": \"The employer or company issuing the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": false}, {\"key\": \"employee_name\", \"name\": \"Employee name\", \"instruction\": \"The full name of the employee as printed on the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": true}, {\"key\": \"net_pay\", \"name\": \"Net pay\", \"instruction\": \"The net amount paid to the employee for the period.\", \"type\": \"number\", \"required\": true, \"is_full_name\": false}, {\"key\": \"pay_date\", \"name\": \"Pay date\", \"instruction\": \"The payment date shown on the payslip.\", \"type\": \"date\", \"required\": false, \"is_full_name\": false}]",
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", result)import java.nio.file.Path;
import me.didit.Didit;
import me.didit.types.DocumentAiAnalyzeParams;
// Reads DIDIT_API_KEY.
Didit client = new Didit();
var result = client.documentAi().analyze(DocumentAiAnalyzeParams.builder()
.document(Path.of("document.pdf"))
.fields("[{\"key\": \"employer_name\", \"name\": \"Employer name\", \"instruction\": \"The employer or company issuing the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": false}, {\"key\": \"employee_name\", \"name\": \"Employee name\", \"instruction\": \"The full name of the employee as printed on the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": true}, {\"key\": \"net_pay\", \"name\": \"Net pay\", \"instruction\": \"The net amount paid to the employee for the period.\", \"type\": \"number\", \"required\": true, \"is_full_name\": false}, {\"key\": \"pay_date\", \"name\": \"Pay date\", \"instruction\": \"The payment date shown on the payslip.\", \"type\": \"date\", \"required\": false, \"is_full_name\": false}]")
.build());
System.out.println(result);<?php
require 'vendor/autoload.php';
use Didit\DiditClient;
use Didit\File;
// Reads DIDIT_API_KEY.
$didit = new DiditClient();
$result = $didit->documentAi->analyze([
'document' => File::fromPath('document.pdf'),
'fields' => '[{"key": "employer_name", "name": "Employer name", "instruction": "The employer or company issuing the payslip.", "type": "text", "required": true, "is_full_name": false}, {"key": "employee_name", "name": "Employee name", "instruction": "The full name of the employee as printed on the payslip.", "type": "text", "required": true, "is_full_name": true}, {"key": "net_pay", "name": "Net pay", "instruction": "The net amount paid to the employee for the period.", "type": "number", "required": true, "is_full_name": false}, {"key": "pay_date", "name": "Pay date", "instruction": "The payment date shown on the payslip.", "type": "date", "required": false, "is_full_name": false}]',
]);
print_r($result->toArray());require "didit"
# Reads DIDIT_API_KEY.
didit = Didit::Client.new
result = didit.document_ai.analyze(
document: Pathname("document.pdf"),
fields: "[{\"key\": \"employer_name\", \"name\": \"Employer name\", \"instruction\": \"The employer or company issuing the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": false}, {\"key\": \"employee_name\", \"name\": \"Employee name\", \"instruction\": \"The full name of the employee as printed on the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": true}, {\"key\": \"net_pay\", \"name\": \"Net pay\", \"instruction\": \"The net amount paid to the employee for the period.\", \"type\": \"number\", \"required\": true, \"is_full_name\": false}, {\"key\": \"pay_date\", \"name\": \"Pay date\", \"instruction\": \"The payment date shown on the payslip.\", \"type\": \"date\", \"required\": false, \"is_full_name\": false}]"
)
puts result.to_husing System;
using System.Text.Json;
using Didit;
// Reads DIDIT_API_KEY.
using var client = new DiditClient();
var result = await client.DocumentAi.AnalyzeAsync(new DocumentAiAnalyzeParams
{
Document = FileUpload.FromPath("document.pdf"),
Fields = "[{\"key\": \"employer_name\", \"name\": \"Employer name\", \"instruction\": \"The employer or company issuing the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": false}, {\"key\": \"employee_name\", \"name\": \"Employee name\", \"instruction\": \"The full name of the employee as printed on the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": true}, {\"key\": \"net_pay\", \"name\": \"Net pay\", \"instruction\": \"The net amount paid to the employee for the period.\", \"type\": \"number\", \"required\": true, \"is_full_name\": false}, {\"key\": \"pay_date\", \"name\": \"Pay date\", \"instruction\": \"The payment date shown on the payslip.\", \"type\": \"date\", \"required\": false, \"is_full_name\": false}]",
});
Console.WriteLine(JsonSerializer.Serialize(result));curl --request POST \
--url https://verification.didit.me/v3/document-ai/ \
--header 'Content-Type: multipart/form-data' \
--header 'x-api-key: <api-key>' \
--form document=@example-file \
--form 'fields=[{"key": "employer_name", "name": "Employer name", "instruction": "The employer or company issuing the payslip.", "type": "text", "required": true, "is_full_name": false}, {"key": "employee_name", "name": "Employee name", "instruction": "The full name of the employee as printed on the payslip.", "type": "text", "required": true, "is_full_name": true}, {"key": "net_pay", "name": "Net pay", "instruction": "The net amount paid to the employee for the period.", "type": "number", "required": true, "is_full_name": false}, {"key": "pay_date", "name": "Pay date", "instruction": "The payment date shown on the payslip.", "type": "date", "required": false, "is_full_name": false}]' \
--form expected_first_name=Sophia \
--form expected_last_name=Martinez \
--form 'expected_company_name=<string>' \
--form 'expected_company_country=<string>' \
--form document_ai_name_match_score_threshold=80 \
--form document_ai_unreadable_document_action=REVIEW \
--form document_ai_missing_required_fields_action=REVIEW \
--form document_ai_document_tampering_action=DECLINE \
--form document_ai_name_mismatch_action=NO_ACTION \
--form document_ai_unsupported_file_action=REVIEW \
--form save_api_request=true \
--form vendor_data=user-123 \
--form 'metadata={
"flow": "onboarding"
}'{
"request_id": "9d6a3b1e-2f0c-4a8e-9b7d-1c2e3f4a5b6c",
"document_ai": {
"status": "Approved",
"extracted_data": {
"employer_name": "Acme Payments Ltd",
"employee_name": "Sophia Martinez",
"net_pay": 3120.5,
"pay_date": "2026-07-31"
},
"detected_codes": [
{
"type": "CODE_128",
"page_number": 1,
"position": [
[
96,
456
],
[
96,
616
],
[
1012,
611
],
[
1015,
456
]
],
"x": 96,
"y": 456,
"width": 919,
"height": 160,
"page_width": 1200,
"page_height": 1700,
"raw_payload": "SU5WLTIwMjYtMDA0Mg==",
"parsed_payload": "INV-2026-0042"
}
],
"fields": [
{
"key": "employer_name",
"name": "Employer name",
"instruction": "The employer or company issuing the payslip.",
"type": "text",
"required": true,
"is_full_name": false
},
{
"key": "employee_name",
"name": "Employee name",
"instruction": "The full name of the employee as printed on the payslip.",
"type": "text",
"required": true,
"is_full_name": true
},
{
"key": "net_pay",
"name": "Net pay",
"instruction": "The net amount paid to the employee for the period.",
"type": "number",
"required": true,
"is_full_name": false
},
{
"key": "pay_date",
"name": "Pay date",
"instruction": "The payment date shown on the payslip.",
"type": "date",
"required": false,
"is_full_name": false
}
],
"name_match_score": 100,
"name_on_document": "Sophia Martinez",
"warnings": []
},
"vendor_data": "user-123",
"metadata": {
"flow": "onboarding"
},
"created_at": "2026-08-19T16:40:12.318Z"
}Document AI API: Custom Document Data Extraction
POST /v3/document-ai/ extracts fields you define from any PDF or image server to server, with name matching and tampering checks. $0.20 per document.
from didit import Didit
# Reads DIDIT_API_KEY.
client = Didit()
result = client.document_ai.analyze(
document=open("document.pdf", "rb"),
fields="[{\"key\": \"employer_name\", \"name\": \"Employer name\", \"instruction\": \"The employer or company issuing the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": false}, {\"key\": \"employee_name\", \"name\": \"Employee name\", \"instruction\": \"The full name of the employee as printed on the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": true}, {\"key\": \"net_pay\", \"name\": \"Net pay\", \"instruction\": \"The net amount paid to the employee for the period.\", \"type\": \"number\", \"required\": true, \"is_full_name\": false}, {\"key\": \"pay_date\", \"name\": \"Pay date\", \"instruction\": \"The payment date shown on the payslip.\", \"type\": \"date\", \"required\": false, \"is_full_name\": false}]",
)
print(result)import Didit, { fileFromPath } from "@didit-protocol/sdk-node";
// Reads DIDIT_API_KEY.
const didit = new Didit();
const result = await didit.documentAi.analyze({
document: await fileFromPath("document.pdf"),
fields: "[{\"key\": \"employer_name\", \"name\": \"Employer name\", \"instruction\": \"The employer or company issuing the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": false}, {\"key\": \"employee_name\", \"name\": \"Employee name\", \"instruction\": \"The full name of the employee as printed on the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": true}, {\"key\": \"net_pay\", \"name\": \"Net pay\", \"instruction\": \"The net amount paid to the employee for the period.\", \"type\": \"number\", \"required\": true, \"is_full_name\": false}, {\"key\": \"pay_date\", \"name\": \"Pay date\", \"instruction\": \"The payment date shown on the payslip.\", \"type\": \"date\", \"required\": false, \"is_full_name\": false}]",
});
console.log(result);ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()
result, err := client.DocumentAi.Analyze(ctx, didit.DocumentAiAnalyzeParams{
Document: didit.FileFromPath("document.pdf"),
Fields: "[{\"key\": \"employer_name\", \"name\": \"Employer name\", \"instruction\": \"The employer or company issuing the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": false}, {\"key\": \"employee_name\", \"name\": \"Employee name\", \"instruction\": \"The full name of the employee as printed on the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": true}, {\"key\": \"net_pay\", \"name\": \"Net pay\", \"instruction\": \"The net amount paid to the employee for the period.\", \"type\": \"number\", \"required\": true, \"is_full_name\": false}, {\"key\": \"pay_date\", \"name\": \"Pay date\", \"instruction\": \"The payment date shown on the payslip.\", \"type\": \"date\", \"required\": false, \"is_full_name\": false}]",
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", result)import java.nio.file.Path;
import me.didit.Didit;
import me.didit.types.DocumentAiAnalyzeParams;
// Reads DIDIT_API_KEY.
Didit client = new Didit();
var result = client.documentAi().analyze(DocumentAiAnalyzeParams.builder()
.document(Path.of("document.pdf"))
.fields("[{\"key\": \"employer_name\", \"name\": \"Employer name\", \"instruction\": \"The employer or company issuing the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": false}, {\"key\": \"employee_name\", \"name\": \"Employee name\", \"instruction\": \"The full name of the employee as printed on the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": true}, {\"key\": \"net_pay\", \"name\": \"Net pay\", \"instruction\": \"The net amount paid to the employee for the period.\", \"type\": \"number\", \"required\": true, \"is_full_name\": false}, {\"key\": \"pay_date\", \"name\": \"Pay date\", \"instruction\": \"The payment date shown on the payslip.\", \"type\": \"date\", \"required\": false, \"is_full_name\": false}]")
.build());
System.out.println(result);<?php
require 'vendor/autoload.php';
use Didit\DiditClient;
use Didit\File;
// Reads DIDIT_API_KEY.
$didit = new DiditClient();
$result = $didit->documentAi->analyze([
'document' => File::fromPath('document.pdf'),
'fields' => '[{"key": "employer_name", "name": "Employer name", "instruction": "The employer or company issuing the payslip.", "type": "text", "required": true, "is_full_name": false}, {"key": "employee_name", "name": "Employee name", "instruction": "The full name of the employee as printed on the payslip.", "type": "text", "required": true, "is_full_name": true}, {"key": "net_pay", "name": "Net pay", "instruction": "The net amount paid to the employee for the period.", "type": "number", "required": true, "is_full_name": false}, {"key": "pay_date", "name": "Pay date", "instruction": "The payment date shown on the payslip.", "type": "date", "required": false, "is_full_name": false}]',
]);
print_r($result->toArray());require "didit"
# Reads DIDIT_API_KEY.
didit = Didit::Client.new
result = didit.document_ai.analyze(
document: Pathname("document.pdf"),
fields: "[{\"key\": \"employer_name\", \"name\": \"Employer name\", \"instruction\": \"The employer or company issuing the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": false}, {\"key\": \"employee_name\", \"name\": \"Employee name\", \"instruction\": \"The full name of the employee as printed on the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": true}, {\"key\": \"net_pay\", \"name\": \"Net pay\", \"instruction\": \"The net amount paid to the employee for the period.\", \"type\": \"number\", \"required\": true, \"is_full_name\": false}, {\"key\": \"pay_date\", \"name\": \"Pay date\", \"instruction\": \"The payment date shown on the payslip.\", \"type\": \"date\", \"required\": false, \"is_full_name\": false}]"
)
puts result.to_husing System;
using System.Text.Json;
using Didit;
// Reads DIDIT_API_KEY.
using var client = new DiditClient();
var result = await client.DocumentAi.AnalyzeAsync(new DocumentAiAnalyzeParams
{
Document = FileUpload.FromPath("document.pdf"),
Fields = "[{\"key\": \"employer_name\", \"name\": \"Employer name\", \"instruction\": \"The employer or company issuing the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": false}, {\"key\": \"employee_name\", \"name\": \"Employee name\", \"instruction\": \"The full name of the employee as printed on the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": true}, {\"key\": \"net_pay\", \"name\": \"Net pay\", \"instruction\": \"The net amount paid to the employee for the period.\", \"type\": \"number\", \"required\": true, \"is_full_name\": false}, {\"key\": \"pay_date\", \"name\": \"Pay date\", \"instruction\": \"The payment date shown on the payslip.\", \"type\": \"date\", \"required\": false, \"is_full_name\": false}]",
});
Console.WriteLine(JsonSerializer.Serialize(result));curl --request POST \
--url https://verification.didit.me/v3/document-ai/ \
--header 'Content-Type: multipart/form-data' \
--header 'x-api-key: <api-key>' \
--form document=@example-file \
--form 'fields=[{"key": "employer_name", "name": "Employer name", "instruction": "The employer or company issuing the payslip.", "type": "text", "required": true, "is_full_name": false}, {"key": "employee_name", "name": "Employee name", "instruction": "The full name of the employee as printed on the payslip.", "type": "text", "required": true, "is_full_name": true}, {"key": "net_pay", "name": "Net pay", "instruction": "The net amount paid to the employee for the period.", "type": "number", "required": true, "is_full_name": false}, {"key": "pay_date", "name": "Pay date", "instruction": "The payment date shown on the payslip.", "type": "date", "required": false, "is_full_name": false}]' \
--form expected_first_name=Sophia \
--form expected_last_name=Martinez \
--form 'expected_company_name=<string>' \
--form 'expected_company_country=<string>' \
--form document_ai_name_match_score_threshold=80 \
--form document_ai_unreadable_document_action=REVIEW \
--form document_ai_missing_required_fields_action=REVIEW \
--form document_ai_document_tampering_action=DECLINE \
--form document_ai_name_mismatch_action=NO_ACTION \
--form document_ai_unsupported_file_action=REVIEW \
--form save_api_request=true \
--form vendor_data=user-123 \
--form 'metadata={
"flow": "onboarding"
}'{
"request_id": "9d6a3b1e-2f0c-4a8e-9b7d-1c2e3f4a5b6c",
"document_ai": {
"status": "Approved",
"extracted_data": {
"employer_name": "Acme Payments Ltd",
"employee_name": "Sophia Martinez",
"net_pay": 3120.5,
"pay_date": "2026-07-31"
},
"detected_codes": [
{
"type": "CODE_128",
"page_number": 1,
"position": [
[
96,
456
],
[
96,
616
],
[
1012,
611
],
[
1015,
456
]
],
"x": 96,
"y": 456,
"width": 919,
"height": 160,
"page_width": 1200,
"page_height": 1700,
"raw_payload": "SU5WLTIwMjYtMDA0Mg==",
"parsed_payload": "INV-2026-0042"
}
],
"fields": [
{
"key": "employer_name",
"name": "Employer name",
"instruction": "The employer or company issuing the payslip.",
"type": "text",
"required": true,
"is_full_name": false
},
{
"key": "employee_name",
"name": "Employee name",
"instruction": "The full name of the employee as printed on the payslip.",
"type": "text",
"required": true,
"is_full_name": true
},
{
"key": "net_pay",
"name": "Net pay",
"instruction": "The net amount paid to the employee for the period.",
"type": "number",
"required": true,
"is_full_name": false
},
{
"key": "pay_date",
"name": "Pay date",
"instruction": "The payment date shown on the payslip.",
"type": "date",
"required": false,
"is_full_name": false
}
],
"name_match_score": 100,
"name_on_document": "Sophia Martinez",
"warnings": []
},
"vendor_data": "user-123",
"metadata": {
"flow": "onboarding"
},
"created_at": "2026-08-19T16:40:12.318Z"
}text, number, or date as YYYY-MM-DD), detects and decodes supported QR codes and barcodes, checks the file for manipulation, and optionally compares the name on the document against the person or company you expect. Use it for proof of funds, payslips, bank statements, tax documents, invoices, or any document that does not fit a fixed template.
This is the server-to-server version of the hosted Document AI step. The request is multipart/form-data: the file goes in document, and the field definitions go in fields as one JSON-encoded array string.
Define the fields to extract
fields is a JSON array of 1 to 30 items, sent as a single string. Each item has a key (lowercase letters, digits, and underscores, unique within the request), a human-readable name, an instruction that tells the model what to look for, a type (text, number, or date), and two flags: required and is_full_name.
[
{
"key": "account_holder",
"name": "Account holder",
"instruction": "Full name of the person or company the account belongs to",
"type": "text",
"required": true,
"is_full_name": true
},
{
"key": "balance",
"name": "Closing balance",
"instruction": "Closing balance shown on the statement, as a number without the currency symbol",
"type": "number",
"required": true
},
{
"key": "currency",
"name": "Currency",
"instruction": "Three-letter currency code of the balance",
"type": "text"
},
{
"key": "statement_date",
"name": "Statement date",
"instruction": "Date the statement was issued",
"type": "date",
"required": true
}
]
curl -X POST https://verification.didit.me/v3/document-ai/ \
-H "x-api-key: $DIDIT_API_KEY" \
-F "document=@./bank-statement.pdf" \
-F 'fields=[{"key":"account_holder","name":"Account holder","instruction":"Full name of the account holder","type":"text","required":true,"is_full_name":true},{"key":"balance","name":"Closing balance","instruction":"Closing balance as a number","type":"number","required":true}]' \
-F "expected_first_name=Jane" \
-F "expected_last_name=Doe"
fields and returns extracted_data keyed by your key values, with null for anything the model could not find. name, instruction, and type are optional on each item (type defaults to text); key is required. Sending fields as bracket-style form keys (fields[0][key]=...) or as anything other than a JSON array returns 400 before any extraction runs, so nothing is billed.
QR codes and barcodes
Every successful response includesdocument_ai.detected_codes. Each item contains:
| Field | Description |
|---|---|
type | Detected symbology, such as QR_CODE, CODE_128, EAN_13, DATA_MATRIX, or PDF_417 |
page_number | 1-based page number |
position | Detected polygon in rendered-page pixels, or null when no reliable location is available |
x, y, width, height | Bounding box in rendered-page pixels, or null when no reliable location is available |
page_width, page_height | Rendered page dimensions used by the coordinates |
parsed_payload | Decoded string or structured value, or null when the code can only be located |
raw_payload | Raw decoder payload as a base64 string when available; otherwise an empty string |
parsed_payload: null, while failures in code detection do not fail the Document AI request.
Name matching
Mark at most one field withis_full_name: true and send who you expect the document to belong to:
| You are verifying | Send | The name is compared against |
|---|---|---|
| A person | expected_first_name + expected_last_name | the person’s full name |
| A company | expected_company_name (+ optional expected_company_country, a 2-letter ISO code) | the company name |
name_match_score (0 to 100) and name_on_document. A score below document_ai_name_match_score_threshold (default 80) raises the DOCUMENT_AI_NAME_MISMATCH warning and applies document_ai_name_mismatch_action. If no field is marked is_full_name, Didit falls back to the first text field whose key looks like a name (name, holder, full_name, account_holder); mark the field explicitly when you want to control which value is compared. When no name value can be found on the document, or no expected name is sent, the name check is skipped and name_match_score is null.
Risks and actions
Each risk below maps to an action parameter you can set per request:DECLINE, REVIEW, or NO_ACTION. The strictest triggered action decides document_ai.status (Declined > In Review > Approved), and every triggered risk is listed in document_ai.warnings. The defaults match the hosted workflow step; see Document AI rules & warnings for how each risk is detected.
| Risk | Parameter | Default |
|---|---|---|
DOCUMENT_AI_UNREADABLE_DOCUMENT | document_ai_unreadable_document_action | REVIEW |
DOCUMENT_AI_MISSING_REQUIRED_FIELDS | document_ai_missing_required_fields_action | REVIEW |
DOCUMENT_AI_SUSPECTED_MANIPULATION | document_ai_document_tampering_action | DECLINE |
DOCUMENT_AI_NAME_MISMATCH | document_ai_name_mismatch_action | NO_ACTION |
DOCUMENT_AI_UNSUPPORTED_FILE | document_ai_unsupported_file_action | REVIEW |
Files, saving, and billing
- Accepted files: PDF (multi-page supported), JPG, JPEG, PNG, TIFF, WebP, or a ZIP containing the document, up to 30 MB. Encrypted PDFs return
400; upload a decrypted PDF or a photo instead. save_api_request(defaulttrue): the request, extracted fields, and detected codes appear in the Business Console under Manual Checks, where your team can review them. Set it tofalseto skip saving.vendor_dataandmetadataare returned unchanged in the response so you can link the result to your own records.- Price: $0.20 per document, billed when the document is processed and a status is returned. Your plan discount applies. See Pricing.
Authorizations
Your application's API key, from Developers -> API keys in the Business Console. The primary key has full access. A named key can be scoped: none, read or write per resource, limited to some workflows or to approved sessions, to a list of IP addresses, and to an expiry date. 401 means the key is wrong, revoked or expired; 403 means no key was sent, the key has no access to this resource or action, or the request came from an address outside its IP list; 404 on a session route means the session is outside the key's workflows or statuses. A key without media access receives image, video and PDF URLs as null, and a key without sessions write receives session links and tokens as null. See https://docs.didit.me/console/api-keys.
Headers
Optional retry-safety key you choose for one operation, up to 255 characters (a UUID works). A request repeated with the same key, endpoint, query and body is answered with the first response, same status and same body, and runs and bills nothing a second time. The same key with another endpoint, query or body returns 409 idempotency_key_reused, and while the first request is still running, 409 idempotency_key_in_progress with Retry-After. A failed request (any 4xx or 5xx) is not stored, so you can send it again with the same key. Keys belong to your application, whether you call with an API key or an access token. See Retries and idempotency.
1 - 255Body
The document to read. Allowed extensions: tiff, jpg, jpeg, png, pdf, webp, zip. Maximum upload size: 30 MB (larger files are rejected with 400). Multi-page PDFs are supported (expect higher latency); encrypted PDFs are rejected with 400. Images are automatically compressed before processing.
One JSON-encoded array string with 1–30 field definitions (maximum 16 KB). Each item: key (required, ^[a-z0-9_]{1,64}$, unique — the key returned in extracted_data), name (≤100 chars, shown in messages), instruction (≤500 chars, what the model should read), type (text default | number | date), required (boolean, default false), is_full_name (boolean, default false, at most one per request). Bracket-style form arrays, invalid JSON, duplicate keys, or more than one is_full_name return 400 before any processing or billing.
"[{\"key\": \"employer_name\", \"name\": \"Employer name\", \"instruction\": \"The employer or company issuing the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": false}, {\"key\": \"employee_name\", \"name\": \"Employee name\", \"instruction\": \"The full name of the employee as printed on the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": true}, {\"key\": \"net_pay\", \"name\": \"Net pay\", \"instruction\": \"The net amount paid to the employee for the period.\", \"type\": \"number\", \"required\": true, \"is_full_name\": false}, {\"key\": \"pay_date\", \"name\": \"Pay date\", \"instruction\": \"The payment date shown on the payslip.\", \"type\": \"date\", \"required\": false, \"is_full_name\": false}]"
Company name to verify against the document's name field (for business documents). Cannot be combined with expected_first_name / expected_last_name (no example value on purpose — the generated request sample uses the person fields; swap them for this one when verifying a business document).
What to do when PDF/EXIF forensics suspect manipulation — modified after digital signing, known PDF editor, overlay-text manipulation, suspicious re-export, image anomalies (DOCUMENT_AI_SUSPECTED_MANIPULATION).
DECLINE, REVIEW, NO_ACTION When true (default), persists the call as an API-type session — visible in the Business Console, retrievable via GET /v3/session/{sessionId}/decision/ using the returned request_id, with the uploaded document, the extracted values, the field definitions and the name-match snapshot stored. When false, nothing is stored and request_id is a transient UUID for response correlation only; the call is still billed.
true
Response
Document processed. document_ai.status is Approved, Declined, or In Review; every detected issue is itemized in document_ai.warnings. A problematic document still returns 200 — inspect the body, not just the HTTP code. When save_api_request=true, request_id is the persisted session id.