Get Started
Integrate / SDKs
User Verification
Business Verification
Transaction Monitoring
ChangelogRetrieve Session
Retrieve the complete decision report for a verification session — the rolled-up session status plus one report per verification feature the workflow executed. This is the canonical read endpoint for both User Verification (KYC) and Business Verification (KYB) sessions: the same path serves both, and the top-level session_kind discriminator tells you which shape you received ("user" or "business").
Every feature report is a plural array. V3 workflows are graphs that can run the same feature more than once, so each block (id_verifications, nfc_verifications, liveness_checks, face_matches, poa_verifications, phone_verifications, email_verifications, aml_screenings, ip_analyses, database_validations, questionnaire_responses) is a JSON array whose items each carry a node_id identifying the workflow graph node that produced them. Read NFC as response.nfc_verifications[0] — never as a singular nfc field. A block is null until the workflow has run that feature at least once; features the workflow does not include never appear with data.
When to call. The recommended pattern is event-driven: wait for the status.updated webhook that fires when the session reaches a decision (Approved, Declined, In Review), then call this endpoint once to fetch the full report. Polling also works — the endpoint can be called at any point in the session lifecycle and returns the data produced so far — but webhook-then-fetch is cheaper and faster. Media URLs in the response (document images, videos, PDFs) are short-lived presigned links: fetch them promptly or re-request the decision to get fresh ones, and do not persist them as long-term references.
Statuses. The top-level status is the session lifecycle status (Not Started, In Progress, Awaiting User, In Review, Approved, Declined, Resubmitted, Expired, Kyc Expired, Abandoned). Each feature item additionally carries its own feature-level status (Not Finished, Approved, Declined, In Review, …). A session can be Approved overall while an individual feature is In Review, depending on the workflow’s decision rules.
Authentication and visibility. Authenticate with the application API key in the x-api-key header (a console user Bearer token with the read:sessions permission also works). Only sessions owned by the authenticated application are visible. If your workflow restricts response attributes, non-allowed fields inside feature items are returned as null while status, warnings, and node_id are always preserved.
Rate limits. GET requests are limited to 600 per minute per API key. Exceeding the limit returns 429 with Retry-After and X-RateLimit-* headers.
Session kind
This endpoint works for both User Verification (KYC) and Business Verification (KYB) sessions. The response always includes a top-levelsession_kind field:
"user"— User Verification (KYC) session. Response carriesid_verifications,liveness_checks,face_matches,nfc_verifications,poa_verifications,database_validations."business"— Business Verification (KYB) session. Response carriesregistry_checks,document_verifications,key_people_checks.
aml_screenings, phone_verifications, email_verifications, questionnaire_responses, ip_analyses, reviews, contact_details — plus the common top-level fields (session_id, session_number, session_url, status, workflow_id, vendor_data, metadata, callback, features, expected_details, created_at, expires_at).
Didit looks up the session_id in both tables (User Verification sessions first, Business Verification sessions second) and returns whichever matches. UUIDs are unique per application — no ambiguity.
See sessions overview for the full matrix of kind-specific features.
Examples
- User Verification (KYC)
- Business Verification (KYB)
Handling the response on your side
Errors
| Status | Reason |
|---|---|
404 | No session with that session_id exists for this application (checked against both tables). |
403 | Missing read:sessions privilege. |
401 | Invalid API key. |
Related
- Sessions overview — kind discrimination and feature matrix.
- KYB response schema — field-by-field business decision reference.
- Verification statuses — status machine shared by both kinds.
- Webhooks — subscribe to
status.updatedfor both User and Business Verification sessions (filter onsession_kind).
Authorizations
Path Parameters
UUID of the verification session whose decision you want to retrieve. This is the session_id returned by POST /v3/session/. The same path works for both User Verification (KYC) and Business Verification (KYB) sessions — the server looks the id up in both tables.
Must be a valid UUID. The route only matches well-formed UUIDs, so a malformed value is rejected by the URL router before any application code runs and the response is a 404 HTML page rather than the JSON {"detail": ...} envelope shown below. Validate the UUID format client-side so you can distinguish an input error from a genuine missing-session 404.
"11111111-2222-3333-4444-555555555555"
Query Parameters
Comma-separated list of extra payload sections. The only supported value is events. When include=events is passed, the response additionally contains the session event timeline (events), the full activity log (activity_reviews), blocklist flags (blocklisted), a per-session cost_breakdown, workflow metadata (workflow_type, workflow_version, workflow_version_id), and session metadata (api_service — string or null, set only for standalone-API sessions; session_type — API, HOSTED, or MIGRATED; has_device_nfc_support — boolean). Two fields change relative to the plain shape: the top-level session_kind discriminator is omitted (the events shape only exists for user sessions), and the features array switches from plain strings to {feature, node_id} objects — where the email feature is reported as EMAIL instead of EMAIL_VERIFICATION. This expanded shape is primarily used by the Didit Console; most API integrations should omit the parameter. KYB limitation: include=events only applies to user (KYC) sessions. Business sessions (session_kind = "business") always return the standard business decision shape — events, activity_reviews, blocklisted, cost_breakdown and the extra workflow_*/session metadata are never returned for business sessions, and their features array stays a plain string array.
events "events"
Response
Full decision report. session_kind discriminates the two shapes: user sessions carry the KYC feature arrays shown below; business sessions instead carry registry_checks, document_verifications and key_people_checks alongside the shared arrays. Feature arrays are null until the workflow has run that feature; media URLs are short-lived presigned links.
The unique identifier of the session for which to retrieve verification results.
Discriminator indicating whether this is a User Verification (KYC) or Business Verification (KYB) session. When user, the KYC feature arrays (id_verifications, nfc_verifications, liveness_checks, face_matches, poa_verifications, database_validations, ...) apply and the business arrays are absent. When business, the payload instead carries registry_checks, document_verifications, key_people_checks plus the shared arrays (aml_screenings, phone_verifications, email_verifications, ip_analyses, questionnaire_responses). Omitted when include=events is passed — the events shape only exists for user sessions, so the discriminator is dropped from that variant.
user, business The number of the session.
The URL of the session.
Overall lifecycle status of the session — the rolled-up workflow result. Terminal values are Approved, Declined, In Review, Expired, Kyc Expired, and Abandoned; Not Started, In Progress, Awaiting User, and Resubmitted indicate the session is still moving through the workflow.
Not Started, In Progress, Awaiting User, In Review, Approved, Declined, Resubmitted, Expired, Kyc Expired, Abandoned Stable identifier of the workflow group that produced this session. Workflows are versioned — this value identifies the workflow itself, not the specific version.
List of verification features configured for this session, as display names: ID_VERIFICATION, NFC, LIVENESS, FACE_MATCH, POA, PHONE, EMAIL_VERIFICATION, AML, IP_ANALYSIS, DATABASE_VALIDATION, QUESTIONNAIRE, AGE_ESTIMATION, FACE_SEARCH (Business Verification sessions use the KYB feature set: KYB_REGISTRY, KYB_DOCUMENTS, KYB_KEY_PEOPLE, AML, PHONE, EMAIL_VERIFICATION, IP_ANALYSIS, QUESTIONNAIRE). With include=events each entry becomes an object {feature, node_id} instead of a plain string, and the email feature is renamed: it appears as EMAIL in events mode instead of the EMAIL_VERIFICATION used here.
The feature of the session.
The vendor data of the session.
The metadata of the session.
Expected user details supplied at session creation for cross-validation against the extracted document data. Echoes back exactly the keys that were provided; null when none were supplied.
Contact details supplied when the session was created (used for notification emails, prefilled phone/email verification, and communication language). null when neither an email nor a phone number was provided.
The callback URL of the session.
Array of ID verification (OCR) reports produced by ID-document steps in the workflow graph. Always a JSON array — read id_verifications[0] and iterate if your workflow can run more than one ID check (for example a primary check plus a step-up). null until at least one ID step has produced data. Each item is the full report, including node_id, feature-level status, extracted document fields, image URLs, quality scores, MRZ, address parsing, cross-session matches, and warnings[].
Array of NFC / ePassport reports produced by NFC steps in the workflow graph. This is always a JSON array, never a singular nfc object — read nfc_verifications[0] and iterate if your workflow can run NFC more than once. null until at least one NFC step has produced data. Each item is the full report, including node_id, feature-level status, chip_data, authenticity (SOD + DG integrity), certificate_summary, and warnings[].
Array of liveness reports produced by liveness steps in the workflow graph. Always a JSON array — never a singular liveness object. null until at least one liveness step has produced data. Each item is the full report, including node_id, feature-level status, method, score, reference_image, video_url, optional age_estimation, cross-session matches[], and warnings[].
Array of face-match reports produced by face-match steps in the workflow graph. Always a JSON array — never a singular face_match object. null until at least one face-match step has produced data. Each item is the full report, including node_id, feature-level status, similarity score, source_image, target_image, and warnings[].
Array of phone verification reports — always a JSON array, never a singular phone object. null until at least one phone step has produced data. Each item is the full report, including node_id, feature-level status, the phone number and country metadata, lifecycle[], matches[], and warnings[].
Array of email verification reports — always a JSON array, never a singular email object. null until at least one email step has produced data. Each item is the full report, including node_id, feature-level status, the email address, breach data, lifecycle[], matches[], and warnings[].
Array of Proof of Address (POA) reports — always a JSON array, never a singular poa object. null until at least one POA step has produced data. Each item is the full report, including node_id, feature-level status, the document file URL, issuer, dates, parsed address, and warnings[].
Array of questionnaire response reports — always a JSON array, never a singular questionnaire object. null until at least one questionnaire step has produced data. Each item is the full report, including node_id, the questionnaire metadata, sections with form elements, and the user's answers.
Array of AML screening reports — always a JSON array, never a singular aml object. null until at least one AML step has produced data. Each item is the full report, including node_id, feature-level status, total_hits, entity_type, hits[], score, screened_data, is_ongoing_monitoring_enabled, and warnings[].
Array of Device & IP Analysis reports — always a JSON array, never a singular ip_analysis object. null until at least one IP-analysis step has produced data. Each item is the full report, including node_id, feature-level status, IP and geolocation data, device fingerprint, and warnings[]. Entries with duplicate (node_id, ip_address, device_fingerprint) are deduplicated server-side.
Array of Database Validation reports — always a JSON array, never a singular database_validation object. null until at least one DB validation step has produced data. Each item is the full report, including node_id, feature-level status, screened_data, the per-service validations[] (each with its registry source_data), and warnings[]. The screened_data and source_data fields vary by country:
ARG (Argentina): screened_data: {document_number, selfie, gender, first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name, date_of_birth, date_of_death, tax_id, tax_id_type, face_match_score, sit_1_since, banks, last_position, highest_position, rejected_checks}. Uses RENAPER biometric face-match validation. Gender is auto-inferred from face analysis or given name when not present in the document (e.g., driver licenses)
BOL (Bolivia): screened_data: {document_number, date_of_birth, first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name, date_of_birth, gender}
BRA (Brazil): screened_data: {tax_number, first_name, last_name, date_of_birth}. source_data always includes {identification_number, first_name, last_name, date_of_birth, lgpd_minor, minor_under_18, minor_under_16} for successful CPF matches. Successful adult lookups set those flags to false. The Receita Federal Consulta CPF service may return HTTP 422 (minor under 18) or 451 (under 16) with LGPD-withheld data; in those cases source_data sets the minor flags to true as appropriate, includes the upstream HTTP status, and field-level validation is no_match. See the Brazil section of the Database Validation Outcome Codes reference for the full code list.
CHL (Chile): screened_data: {personal_number, first_name, last_name, date_of_birth}. source_data: {identification_number, first_name, last_name, date_of_birth, gender}
COL (Colombia): screened_data: {document_number, document_type, first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name, date_of_birth, document_type}
CRI (Costa Rica): screened_data: {personal_number, first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name}
DOM (Dominican Republic): screened_data: {personal_number}. source_data: {identification_number} (returns valid/invalid only)
ECU (Ecuador): screened_data: {personal_number, first_name, last_name}. source_data: {identification_number, first_name, last_name, street, formatted_address, gender, nationality, education, marital_status, spouse, mother_name, father_name, profession}
ESP (Spain): screened_data: {personal_number, document_type, expiration_date, first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name, document_type, expiration_date}
GTM (Guatemala): screened_data: {document_number, first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name}
HND (Honduras): screened_data: {document_number, first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name}
MEX (Mexico): screened_data: {personal_number (CURP), first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name, date_of_birth, gender, nationality, curp_status, state_of_birth, doc_probatorio, registration_year, registration_state, registration_municipality, num_acta, crip, issuing_state_code, foreign_registry_number, folio_carta, folio_certificado}. Uses the RENAPO civil registry. A separate INE validity-check service is also available for MEX as an additional one-by-one validation.
PAN (Panama): screened_data: {personal_number, selfie}. source_data: {identification_number}. Uses SIB biometric validation
PER (Peru): screened_data: {personal_number (DNI), first_name, last_name}. source_data: {identification_number, first_name, last_name, paternal_name, maternal_name, verification_number, verification_letter}
PRY (Paraguay): screened_data: {document_number, first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name}
SLV (El Salvador): screened_data: {document_number, date_of_birth, first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name}
URY (Uruguay): screened_data: {personal_number, date_of_birth, first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name}
VEN (Venezuela): screened_data: {document_number, first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name, gender, date_of_birth, document_type}
Timestamp at which the session was created (ISO 8601, UTC).
Timestamp at which this session is scheduled to expire. Set on User Verification (KYC) sessions when an expiration was configured at creation time (or once Approved status triggers KYC expiry computation). null for sessions without a configured expiration, and for kinds that do not use expiry (e.g. Business Verification (KYB) sessions that never received an expires_at).
Company registry checks. Present only when session_kind = business. Each item wraps the full company-registry payload.
Aggregate key-people checks. Present only when session_kind = business. Each item uses the two-bucket shape (registry, submitted, ubo_kyc_summary).
Document verification checks grouped by workflow node. Present only when session_kind = business.
Whether the session was created by a live application (live) or a sandbox application (sandbox). Sandbox sessions are free, fully simulated, and never bill credits.
live, sandbox