> ## 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-call from $0.30.

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

### 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 } }

### 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                         |

**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 |

***

## 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>

***