Didit Session API
The Session API from Didit — 1 operation(s) for session.
OpenAPI Specification
openapi: 3.0.0
info:
version: 3.0.0
title: Didit Verification Billing Session API
description: Identity verification API. Authenticate with x-api-key header.
servers:
- url: https://verification.didit.me
tags:
- name: Session
paths:
/v3/session/{sessionId}/decision/:
get:
summary: Retrieve the full decision for a verification session
description: '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`, `document_ai_documents`, `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.'
operationId: get_v3_session_decision
responses:
'200':
description: '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.'
content:
application/json:
examples:
Example:
summary: Full Example
value:
session_id: 11111111-2222-3333-4444-555555555555
session_kind: user
session_number: 43762
session_url: https://verify.didit.me/session/11111111-2222-3333-4444-555555555555
status: In Review
environment: live
workflow_id: 11111111-2222-3333-4444-555555555555
features:
- ID_VERIFICATION
- NFC
- LIVENESS
- FACE_MATCH
- POA
- PHONE
- DATABASE_VALIDATION
- AML
- IP_ANALYSIS
vendor_data: 11111111-1111-1111-1111-111111111111
metadata:
user_type: premium
account_id: ABC123
expected_details:
first_name: Carmen
last_name: Española Española
contact_details:
email: carmen@example.com
email_lang: es
send_notification_emails: false
phone: null
callback: https://verify.didit.me/
id_verifications:
- node_id: feature_ocr_1
status: Approved
document_type: Identity Card
document_subtype: ID_CARD_GENERIC
document_number: CAA000000
personal_number: 99999999R
portrait_image: https://<media-host>/portrait.jpg
front_image: https://<media-host>/front.jpg
front_video: https://<media-host>/front.mp4
back_image: https://<media-host>/back.jpg
back_video: https://<media-host>/back.mp4
full_front_image: https://<media-host>/full_front.jpg
full_back_image: https://<media-host>/full_back.jpg
front_image_camera_front: https://<media-host>/front_camera_front.jpg
back_image_camera_front: https://<media-host>/back_camera_front.jpg
date_of_birth: '1980-01-01'
age: 45
expiration_date: '2031-06-02'
date_of_issue: '2021-06-02'
issuing_state: ESP
issuing_state_name: Spain
first_name: Carmen
last_name: Española Española
full_name: Carmen Española Española
gender: F
address: Avda de Madrid 34, Madrid, Madrid
formatted_address: Avda de Madrid 34, Madrid, Madrid 28822, Spain
place_of_birth: Madrid
marital_status: Single
nationality: ESP
extra_fields:
dl_categories: []
blood_group: null
mrz:
surname: ESPANOLA ESPANOLA
name: CARMEN
country: ESP
nationality: ESP
birth_date: '800101'
expiry_date: '310602'
sex: F
document_type: ID
document_number: CAA000000
optional_data: 99999999R
optional_data_2: ''
birth_date_hash: '4'
expiry_date_hash: '8'
document_number_hash: '4'
final_hash: '1'
personal_number: 99999999R
warnings: []
errors: []
mrz_type: TD1
mrz_string: 'IDESPCAA000000499999999R<<<<<<
8001014F3106028ESP<<<<<<<<<<<1
ESPANOLA<ESPANOLA<<CARMEN<<<<<'
mrz_key: CAA000000480010143106028
parsed_address:
city: Madrid
label: Spain ID Card Address
region: Madrid
country: ES
category: Residential
street_1: Avda de Madrid 34
street_2: null
is_verified: true
postal_code: '28822'
raw_results:
types:
- street_address
geometry:
location:
lat: 37.4222804
lng: -122.0843428
viewport:
northeast:
lat: 37.4237349802915
lng: -122.083183169709
southwest:
lat: 37.4210370197085
lng: -122.085881130292
location_type: ROOFTOP
place_id: ChIJN1t_tDeuEmsRUsoyG83frY4
formatted_address: Avda de Madrid 34, 28822 Madrid, Spain
navigation_points:
- location:
latitude: 37.4222804
longitude: -122.0843428
address_components:
- types:
- street_number
long_name: '34'
short_name: '34'
- types:
- route
long_name: Avda de Madrid
short_name: Avda de Madrid
- types:
- locality
- political
long_name: Madrid
short_name: Madrid
- types:
- country
- political
long_name: Spain
short_name: ES
- types:
- postal_code
long_name: '28822'
short_name: '28822'
address_type: Avda
document_location:
latitude: 37.4222804
longitude: -122.0843428
formatted_address: Avda de Madrid 34, 28822 Madrid, Spain
front_image_camera_front_face_match_score: 95.5
back_image_camera_front_face_match_score: 93.2
front_image_quality_score:
focus_score: 85.3
brightness_score: 92.1
brightness_issue: ok
is_document_fully_visible: true
resolution_score: 72.4
overall_score: 88.7
back_image_quality_score:
focus_score: 79.1
brightness_score: 90.5
brightness_issue: ok
is_document_fully_visible: true
resolution_score: 72.4
overall_score: 85.2
extra_files:
- https://<media-host>/extra_id_verification.jpg
matches:
- session_id: 7d4f1f60-9c2e-4b8a-8f3d-2a1b5c6d7e8f
session_number: 1234
vendor_data: user_ref_001
verification_date: '2024-06-15T10:30:00Z'
user_details:
name: John Smith
document_type: ID
document_number: CLM148418
status: Approved
is_blocklisted: false
api_service: null
front_image_url: https://<media-host>/document_front.jpg
- session_id: b2c8e4d1-6a3f-4e7b-95c0-1d8f2a6b4c9e
session_number: 1235
vendor_data: null
verification_date: '2024-05-20T14:45:00Z'
user_details:
name: John Smith
document_type: ID
document_number: CLM148418
status: Declined
is_blocklisted: true
api_service: ID_VERIFICATION
front_image_url: https://<media-host>/document_front_2.jpg
warnings:
- feature: ID_VERIFICATION
risk: QR_NOT_DETECTED
additional_data: null
log_type: information
short_description: QR not detected
long_description: The system couldn't find or read the QR code on the document, which is necessary for document verification. This could be due to poor image quality or an unsupported document type.
node_id: feature_ocr_1
nfc_verifications:
- node_id: feature_nfc_1
status: In Review
portrait_image: https://<media-host>/portrait.jpg
signature_image: https://<media-host>/signature.jpg
chip_data:
document_type: ID
issuing_country: ESP
document_number: '123456789'
expiration_date: '2030-01-01'
first_name: John
last_name: Smith
birth_date: '1990-05-15'
gender: M
nationality: ESP
address: CALLE MAYOR 123 4B, MADRID, MADRID
place_of_birth: MADRID, MADRID
authenticity:
sod_integrity: true
dg_integrity: true
certificate_summary:
issuer: 'Common Name: CSCA SPAIN, Serial Number: 3, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES'
subject: 'Common Name: DS n-eID SPAIN 2, Organizational Unit: PASSPORT, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES'
serial_number: '118120836164494130086420187336801405660'
not_valid_after: '2031-02-18 10:21:11'
not_valid_before: '2020-11-18 10:21:11'
warnings:
- feature: NFC
risk: DATA_INCONSISTENT
additional_data: null
log_type: warning
short_description: OCR and NFC mrz code extracted are not the same
long_description: The Optical Character Recognition (OCR) data and the NFC chip data don't match, indicating potential document tampering or data inconsistency.
node_id: feature_nfc_1
liveness_checks:
- node_id: feature_liveness_1
status: Approved
method: ACTIVE_3D
score: 89.92
reference_image: https://<media-host>/reference.jpg
video_url: https://<media-host>/video.mp4
age_estimation: 24.3
matches:
- session_id: 7d4f1f60-9c2e-4b8a-8f3d-2a1b5c6d7e8f
session_number: 1234
vendor_data: user_ref_001
verification_date: '2024-06-15T10:30:00Z'
user_details:
full_name: John Smith
document_type: ID
document_number: CLM148418
status: Approved
is_blocklisted: false
is_allowlisted: false
api_service: null
source: session
match_image_url: https://<media-host>/face_match.jpg
similarity_percentage: 98.5
- session_id: 3e9a7c21-5b48-4f0e-9c6a-8d2f4b1e0a35
session_number: 1100
vendor_data: customer_xyz
verification_date: '2024-04-10T09:15:00Z'
user_details:
full_name: John Smith
document_type: P
document_number: DZ8375806
status: Approved
is_blocklisted: false
is_allowlisted: false
api_service: PASSIVE_LIVENESS
source: session
match_image_url: https://<media-host>/face_match_2.jpg
similarity_percentage: 95.2
warnings:
- feature: LIVENESS
risk: LOW_LIVENESS_SCORE
additional_data: null
log_type: information
short_description: Low liveness score
long_description: The liveness check resulted in a low score, indicating potential use of non-live facial representations or poor-quality biometric data.
node_id: feature_liveness_1
face_quality: null
face_luminance: null
face_matches:
- node_id: feature_face_match_1
status: In Review
score: 65.43
source_image_session_id: null
source_image: https://<media-host>/source-image.jpg
target_image: https://<media-host>/target-image.jpg
warnings:
- feature: FACEMATCH
risk: LOW_FACE_MATCH_SIMILARITY
additional_data: null
log_type: warning
short_description: Low face match similarity
long_description: The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch.
node_id: feature_face_match_1
phone_verifications:
- node_id: feature_phone_1
status: Approved
phone_number_prefix: '+34'
phone_number: '600600600'
full_number: '+34600600600'
country_code: ES
country_name: Spain
carrier:
name: Orange
type: mobile
is_disposable: false
is_virtual: false
verification_method: sms
verification_attempts: 1
verified_at: '2024-07-28T06:47:35.654321Z'
lifecycle:
- type: PHONE_VERIFICATION_MESSAGE_SENT
timestamp: '2025-08-24T09:12:39.580554+00:00'
details:
status: Success
reason: null
channel: sms
actual_channel: sms
fee: 0.1
- type: VALID_CODE_ENTERED
timestamp: '2025-08-24T09:12:39.662157+00:00'
details:
code_tried: '123456'
status: Approved
fee: 0
- type: PHONE_VERIFICATION_APPROVED
timestamp: '2025-08-24T09:12:39.684292+00:00'
details: null
fee: 0
warnings: []
matches:
- session_id: null
session_number: null
vendor_data: null
verification_date: null
phone_number: '+34600000000'
status: null
is_blocklisted: true
api_service: null
source: list_entry
email_verifications:
- node_id: feature_email_1
status: Approved
email: test@example.com
is_breached: true
breaches:
- name: TAPAirPortugal
domain: flytap.com
logo_path: https://logos.haveibeenpwned.com/TAPAirPortugal.png
breach_date: '2022-08-25'
description: In August 2022, the Portuguese airline <a href="https://www.bleepingcomputer.com/news/security/ragnar-locker-ransomware-claims-attack-on-portugals-flag-airline/" target="_blank" rel="noopener">TAP Air Portugal was the target of a ransomware attack perpetrated by the Ragnar Locker gang</a> who later leaked the compromised data via a public dark web site. Over 5M unique email addresses were exposed alongside other personal data including names, genders, DoBs, phone numbers and physical addresses.
is_verified: true
data_classes:
- dates_of_birth
- email_addresses
- genders
- names
- nationalities
- phone_numbers
- physical_addresses
- salutations
- spoken_languages
breach_emails_count: 6083479
is_disposable: false
is_undeliverable: false
verification_attempts: 1
verified_at: '2025-09-15T17:36:19.963451Z'
warnings:
- feature: EMAIL
risk: BREACHED_EMAIL_DETECTED
additional_data: null
log_type: information
short_description: Breached email detected
long_description: This email address was found in one or more known data breaches.
node_id: feature_email_1
lifecycle:
- type: EMAIL_VERIFICATION_MESSAGE_SENT
timestamp: '2025-09-15T17:36:19.792684+00:00'
details:
status: Success
reason: null
fee: 0.03
- type: VALID_CODE_ENTERED
timestamp: '2025-09-15T17:36:19.963427+00:00'
details:
code_tried: '123456'
status: Approved
fee: 0
- type: EMAIL_VERIFICATION_DECLINED
timestamp: '2025-09-15T17:36:20.081471+00:00'
details:
reason: BREACHED_EMAIL_DETECTED
fee: 0
matches:
- session_id: null
session_number: null
vendor_data: null
verification_date: null
email: test@example.com
status: null
is_blocklisted: true
api_service: null
source: list_entry
poa_verifications:
- node_id: feature_poa_1
status: Declined
document_file: https://<media-host>/poa_document.pdf
issuing_state: AR
document_type: UTILITY_BILL
document_subtype: null
document_language: es
document_metadata:
file_size: 1000
content_type: application/pdf
creation_date: '2021-01-01'
modified_date: '2021-01-01'
overlay_manipulation: null
creator: null
producer: PDF Generator
software: null
encryption: null
is_signed: false
is_tampered: false
signature_info: null
exif_original_date: null
exif_digitized_date: null
processed_by_known_editor: false
has_different_creation_mod_date: true
issuer: Aguas del Norte
issue_date: '2021-02-01'
expiration_date: null
poa_address: AVDA. MONSEÑOR TAVELLA N° 3396, SALTA
poa_formatted_address: Av. Monseñor Tavella 3396, A4400 Salta, Argentina
poa_parsed_address:
address_type: Avenida
street_1: Avenida Monseñor Tavella 3396
street_2: null
city: Salta
region: Salta
country: AR
postal_code: A4400
document_location:
latitude: -24.8208664
longitude: -65.4131
name_on_document: Fernando De Lima
name_match_score_expected_details: null
name_match_score_id_verification: 38.5
expected_details_address: null
expected_details_formatted_address: null
expected_details_parsed_address: {}
extra_fields:
bank_account_number: '1234567890'
bank_iban: null
bank_sort_code: null
bank_routing_number: null
bank_swift_bic: null
bank_branch_name: null
bank_branch_address: null
document_phone_number: '+5491112345678'
additional_names: []
extra_files:
- https://<media-host>/extra_poa.pdf
warnings: []
document_ai_documents:
- status: Approved
node_id: feature_document_ai_1
items:
- uuid: c1a2b3c4-d5e6-7f80-9a1b-2c3d4e5f6071
node_id: feature_document_ai_1
document_key: proof_of_funds
original_filename: bank_statement.pdf
file_size: 184320
file_url: https://<media-host>/document_ai/proof_of_funds.pdf
status: Approved
extracted_data:
account_holder: John Doe
balance: 15230.55
currency: EUR
statement_date: '2026-05-31'
fields:
- key: account_holder
name: Account holder
instruction: Extract the full name of the account holder.
type: text
required: true
- key: balance
name: Closing balance
instruction: Extract the closing balance amount.
type: number
required: true
document_metadata:
is_tampered: false
cross_check_result: null
created_at: '2026-06-01T12:34:56Z'
warnings: []
questionnaire_responses:
- node_id: feature_questionnaire_1
questionnaire_id: 9f7485e0-b00b-4d56-9d3e-7859b68d1213
title: Source of Funds
description: Reply to this questionnaire to help us understand the source of funds.
languages:
- en
default_language: en
is_active: true
is_simple_questionnaire: true
questionnaire_group_id: 2b6a9d40-13a8-4b1e-9a6c-3f1d2e4b5a60
version: 1
published_at: '2025-11-02T09:14:55.000000Z'
sections:
- title: null
description: null
items:
- uuid: 618636d9-7d5c-41ce-b8d0-1ab2a4be20db
value: question_1
element_type: DROPDOWN
is_required: true
title: What is your primary source of funds?
description: null
placeholder: null
choices:
- label: Salary
value: salary
- label: Business Income
value: business_income
- label: Savings
value: savings
- label: Investments
value: investments
- label: Sale of Asset
value: sale_of_asset
- label: Inheritance/Gift
value: inheritance_gift
- label: Pension
value: pension
- label: Crypto Proceeds
value: crypto_proceeds
- label: Other
value: other
requires_text_input: true
max_files: 1
answer:
value: salary
required_if: null
repeatable_config: null
- uuid: 2d16b527-72be-42e0-8e96-b164b818386c
value: question_2
element_type: LONG_TEXT
is_required: true
title: Provide details of the primary source.
description: null
placeholder: null
choices: null
max_files: 1
answer:
value: Test answer
required_if: null
repeatable_config: null
- uuid: a9239b7c-fbfb-4ea7-b7e4-c835cd4016e0
value: question_3
element_type: DROPDOWN
is_required: true
title: What is your annual income range (pre-tax)?
description: null
placeholder: null
choices:
- label: Less than $25,000
value: <25k
- label: $25,000 - $50,000
value: 25k-50k
- label: $50,001 - $100,000
value: 50k-100k
- label: $100,001 - $250,000
value: 100k-250k
- label: More than $250,000
value: '>250k'
max_files: 1
answer:
v
# --- truncated at 32 KB (322 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/didit/refs/heads/main/openapi/didit-session-api-openapi.yml