> ## 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. # List Sessions > Returns a paginated list of verification sessions for the application identified by your API key, newest first (descending `session_number`). **Canonical URL:** the route is `/v3/sessions/` (trailing slash). Requests to `/v3/sessions` without the slash receive a `301` redirect to the slashed URL with the query string preserved; most HTTP clients follow it transparently on GET. **When to use this endpoint vs webhooks.** Use this endpoint for dashboards, back-office search, reconciliation, and batch exports. Do not poll it to track the progress of individual verifications - configure [webhooks](/integration/webhooks) instead, which push `status.updated` events the moment a session changes. For one session's full result, call `GET /v3/session/{sessionId}/decision/`. **KYC and KYB rows.** `session_kind` selects which tables are listed: - `user` (default) - User Verification (KYC) sessions only. Backward-compatible behavior. - `business` - Business Verification (KYB) sessions only. Rows have a different, smaller shape (see the response schema). - `all` - both kinds in one response: the KYC page and the KYB page for the same `limit`/`offset` are concatenated in `results` (KYC rows first), so a page can contain up to `2 x limit` rows. `count` is the sum of both kinds and `next`/`previous` reflect the KYC-side pagination. For strict pagination of mixed data, call `user` and `business` separately. Every row carries a `session_kind` discriminator (`"user"` or `"business"`). **Pagination.** Standard limit/offset: `limit` (default 50) and `offset` (default 0), with `next`/`previous` ready-made page URLs. For KYC rows `count` is exact. For KYB rows `count` is computed with a bounded scan and is capped at 100 - when there are more than 100 matches it stays at 100, so iterate using `next` (or by checking whether a full page came back) rather than computing total pages from `count`. **Filter semantics.** All filters combine with AND and apply to KYC rows. When `session_kind` is `business` or `all`, the KYB side honors the shared parameters `vendor_data`, `status`, `workflow_id`, `country` (registry-company country code), `date_from`, `date_to`, `search` (company name, registration number — type registration numbers without separators, e.g. `DPC001` not `DPC-001` — vendor_data, session number, or session UUID), `warning`, and `organization_name`; the remaining KYC-only filters are ignored for KYB rows. Comma-separated parameters (`status`, `country`, `document_type`, `region`, `workflow_id`, `document_name`, `warning`, `organization_name`, `session_type`) match any of the listed values (OR within the parameter). `vendor_data` is an exact match - use `search` for partial matching. Unknown values in list filters simply return no rows (no error); malformed typed values (`date_from`, `date_to`, `didit_internal_id`, `api_service`, `session_kind`) return `400` with a per-field error object. **Search.** `search` adapts to the input: a full UUID looks up `session_id`; digits (with optional `+ - . space`) match session-number prefix, document/personal numbers, phone-number prefix, or `vendor_data`; values containing `@` match email prefixes; any other text matches names (accent-insensitive) and `vendor_data`. No fixed per-endpoint rate limit is enforced, but keep list polling infrequent and rely on webhooks for real-time updates. 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
{}
{title}
{} 
{prompt.trim()}
{}
Paste into
{agents.map(name => {name})}
; }; " \\ --data-urlencode "session_kind=all" \\ --data-urlencode "status=Approved,In Review" \\ --data-urlencode "date_from=2026-01-01" \\ --data-urlencode "limit=50" Response envelope: { "count": , "next": "", "previous": "", "results": [ ...rows ] } Every row has: - session_id (UUID), session_kind ("user" | "business"), session_number, status, vendor_data, created_at. KYC row extras: portrait_image, document_type, full_name, country (issuing state), phone_number, email_address, features, didit_internal_id. KYB row extras: workflow_type, workflow_label, company_name, registration_number, country (incorporation). Each row is a LIGHT projection. For the full feature payload of a row, call GET /v3/session/{session_id}/decision/ — see /sessions-api/retrieve-session. Failure modes: - 401 — invalid API key. - 403 — { "detail": "You do not have permission to perform this action." } when the key lacks read:sessions. - 400 — malformed UUIDs in filters are silently dropped (no error); malformed ISO dates return { "date_from": ["..."] }. Common patterns: - Build a dashboard: paginate with limit + offset, sort newest-first (server orders by -session_number within each kind). - Find pending review queue: status=In Review. - Find a specific entity's sessions: vendor_data=. - Refresh ongoing AML hits: filter by workflow_id of your AML workflow. For end-to-end Didit integration, paste in the full prompt at /integration/integration-prompt.`} /> ## Session kind filter Use the `session_kind` query parameter to choose which kind of sessions to return: | Value | Returns | | ---------------- | ---------------------------------------------------------------------------------------------------------- | | `user` (default) | Only User Verification (KYC) sessions. **Backward-compatible behavior** — omit `session_kind` to get this. | | `business` | Only Business Verification (KYB) sessions. | | `all` | Both User Verification and Business Verification sessions, concatenated. | Every row in the response includes `session_kind: "user" | "business"` so your client can switch on shape per row. ## Common filters These filters apply to both kinds (the user-only filters are ignored when `session_kind=business`, and vice versa): | Query parameter | Description | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `session_kind` | `user`, `business`, or `all`. Default `user`. | | `vendor_data` | Exact match on your identifier. | | `status` | `APPROVED`, `DECLINED`, `IN_REVIEW`, etc. | | `workflow_id` | Filter by the workflow used. | | `country` | Country code filter (user: `issuing_states`, business: `country_code`). | | `date_from`, `date_to` | Created-date window (ISO 8601). | | `search` | Substring match. For user: vendor\_data, full name, document number, phone, email. For business: vendor\_data, company name, registration number. | ## Examples ```bash theme={null} curl -G https://verification.didit.me/v3/sessions \ -H "x-api-key: YOUR_API_KEY" \ --data-urlencode "vendor_data=user-42" ``` **Response (truncated):** ```json theme={null} { "count": 3, "next": null, "previous": null, "results": [ { "session_id": "...", "session_kind": "user", "session_number": 1024, "session_url": "...", "portrait_image": "...", "document_type": "Passport", "full_name": "John Doe", "country": "GBR", "status": "APPROVED", "vendor_data": "user-42", "didit_internal_id": "...", "created_at": "2026-04-10T09:00:00Z", "features": "ID_VERIFICATION,LIVENESS,FACE_MATCH,AML", "phone_number": "+14155550123", "email_address": "jane@example.com", "additional_details": null } ] } ``` ```bash theme={null} curl -G https://verification.didit.me/v3/sessions \ -H "x-api-key: YOUR_API_KEY" \ --data-urlencode "session_kind=business" \ --data-urlencode "status=APPROVED" ``` **Response (truncated):** ```json theme={null} { "count": 1, "next": null, "previous": null, "results": [ { "session_id": "...", "session_kind": "business", "session_number": 89, "status": "APPROVED", "vendor_data": "biz-acme-001", "created_at": "2026-04-01T09:00:00Z", "workflow_id": "wf_kyb_standard", "workflow_type": "business", "workflow_label": "Standard KYB", "company_name": "Acme Corporation Limited", "registration_number": "12345678", "country": "GBR" } ] } ``` ```bash theme={null} curl -G https://verification.didit.me/v3/sessions \ -H "x-api-key: YOUR_API_KEY" \ --data-urlencode "session_kind=all" \ --data-urlencode "date_from=2026-04-01T00:00:00Z" ``` Returns User Verification and Business Verification rows in a single `results` array. Consumers should switch per row on `session_kind`. The `all` mode concatenates results rather than interleaving them by timestamp. For high-volume mixed traversals, call each kind separately and merge client-side. ## Row shapes differ by kind User Verification (KYC) rows include: `portrait_image`, `document_type`, `full_name`, `country` (issuing state), `phone_number`, `email_address`. Business Verification (KYB) rows include: `workflow_type`, `workflow_label`, `company_name`, `registration_number`, `country` (country of incorporation). Both carry: `session_id`, `session_kind`, `session_number`, `status`, `vendor_data`, `created_at`. See [sessions overview](/sessions-api/overview) for the complete feature matrix. ## Pagination Cursor-based via `page_size` and the `next` / `previous` pointers in the response. Default `page_size=25`, max `100`. ## Related * [Sessions overview](/sessions-api/overview) * [Retrieve session](/sessions-api/retrieve-session) — full decision for a single row * [Businesses overview](/entities/businesses/overview) — the Business entity aggregated across sessions * [Users overview](/entities/users/overview) — the User entity aggregated across sessions ## OpenAPI ````yaml GET /v3/sessions openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: Identity verification API. Authenticate with x-api-key header. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/sessions: get: tags: - Sessions summary: List verification sessions (KYC and/or KYB) with filters and pagination description: >- Returns a paginated list of verification sessions for the application identified by your API key, newest first (descending `session_number`). **Canonical URL:** the route is `/v3/sessions/` (trailing slash). Requests to `/v3/sessions` without the slash receive a `301` redirect to the slashed URL with the query string preserved; most HTTP clients follow it transparently on GET. **When to use this endpoint vs webhooks.** Use this endpoint for dashboards, back-office search, reconciliation, and batch exports. Do not poll it to track the progress of individual verifications - configure [webhooks](/integration/webhooks) instead, which push `status.updated` events the moment a session changes. For one session's full result, call `GET /v3/session/{sessionId}/decision/`. **KYC and KYB rows.** `session_kind` selects which tables are listed: - `user` (default) - User Verification (KYC) sessions only. Backward-compatible behavior. - `business` - Business Verification (KYB) sessions only. Rows have a different, smaller shape (see the response schema). - `all` - both kinds in one response: the KYC page and the KYB page for the same `limit`/`offset` are concatenated in `results` (KYC rows first), so a page can contain up to `2 x limit` rows. `count` is the sum of both kinds and `next`/`previous` reflect the KYC-side pagination. For strict pagination of mixed data, call `user` and `business` separately. Every row carries a `session_kind` discriminator (`"user"` or `"business"`). **Pagination.** Standard limit/offset: `limit` (default 50) and `offset` (default 0), with `next`/`previous` ready-made page URLs. For KYC rows `count` is exact. For KYB rows `count` is computed with a bounded scan and is capped at 100 - when there are more than 100 matches it stays at 100, so iterate using `next` (or by checking whether a full page came back) rather than computing total pages from `count`. **Filter semantics.** All filters combine with AND and apply to KYC rows. When `session_kind` is `business` or `all`, the KYB side honors the shared parameters `vendor_data`, `status`, `workflow_id`, `country` (registry-company country code), `date_from`, `date_to`, `search` (company name, registration number — type registration numbers without separators, e.g. `DPC001` not `DPC-001` — vendor_data, session number, or session UUID), `warning`, and `organization_name`; the remaining KYC-only filters are ignored for KYB rows. Comma-separated parameters (`status`, `country`, `document_type`, `region`, `workflow_id`, `document_name`, `warning`, `organization_name`, `session_type`) match any of the listed values (OR within the parameter). `vendor_data` is an exact match - use `search` for partial matching. Unknown values in list filters simply return no rows (no error); malformed typed values (`date_from`, `date_to`, `didit_internal_id`, `api_service`, `session_kind`) return `400` with a per-field error object. **Search.** `search` adapts to the input: a full UUID looks up `session_id`; digits (with optional `+ - . space`) match session-number prefix, document/personal numbers, phone-number prefix, or `vendor_data`; values containing `@` match email prefixes; any other text matches names (accent-insensitive) and `vendor_data`. No fixed per-endpoint rate limit is enforced, but keep list polling infrequent and rely on webhooks for real-time updates. operationId: get_v3_sessions parameters: - name: session_kind in: query required: false description: >- Which kind of sessions to list: `user` (KYC only, default), `business` (KYB only), or `all` (both, concatenated - see the description for merged-pagination semantics). Matching is case-insensitive (`BUSINESS` works); any value other than a case variant of `user`/`business`/`all` returns `400`. schema: type: string enum: - user - business - all default: user example: all - name: limit in: query required: false description: >- Maximum number of rows per page (per kind when `session_kind=all`). Defaults to 50. schema: type: integer default: 50 minimum: 1 example: 20 - name: offset in: query required: false description: >- Number of rows to skip before the first returned row. Defaults to 0. Prefer following the `next`/`previous` URLs from the response. schema: type: integer default: 0 minimum: 0 example: 20 - name: status in: query required: false description: >- Comma-separated list of session statuses to include, e.g. `Approved,In Review`. Values are case-sensitive; see [Verification Statuses](/integration/verification-statuses). Unknown values match nothing. schema: type: string example: Approved,In Review - name: vendor_data in: query required: false description: >- Exact-match filter on the `vendor_data` you sent at session creation (your own user/business identifier). For partial matches use `search` instead. schema: type: string example: your-user-id-123 - name: search in: query required: false description: >- Smart free-text search. A full UUID matches `session_id`; numeric input matches session-number prefix, document/personal numbers, phone prefix, or `vendor_data`; input containing `@` matches email prefixes; other text matches names (accent-insensitive) and `vendor_data`. Free text containing digits additionally matches document/personal-number search fields and session-number prefixes. schema: type: string example: jane doe - name: workflow_id in: query required: false description: >- Comma-separated workflow UUIDs (find them on the Workflows page in the Console). Malformed UUIDs in the list are ignored; if none are valid the result is empty. schema: type: string example: 9f9b1234-aaaa-bbbb-cccc-1234567890ab - name: date_from in: query required: false description: >- Only sessions created on or after this date (UTC), format `YYYY-MM-DD`. Malformed dates return `400`. schema: type: string format: date example: '2026-06-01' - name: date_to in: query required: false description: >- Only sessions created up to this date (UTC), format `YYYY-MM-DD`. For KYC rows the entire day is included; for KYB rows the comparison is `created_at <= date_to` (midnight), so use the next day's date to include a full day of KYB sessions. schema: type: string format: date example: '2026-06-30' - name: country in: query required: false description: >- Comma-separated country filter. For KYC rows: ISO 3166-1 alpha-3 codes of the ID document's issuing state (e.g. `ESP,USA`), which may differ from nationality. For KYB rows: the registry company's country code. schema: type: string example: ESP,USA - name: document_type in: query required: false description: >- Comma-separated ID-document type codes verified in the session (KYC rows only): `P` (Passport), `ID` (Identity Card), `DL` (Driver's License), `RP` (Residence Permit), `SSC` (Social Security Card), `HIC` (Health Insurance Card), `WP` (Work Permit), `TC` (Tax Card), `VISA`, `PSC` (Public Service Card), `BC` (Birth Certificate), `OTHER`. Note the response field `document_type` contains the display name, not the code. schema: type: string example: P,ID - name: document_name in: query required: false description: >- Exact document names; multiple names can be passed comma-separated, but the value is only split on commas when it contains more than one ` - ` separator (a lone name with an embedded comma is matched whole). Names are as recognized by document verification (front or back side), e.g. `Spain - Id Card (2021)`. KYC rows only. schema: type: string example: Spain - Id Card (2021) - name: region in: query required: false description: >- Comma-separated document region/state values (for documents issued per region, such as US driver's licenses). KYC rows only. schema: type: string example: CA,TX - name: didit_internal_id in: query required: false description: >- Filter by Didit's internal user identifier (the `didit_internal_id` response field) to list all sessions of one verified user. Must be a valid UUID; malformed values return `400`. KYC rows only. schema: type: string format: uuid example: d9e78474-6c8d-4f2a-bb90-6f5c2f3a1147 - name: session_type in: query required: false description: >- Comma-separated session creation channels: `API`, `HOSTED`, `MIGRATED`. The special value `ALL` (or omitting the parameter) disables the filter. KYC rows only. schema: type: string example: HOSTED - name: api_service in: query required: false description: >- Filter standalone API sessions by service. Invalid values return `400`. KYC rows only. schema: type: string enum: - ID_VERIFICATION - FACE_MATCH - AGE_ESTIMATION - FACE_SEARCH - POA - AML - KYB_REGISTRY - PASSIVE_LIVENESS - DATABASE_VALIDATION - PHONE_VERIFICATION - EMAIL_VERIFICATION example: AML - name: screened_full_name in: query required: false description: >- Accent-insensitive name search inside AML and database-validation screened data. When combined with `api_service=AML` or `api_service=DATABASE_VALIDATION`, the search is restricted to that feature's screened data. KYC rows only. schema: type: string example: Jane Doe - name: warning in: query required: false description: >- Comma-separated warning risk codes; returns sessions that raised any of them (e.g. `POSSIBLE_FRAUD`). Risk codes are listed per feature in the [warnings documentation](/integration/webhooks). Applies to KYC rows and, with business warning codes, to KYB rows. schema: type: string example: POSSIBLE_FRAUD - name: status_initialized_as_in_review in: query required: false description: >- When `true`, only sessions whose decision initially landed in `In Review` (useful to audit manual-review volume). KYC rows only. schema: type: boolean example: true - name: is_kyc_to_be_reviewed in: query required: false description: >- `true` returns sessions whose document verification is flagged for manual review; `false` returns sessions with document verification explicitly not flagged. Omit to disable. KYC rows only. schema: type: boolean example: true - name: euuid in: query required: false description: >- Filter by the end user's euuid (UUID assigned to the verifying user, used by Console deep links). Must be a valid UUID; malformed values return a 400 field error. KYC rows only. schema: type: string format: uuid example: 0f8fad5b-d9cb-469f-a165-70867728950e - name: organization_name in: query required: false description: >- Comma-separated organization names. Console-oriented; with an API key (already scoped to one application) it only matches your own organization's name. schema: type: string example: Acme Inc responses: '200': description: >- Paginated session list. `results` items are KYC rows, KYB rows, or both depending on `session_kind`; discriminate with each row's `session_kind` field. content: application/json: schema: type: object required: - count - next - previous - results properties: count: type: integer description: >- Number of sessions matching the filters. Exact for KYC rows; for KYB rows it is capped at 100 (use `next` to know whether more pages exist). For `session_kind=all` it is the sum of both kinds. example: 2 next: type: string format: uri nullable: true description: Absolute URL of the next page, or `null` on the last page. example: >- https://verification.didit.me/v3/sessions/?limit=20&offset=20 previous: type: string format: uri nullable: true description: >- Absolute URL of the previous page, or `null` on the first page. example: null results: type: array description: >- Session rows, newest first. With `session_kind=all`, KYC rows come first, then KYB rows. items: oneOf: - title: 'KYC session row (session_kind: user)' type: object description: >- Summary row for a User Verification (KYC) session. Identity fields (`full_name`, `country`, `document_type`, `portrait_image`, contact fields) are populated progressively as the user completes verification steps, and are `null` until the relevant step finishes. Fields restricted by the workflow's response-attributes configuration are also returned as `null`. required: - session_id - session_kind - session_number - session_url - portrait_image - document_type - full_name - country - status - vendor_data - didit_internal_id - created_at - features - phone_number - email_address - additional_details properties: session_id: type: string format: uuid description: >- Unique identifier of the verification session. Use it with `GET /v3/session/{sessionId}/decision/` to fetch the full decision payload. example: 5b3720ed-d429-42ef-b67f-37ea805f48ee session_kind: type: string enum: - user description: >- Row discriminator. Always `"user"` for KYC rows; Business Verification (KYB) rows have `"business"` and a different shape. example: user session_number: type: integer description: >- Human-friendly sequential number of the session within your application. Also matched by the `search` parameter. example: 720 session_url: type: string nullable: true description: >- Hosted verification URL the end user opens to complete the flow. `null` when the session has no hosted URL. example: https://verify.didit.me/session/CuXoBYCYVO5Y portrait_image: type: string nullable: true description: >- Expiring (presigned) URL of the best available portrait: the NFC chip photo when available, otherwise the ID document portrait, otherwise the liveness reference image. `null` until one of those exists. Download promptly; the link expires. example: >- https:///portraits/5b3720ed.jpg?X-Amz-Expires=3600&X-Amz-Signature=... document_type: type: string nullable: true enum: - Passport - Identity Card - Driver's License - Residence Permit - Health Insurance Card - Tax Card description: >- Human-readable type of the verified ID document. `null` before document verification completes, and also `null` after completion when the verified code has no display mapping (`SSC`, `WP`, `VISA`, `PSC`, `BC`, `OTHER`). Note: the `document_type` query parameter filters by short codes (`P`, `ID`, `DL`, `RP`, ...), not by these display values. example: Passport full_name: type: string nullable: true description: >- Best available full name for the session, resolved in order: ID document OCR, AML screened data, database-validation screened data, proof-of-address document, then the expected details provided at session creation. `null` when none is available yet. example: Jane Marie Doe country: type: string nullable: true description: >- ISO 3166-1 alpha-3 country associated with the session, resolved in order: ID document issuing state, database-validation issuing state, proof-of-address issuing state, expected details, then the verified phone's country. May differ from nationality. example: ESP status: type: string enum: - Not Started - In Progress - Approved - Declined - In Review - Expired - Abandoned - Kyc Expired - Resubmitted - Awaiting User description: >- Overall session status. See the [Verification Statuses](/integration/verification-statuses) page for the lifecycle. example: Approved vendor_data: type: string nullable: true description: >- Your own identifier for the end user, echoed back exactly as sent at session creation. example: your-user-id-123 didit_internal_id: type: string format: uuid nullable: true description: >- Didit's internal identifier for the verified user profile behind this session. Stable across multiple sessions of the same user; filterable via the `didit_internal_id` query parameter. example: d9e78474-6c8d-4f2a-bb90-6f5c2f3a1147 created_at: type: string format: date-time description: UTC timestamp when the session was created. example: '2026-06-09T12:26:54.328364Z' features: type: array description: >- Per-feature status for every verification step configured in the session's workflow, in workflow order. items: type: object required: - feature - status properties: feature: type: string enum: - ID_VERIFICATION - NFC - LIVENESS - FACE_MATCH - POA - QUESTIONNAIRE - EMAIL_VERIFICATION - PHONE - AML - IP_ANALYSIS - AGE_ESTIMATION - DATABASE_VALIDATION description: Verification feature identifier. example: ID_VERIFICATION status: type: string enum: - Not Finished - Approved - Declined - In Review - Resub Requested description: >- Status of this feature. `Not Finished` until the step completes. example: Approved phone_number: type: object nullable: true description: >- Phone associated with the session: the verified phone when phone verification ran, otherwise the contact phone provided at session creation. `null` when neither exists. required: - number - is_verified properties: number: type: string description: Phone number in E.164 format. example: '+14155552671' is_verified: type: boolean description: >- `true` only when the phone-verification feature approved this number. example: true email_address: type: object nullable: true description: >- Email associated with the session: the verified email when email verification ran, otherwise the contact email provided at session creation. `null` when neither exists. required: - email - is_verified properties: email: type: string format: email example: jane@example.com is_verified: type: boolean description: >- `true` only when the email-verification feature approved this address. example: true additional_details: type: object nullable: true description: >- Compact per-feature extras. Only features that produced data appear as keys; `null` when no feature produced extras. Fields excluded by the workflow's response-attributes configuration are omitted. properties: aml: type: object description: Present when AML screening ran. properties: total_hits: type: integer description: Number of AML screening hits. example: 0 entity_type: type: string description: Screened entity type. example: person is_adverse_media_fetched: type: boolean example: false screened_data: type: object description: >- Subset of the data that was screened. Only non-empty keys are included. properties: nationality: type: string example: ESP document_number: type: string example: XX1234567 date_of_birth: type: string example: '1990-05-21' database_validation: type: object description: Present when database validation ran. properties: validation_type: type: string example: DOCUMENT_VALIDATION match_type: type: string example: FULL_MATCH identification_number: type: string description: >- Tax, personal, or document number that was validated (first available). example: 12345678Z poa: type: object description: Present when proof of address ran. properties: document_type: type: string example: UTILITY_BILL issuer: type: string example: Energy Co address: type: string example: Calle Mayor 1, 28013 Madrid name_on_document: type: string example: Jane Marie Doe liveness: type: object description: Present when a liveness check ran. properties: method: type: string example: PASSIVE score: type: number description: >- Liveness confidence score, rounded to 2 decimals. example: 0.98 face_match: type: object description: Present when face match ran. properties: score: type: number description: >- Face-match similarity score, rounded to 2 decimals. example: 0.95 source_image: type: string description: >- Expiring (presigned) URL of the source face image. example: >- https:///faces/source.jpg?X-Amz-Expires=3600&... target_image: type: string description: >- Expiring (presigned) URL of the target face image. example: >- https:///faces/target.jpg?X-Amz-Expires=3600&... phone_verification: type: object description: Present when phone verification ran. properties: country_code: type: string description: >- ISO 3166-1 alpha-2 country of the phone number. example: US is_temporary: type: boolean example: false is_ported: type: boolean example: false is_blocked: type: boolean example: false email_verification: type: object description: Present when email verification ran. properties: is_breached: type: boolean example: false is_disposable: type: boolean example: false is_undeliverable: type: boolean example: false is_blocklisted: type: boolean example: false - title: 'KYB session row (session_kind: business)' type: object description: >- Summary row for a Business Verification (KYB) session. Returned only when `session_kind` is `business` or `all`. required: - session_id - session_kind - session_number - status - vendor_data - created_at - workflow_id - workflow_type - workflow_label - company_name - registration_number - country properties: session_id: type: string format: uuid description: >- Unique identifier of the business verification session. example: 8a1f63c2-1b9e-4f3a-9c41-2f6a1f0b7d52 session_kind: type: string enum: - business description: >- Row discriminator. Always `"business"` for KYB rows. example: business session_number: type: integer description: >- Human-friendly sequential number of the business session within your application. Numbered independently from KYC sessions. example: 42 status: type: string enum: - Not Started - In Progress - Approved - Declined - In Review - Expired - Abandoned - Kyc Expired - Resubmitted - Awaiting User description: >- Overall session status. See the [Verification Statuses](/integration/verification-statuses) page. example: Approved vendor_data: type: string nullable: true description: >- Your own identifier for the business, echoed back exactly as sent at session creation. example: your-company-id-77 created_at: type: string format: date-time description: UTC timestamp when the session was created. example: '2026-06-08T09:14:02.118450Z' workflow_id: type: string format: uuid nullable: true description: >- Identifier of the workflow this session was created with. example: 9f9b1234-aaaa-bbbb-cccc-1234567890ab workflow_type: type: string nullable: true description: Workflow type. `kyb` for business workflows. example: kyb workflow_label: type: string nullable: true description: Display name of the workflow. example: Standard KYB company_name: type: string nullable: true description: >- Name of the company being verified, from the registry company linked to the session. `null` until a company is selected. example: Acme Holdings S.L. registration_number: type: string nullable: true description: >- Company registration number from the registry company linked to the session. example: B12345678 country: type: string nullable: true description: >- Country code of the registry company linked to the session. example: ES examples: KYC sessions (default): summary: >- session_kind=user - one completed and one not-started session value: count: 2 next: null previous: null results: - session_id: 5b3720ed-d429-42ef-b67f-37ea805f48ee session_kind: user session_number: 720 session_url: https://verify.didit.me/session/CuXoBYCYVO5Y portrait_image: >- https:///portraits/5b3720ed.jpg?X-Amz-Expires=3600&X-Amz-Signature=... document_type: Passport full_name: Jane Marie Doe country: ESP status: Approved vendor_data: your-user-id-123 didit_internal_id: d9e78474-6c8d-4f2a-bb90-6f5c2f3a1147 created_at: '2026-06-09T12:26:54.328364Z' features: - feature: ID_VERIFICATION status: Approved - feature: LIVENESS status: Approved - feature: FACE_MATCH status: Approved - feature: AML status: Approved - feature: IP_ANALYSIS status: Approved phone_number: number: '+14155552671' is_verified: true email_address: email: jane@example.com is_verified: true additional_details: aml: total_hits: 0 entity_type: person is_adverse_media_fetched: false liveness: method: PASSIVE score: 0.98 face_match: score: 0.95 - session_id: 038ad62f-5ebd-46c2-afe9-4b2956bf687f session_kind: user session_number: 719 session_url: https://verify.didit.me/session/7RGKiO6ioGH6 portrait_image: null document_type: null full_name: null country: null status: Not Started vendor_data: your-user-id-124 didit_internal_id: eb4e679d-ca4b-461f-9685-687bac29ebdb created_at: '2026-06-09T08:02:23.343053Z' features: - feature: ID_VERIFICATION status: Not Finished - feature: LIVENESS status: Not Finished - feature: FACE_MATCH status: Not Finished - feature: AML status: Not Finished - feature: IP_ANALYSIS status: Not Finished phone_number: null email_address: null additional_details: null Mixed KYC + KYB (session_kind=all): summary: session_kind=all - KYC row followed by a KYB row value: count: 2 next: null previous: null results: - session_id: 5b3720ed-d429-42ef-b67f-37ea805f48ee session_kind: user session_number: 720 session_url: https://verify.didit.me/session/CuXoBYCYVO5Y portrait_image: null document_type: Identity Card full_name: Jane Marie Doe country: ESP status: In Review vendor_data: your-user-id-123 didit_internal_id: d9e78474-6c8d-4f2a-bb90-6f5c2f3a1147 created_at: '2026-06-09T12:26:54.328364Z' features: - feature: ID_VERIFICATION status: In Review - feature: LIVENESS status: Approved phone_number: null email_address: null additional_details: liveness: method: PASSIVE score: 0.98 - session_id: 8a1f63c2-1b9e-4f3a-9c41-2f6a1f0b7d52 session_kind: business session_number: 42 status: Approved vendor_data: your-company-id-77 created_at: '2026-06-08T09:14:02.118450Z' workflow_id: 9f9b1234-aaaa-bbbb-cccc-1234567890ab workflow_type: kyb workflow_label: Standard KYB company_name: Acme Holdings S.L. registration_number: B12345678 country: ES '301': description: >- Redirect to the canonical trailing-slash URL. Returned when the request path is `/v3/sessions` (no trailing slash); the `Location` header points to `/v3/sessions/` with the query string preserved. GET clients typically follow it automatically. '400': description: >- Invalid query parameter. The body is an object keyed by the offending parameter. content: application/json: examples: Invalid session_kind: summary: session_kind not one of user/business/all value: session_kind: Must be "user", "business", or "all". Invalid date: summary: Malformed date_from/date_to value: date_from: - Enter a valid date. Invalid didit_internal_id: summary: didit_internal_id is not a UUID value: didit_internal_id: - Enter a valid UUID. Invalid api_service: summary: api_service not in the allowed choices value: api_service: - >- Select a valid choice. FOO is not one of the available choices. '403': description: >- Missing, malformed, or revoked API key. This API never returns `401`; all authentication failures are `403`. content: application/json: examples: Forbidden: summary: Missing or invalid x-api-key value: detail: You do not have permission to perform this action. security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: >- curl -s 'https://verification.didit.me/v3/sessions/?status=Approved,In%20Review&date_from=2026-06-01&limit=20' \ -H 'x-api-key: YOUR_API_KEY' - lang: python label: Python source: |- import requests url = "https://verification.didit.me/v3/sessions/" headers = {"x-api-key": "YOUR_API_KEY"} params = { "session_kind": "user", # "user" (default) | "business" | "all" "status": "Approved,In Review", # comma-separated, OR within the list "date_from": "2026-06-01", "limit": 20, } while url: response = requests.get(url, headers=headers, params=params) response.raise_for_status() page = response.json() for session in page["results"]: print(session["session_kind"], session["session_id"], session["status"]) url, params = page["next"], None # "next" already carries the query string - lang: javascript label: JavaScript source: |- const params = new URLSearchParams({ session_kind: 'all', status: 'Approved,In Review', date_from: '2026-06-01', limit: '20', }); const response = await fetch( `https://verification.didit.me/v3/sessions/?${params}`, { headers: { 'x-api-key': process.env.DIDIT_API_KEY } }, ); if (!response.ok) throw new Error(`HTTP ${response.status}`); const { count, next, results } = await response.json(); for (const session of results) { // session.session_kind is "user" (KYC) or "business" (KYB) console.log(session.session_kind, session.session_id, session.status); } components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key ````