> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete REST API reference for Didit identity verification. Sessions, standalone endpoints, management API, and OpenAPI spec. Pay-per-use pricing.

export const SectionHeader = ({label, title, description, align = "left"}) => <div className="didit-section-header" style={{
  textAlign: align,
  alignItems: align === "center" ? "center" : "flex-start"
}}>
    {label && <p className="didit-section-label">{label}</p>}
    <h2 className="didit-section-title">{title}</h2>
    {description && <p className="didit-section-desc">{description}</p>}
  </div>;

export const FeatureGrid = ({cols = 3, children}) => <div className="didit-feature-grid" style={{
  "--grid-cols": cols
}}>
    {children}
  </div>;

export const FeatureCard = ({icon, title, description, href}) => {
  const inner = <div className="didit-feature-card">
      {icon && <div className="didit-feature-card-icon">
          <Icon icon={icon} size={20} />
        </div>}
      <div className="didit-feature-card-content">
        <h3 className="didit-feature-card-title">{title}</h3>
        {description && <p className="didit-feature-card-desc">{description}</p>}
      </div>
      {href && <div className="didit-feature-card-arrow">
          <Icon icon="arrow-right" size={14} />
        </div>}
    </div>;
  if (href) {
    return <a href={href} style={{
      textDecoration: "none",
      color: "inherit",
      display: "block",
      border: "none",
      boxShadow: "none"
    }}>{inner}</a>;
  }
  return inner;
};

export const AgentPromptAccordion = ({prompt, title = "AI Agent Integration Prompt"}) => {
  const [copied, setCopied] = React.useState(false);
  const handleCopy = e => {
    e.stopPropagation();
    if (!prompt) return;
    navigator.clipboard.writeText(prompt.trim()).then(() => {
      setCopied(true);
      setTimeout(() => setCopied(false), 2000);
    });
  };
  const agents = ["Claude Code", "Codex", "Cursor", "Devin", "Windsurf", "GitHub Copilot"];
  return <div className="didit-agent-card">
      {}
      <div className="didit-agent-titlebar">
        <div className="didit-agent-dots" aria-hidden="true">
          <span className="didit-agent-dot didit-agent-dot-red"></span>
          <span className="didit-agent-dot didit-agent-dot-yellow"></span>
          <span className="didit-agent-dot didit-agent-dot-green"></span>
        </div>
        <span className="didit-agent-filename">{title}</span>
        <button type="button" className={`didit-agent-copy ${copied ? "didit-agent-copy-copied" : ""}`} onClick={handleCopy} title="Copy prompt to clipboard" aria-label={copied ? "Copied!" : "Copy prompt to clipboard"}>
          {copied ? <>
              <svg width="13" height="13" viewBox="0 0 16 16" fill="none">
                <path d="M3 8.5l3.5 3.5L13 4" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" />
              </svg>
              <span>Copied</span>
            </> : <>
              <svg width="13" height="13" viewBox="0 0 16 16" fill="none">
                <rect x="5" y="5" width="9" height="9" rx="1.5" stroke="currentColor" strokeWidth="1.5" />
                <path d="M11 5V3.5A1.5 1.5 0 0 0 9.5 2h-6A1.5 1.5 0 0 0 2 3.5v6A1.5 1.5 0 0 0 3.5 11H5" stroke="currentColor" strokeWidth="1.5" />
              </svg>
              <span>Copy</span>
            </>}
        </button>
      </div>

      {}
      <pre className="didit-agent-body"><code>{prompt.trim()}</code></pre>

      {}
      <div className="didit-agent-footer">
        <span className="didit-agent-footer-label">Paste into</span>
        <div className="didit-agent-chips">
          {agents.map(name => <span key={name} className="didit-agent-chip">{name}</span>)}
        </div>
      </div>
    </div>;
};

<AgentPromptAccordion
  title="Standalone API Integration Prompt"
  prompt={`Integrate Didit standalone verification APIs into my backend for server-to-server identity checks.

## Available Standalone APIs

### Identity & Documents
- POST /v3/id-verification/ — multipart/form-data: front_image (required), back_image (optional). Returns: { request_id, id_verification: { status, first_name, last_name, document_type, document_number, date_of_birth, nationality, expiration_date, issuing_state, address, parsed_address, warnings[] } }
- POST /v3/poa/ — multipart/form-data: document (PDF/image). Returns: { request_id, poa: { status, document_type, issuer, poa_address, poa_parsed_address, issue_date, warnings[] } }
- POST /v3/database-validation/ — JSON: { issuing_state, validation_type, first_name, last_name, date_of_birth, personal_number, ... }. Returns: { request_id, database_validation: { status, validations } }

### Document AI
- POST /v3/document-ai/ — multipart/form-data: document (PDF/image), fields (one JSON-encoded array string of { key, name, instruction, type: "text"|"number"|"date", required, is_full_name }, 1-30 items), expected_first_name + expected_last_name OR expected_company_name (+ expected_company_country), document_ai_name_match_score_threshold (default 80), per-risk *_action params. Returns: { request_id, document_ai: { status, extracted_data: { <key>: value|null }, detected_codes[], fields[], name_match_score, name_on_document, warnings[] } }. $0.20 per document.

### Biometrics & Face
- POST /v3/passive-liveness/ — multipart/form-data: user_image. Returns: { request_id, passive_liveness: { status, score, method } }
- POST /v3/face-match/ — multipart/form-data: user_image + ref_image. Returns: { request_id, face_match: { status, score } }
- POST /v3/face-search/ — multipart/form-data: user_image. Returns: { request_id, face_search: { status, total_matches, matches[] } }
- POST /v3/age-estimation/ — multipart/form-data: user_image. Returns: { request_id, age_estimation: { status, age_estimation, score } }

### Compliance
- POST /v3/aml/ — JSON: { full_name, entity_type, date_of_birth, nationality, document_number, include_adverse_media, include_ongoing_monitoring }. Returns: { request_id, aml: { status, total_hits, hits[], score, entity_type } }

### Business Verification (KYB)
- POST /v3/kyb/search/ — JSON: { country_code (required), name, registration_number, search_type: "contains"|"start_with"|"fuzzy", webhook_url, vendor_data, metadata }. Up to $0.50 per successful request, separately from profile retrieval; empty results and failures are not charged. Returns: { request_id, kyb_registry: { companies[] ({ kyb_response_id, name, registration_number, status, type, fetch_status }), pagination, search_status, search_resolved } }. \`kyb_response_id\` is an opaque handle — pass it straight to select/shareholders/ubo, never parse it.
- POST /v3/kyb/select/ — JSON: { kyb_response_id (from search), save_api_request, vendor_data, metadata }. **Lite** tier, priced per country ([per-country prices](/getting-started/kyb-registry-pricing)). Returns: { request_id, kyb_registry: { status, company_name, registration_number, country_code, company_type, incorporation_date, registered_address, officers[], beneficial_owners[], fetch_status, data_resolved, ... } }
- POST /v3/kyb/shareholders/ and POST /v3/kyb/ubo/ — same JSON shape as select. **Shareholders** and **UBOs** tiers, priced per country; delivered and billed as the highest tier the country's registries can serve. v3 only.

### Contact Verification
- POST /v3/email/send/ — JSON: { email }. Sends OTP code.
- POST /v3/email/check/ — JSON: { email, code }. Verifies OTP.
- POST /v3/phone/send/ — JSON: { phone, channel }. Sends OTP via SMS/WhatsApp/Telegram.
- POST /v3/phone/check/ — JSON: { phone, code }. Verifies OTP.

## Authentication
All requests require: Headers: { "x-api-key": DIDIT_API_KEY }
For file uploads: multipart/form-data. For JSON: Content-Type: application/json.

## Common Parameters
- save_api_request (bool, default true): if true, appears in Console > Manual Checks
- vendor_data (string): your internal ID for tracking

## Example: ID Verification (Node.js)
const FormData = require('form-data');
const fs = require('fs');
const form = new FormData();
form.append('front_image', fs.createReadStream('./id_front.jpg'));
form.append('back_image', fs.createReadStream('./id_back.jpg'));

const response = await fetch('https://verification.didit.me/v3/id-verification/', {
method: 'POST',
headers: { 'x-api-key': process.env.DIDIT_API_KEY, ...form.getHeaders() },
body: form
});
const result = await response.json();
// result.id_verification.status: "Approved" or "Declined"
// result.id_verification.first_name, .last_name, .document_number, etc.

## Example: AML Screening
const response = await fetch('https://verification.didit.me/v3/aml/', {
method: 'POST',
headers: { 'x-api-key': process.env.DIDIT_API_KEY, 'Content-Type': 'application/json' },
body: JSON.stringify({
full_name: 'John Doe',
entity_type: 'person',
date_of_birth: '1990-01-15',
nationality: 'US'
})
});
const result = await response.json();
// result.aml.status, result.aml.total_hits, result.aml.hits

## When to Use Standalone APIs vs Sessions
- Standalone: you have images/data, server-to-server, batch processing, custom UX
- Sessions: user-facing flows where Didit handles camera, UX, multi-step, 49 languages

## Rate Limits
- Free: 10/min. Paid: 600/min. Exceeded: HTTP 429.

## Environment Variables
- DIDIT_API_KEY — from Didit Console > API & Webhooks

## Docs
- API Reference: https://docs.didit.me/api-reference/overview
- Sessions vs APIs: https://docs.didit.me/api-reference/overview
- Webhooks: https://docs.didit.me/integration/webhooks
`}
/>

Didit offers **two complementary approaches** to identity verification. Understanding the difference is essential for choosing the right integration for your use case.

<FeatureGrid columns={2}>
  <FeatureCard icon="browser" title="Hosted Sessions" description="Full verification flows with a pre-built, optimized UI. Users interact with Didit's hosted interface via redirect, iframe, or native SDK." href="/sessions-api/create-session" />

  <FeatureCard icon="server" title="Standalone APIs" description="Direct server-to-server API calls. You send data (images, documents, names) and receive structured verification results — no end-user UI involved." href="/standalone-apis/id-verification" />
</FeatureGrid>

***

## Hosted Sessions (Recommended for User-Facing Flows)

Hosted sessions are the **recommended approach** for most integrations. When you create a session, Didit generates a `verification_url` that you present to your user. The user completes the entire verification flow in Didit's optimized interface, and you receive the results via webhook or API.

### How It Works

<Steps>
  <Step title="Create Session">
    Your server calls `POST /v3/session/` with a workflow ID. Didit returns a `verification_url` and `session_token`.
  </Step>

  <Step title="Present to User">
    Redirect the user, embed via iframe, or initialize a native SDK using the session token.
  </Step>

  <Step title="User Completes Verification">
    The user follows the guided flow in Didit's optimized UI — ID capture, liveness, and any additional steps.
  </Step>

  <Step title="Receive Results">
    Didit sends a webhook to your server with the verification decision, or you poll via the retrieve API.
  </Step>
</Steps>

### Why Sessions Are Recommended

| Advantage | Details |
| - | - |
| **Optimized UX** | The verification interface is continuously A/B tested globally for the highest completion rates |
| **Camera handling** | Smart camera selection, auto-capture, quality checks, and device compatibility built in |
| **Guided flow** | Step-by-step instructions, real-time feedback, and error recovery for the user |
| **Multi-feature workflows** | Chain multiple features (ID + Liveness + AML + Phone + Email) in a single flow |
| **Security** | Anti-spoofing, active liveness detection, and device fingerprinting embedded in the flow |
| **Compliance** | Session-level audit trails, consent capture, and data retention policies handled automatically |
| **Localization** | 49 languages with automatic browser detection |
| **Mobile-native** | Native SDKs for iOS, Android, React Native, and Flutter |
| **No maintenance** | Didit handles all UI updates, browser/device bugs, and camera edge cases |

### When to Use Sessions

* **User onboarding / KYC** — New users sign up and need to verify their identity
* **Age verification** — Confirm users meet minimum age requirements
* **Re-verification** — Periodically re-verify existing users
* **Biometric authentication** — Users authenticate with their face for sensitive actions
* **Multi-step compliance** — Flows requiring ID + Liveness + AML + Phone in one go
* **Any scenario where the end user is present** and interacts directly

### Session Endpoints

| Endpoint | Purpose |
| - | - |
| [Create Session](/sessions-api/create-session) | Generate a verification URL for a user |
| [Retrieve Session](/sessions-api/retrieve-session) | Get the full results and decision for a session |
| [List Sessions](/sessions-api/list-sessions) | Query and filter all sessions |
| [Delete Session](/sessions-api/delete-session) | Remove a session and all associated data |
| [Generate PDF](/sessions-api/generate-pdf) | Export a verification report as PDF |
| [Share Session](/sessions-api/share-session/share) | Generate a share token for Reusable KYC with a partner |
| [Import Shared](/sessions-api/share-session/import) | Import a session shared by a partner (Reusable KYC) |

***

## Standalone APIs (For Server-to-Server Processing)

Standalone APIs let you call individual verification features **directly from your server** without any end-user UI. You send the data (images, documents, names) and receive structured results.

### How It Works

<Steps>
  <Step title="Send Data">
    Your server calls a standalone endpoint (e.g., `POST /v3/id-verification/`) with the required data — images, documents, or JSON fields.
  </Step>

  <Step title="Receive Results">
    Didit processes the request synchronously and returns structured verification results in the response.
  </Step>
</Steps>

### When to Use Standalone APIs

| Use Case | Example |
| - | - |
| **Backend processing** | You already have document images from your own capture UI and need to verify them |
| **Batch verification** | Processing bulk identity documents uploaded by an operations team |
| **Custom UX** | You've built your own capture flow and want to use Didit only for the analysis |
| **Server-to-server checks** | AML screening a list of customers, without any user interaction |
| **Automated pipelines** | CI/CD or cron-based compliance re-checks (e.g., daily AML monitoring) |
| **Integration with existing systems** | Connecting Didit's verification to your existing document management system |
| **Single-feature calls** | You only need one feature (e.g., just AML screening or just face matching) |

### Available Standalone APIs

**Identity & Documents**

| API | What It Does |
| - | - |
| [ID Verification](/standalone-apis/id-verification) | Extract and validate data from ID documents (front + back images) |
| [Proof of Address](/standalone-apis/proof-of-address) | Verify address documents (utility bills, bank statements, government docs) |
| [Database Validation](/core-technology/database-validation/overview) | Cross-check user data against government databases |

**Document AI**

| API | What It Does |
| - | - |
| [Document AI](/standalone-apis/document-ai) | Extract the fields you define from any document (PDF or image), with name matching and tampering checks |

**Biometrics & Face**

| API | What It Does |
| - | - |
| [Passive Liveness](/standalone-apis/passive-liveness) | Verify a real person is present (anti-spoofing) from a single image |
| [Face Match](/standalone-apis/face-match) | Compare two faces to determine if they are the same person |
| [Face Search](/standalone-apis/face-search) | Search for a face across all previously verified sessions (1:N) |
| [Age Estimation](/standalone-apis/age-estimation) | Estimate a person's age from a facial image |

**Compliance & Risk**

| API | What It Does |
| - | - |
| [AML Screening](/standalone-apis/aml-screening) | Screen persons or companies against sanctions, PEP, and watchlists |

**Business Verification (KYB)**

| API | What It Does |
| - | - |
| [KYB Registry Search](/standalone-apis/kyb-registry-search) | Search company registries by name, registration number, and country; up to \$0.50 per successful request |
| [KYB Registry Select](/standalone-apis/kyb-registry-select) | Retrieve the full registry profile (officers, beneficial owners, addresses) for a selected company |

***

## Side-by-Side Comparison

| | Hosted Sessions | Standalone APIs |
| - | - | - |
| **Integration effort** | Low — redirect, iframe, or SDK | Medium — you handle data capture and submission |
| **User interaction** | Yes — user completes flow in Didit UI | No — server-to-server only |
| **Camera/capture** | Handled by Didit (optimized) | You provide the images/data |
| **Multi-feature flows** | Yes — chain features in a workflow | One feature per API call |
| **UX optimization** | Continuously A/B tested | You control the UX |
| **Localization** | 49 languages, auto-detected | N/A (no UI) |
| **Webhooks** | Automatic status notifications | N/A (synchronous response) |
| **Response time** | Async (user completes at their pace) | Synchronous (seconds) |
| **Best for** | User-facing onboarding & verification | Backend processing & automation |
| **Console visibility** | Full session lifecycle in dashboard | Appears in Manual Checks section |

***

## Can I Use Both?

**Yes.** Many teams combine both approaches:

1. **Sessions for onboarding** — New users go through the full hosted verification flow during sign-up
2. **Standalone AML for ongoing monitoring** — A cron job re-screens all approved users nightly against updated watchlists
3. **Standalone Face Search for duplicate detection** — When a new session is approved, your server calls Face Search to check for duplicates
4. **Standalone ID Verification for operations** — Your compliance team uploads documents manually for edge-case reviews

### Example: Combined Architecture

| Your Application | Didit API | Type |
| - | - | - |
| **User sign-up flow** | Sessions API (hosted UI) | User-facing |
| **Nightly AML re-screening** | Standalone AML API | Server-to-server |
| **Ops team document review** | Standalone ID Verification API | Server-to-server |
| **Duplicate face detection** | Standalone Face Search API | Server-to-server |

***

## Getting Started

<FeatureGrid columns={2}>
  <FeatureCard icon="rocket" title="Quick Start with Sessions" description="Create your first hosted verification session in 5 minutes." href="/integration/api-full-flow" />

  <FeatureCard icon="key" title="API Authentication" description="Get your API key and start making authenticated requests." href="/getting-started/api-authentication" />

  <FeatureCard icon="webhook" title="Set Up Webhooks" description="Receive real-time notifications when verification status changes." href="/integration/webhooks" />

  <FeatureCard icon="diagram-project" title="Create a Workflow" description="Build custom verification flows in the Business Console." href="/console/workflows" />
</FeatureGrid>

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.