Skip to main content
POST
Python
Previewing does not change the session or send an email. After reviewing the response, confirm with Update Session Status and pass the returned preview_token as email_preview_token. The receipt expires after 15 minutes. A changed or expired receipt returns 409 before the session is changed or an email is sent. Generate a fresh preview after a conflict. Existing API integrations may omit the receipt; the console supplies it when confirming a preview. The sender and branding follow your existing white-label configuration. Message content comes from the translated verification template; arbitrary subjects, message bodies and action URLs are not accepted as template inputs.

Who receives the email

email_address is optional. Without it, the email goes to the person’s own address: the one they verified in an email verification step of the flow, else the one given in contact_details when the session was created. An address you pass in email_address wins. recipient_source tells you which address applies:

Whether the email goes out

will_be_sent is true when confirming the resubmission with send_email: true sends the email. When it is false, not_sent_reason says why:

Confirm the resubmission

Call Update Session Status with these fields: The response’s language is the language the email is written in: English when the one you asked for is not offered.

Repeated backend-only resubmissions

When every step to resubmit runs without the person (AML, Database Validation or IP Analysis), a session can be resubmitted for them only once every 30 seconds. Within that window the preview returns 429, as Update Session Status would, with the wait in the Retry-After header.

Authorizations

x-api-key
string
header
required

Your application's API key, from Developers -> API keys in the Business Console. The primary key has full access. A named key can be scoped: none, read or write per resource, limited to some workflows or to approved sessions, to a list of IP addresses, and to an expiry date. 401 means the key is wrong, revoked or expired; 403 means no key was sent, the key has no access to this resource or action, or the request came from an address outside its IP list; 404 on a session route means the session is outside the key's workflows or statuses. A key without media access receives image, video and PDF URLs as null, and a key without sessions write receives session links and tokens as null. See https://docs.didit.me/console/api-keys.

Headers

Idempotency-Key
string

Optional retry-safety key you choose for one operation, up to 255 characters (a UUID works). A request repeated with the same key, endpoint, query and body is answered with the first response, same status and same body, and runs and bills nothing a second time. The same key with another endpoint, query or body returns 409 idempotency_key_reused, and while the first request is still running, 409 idempotency_key_in_progress with Retry-After. A failed request (any 4xx or 5xx) is not stored, so you can send it again with the same key. Keys belong to your application, whether you call with an API key or an access token. See Retries and idempotency.

Required string length: 1 - 255

Path Parameters

sessionId
string<uuid>
required

UUID of the verification session to update. Accepts both user (KYC) and business (KYB) session IDs — the service resolves the ID across both session types.

Example:

"11111111-2222-3333-4444-555555555555"

Body

application/json
nodes_to_resubmit
object[]

Steps to preview, using the same validation, selection and workflow ordering as a resubmission. Omit to auto-select recorded attempts needing resubmission.

email_address
string<email>

Optional. Send the email to this address instead of the person's own. Without it, the recipient is the address the person verified in the flow, else the one given in contact_details. No email is sent by this call.

Example:

"user@example.com"

email_language
string
default:en

Language for the notification email. Accepts any string at schema level; unsupported codes silently fall back to English (en).

Example:

"en"

Response

Preview only. The session is unchanged and no email is sent.

recipient
string
required

The address the email goes to. An empty string when no address is known for the person: then no email can be sent and preview_token is empty too. Pass it as email_address when you confirm.

Example:

"person@example.com"

recipient_source
enum<string>
required

Where recipient comes from. request: the email_address you passed. email_verification: the address the person verified in an email verification step of the flow. contact_details: the address given in contact_details when the session was created. An empty string when there is no address.

Available options:
email_verification,
contact_details,
request,
Example:

"email_verification"

sender
string
required

The From header the email goes out with.

Example:

"Example App <no-reply@mail.example.com>"

sender_name
string
required

The display name part of sender.

Example:

"Example App"

sender_email
string<email>
required

The address part of sender.

Example:

"no-reply@mail.example.com"

sender_kind
enum<string>
required

customer: the email goes out from your application's verified sender domain (white label). didit: it goes out from Didit's own sender.

Available options:
customer,
didit
Example:

"customer"

subject
string
required

The subject line exactly as it is sent.

Example:

"Action Required: Complete your verification in Example App"

html
string
required

The email's HTML exactly as it is sent, with its logo embedded as a data URL. Render it in a sandboxed frame, never directly in your application DOM.

Example:

"<!DOCTYPE html><html><body>...</body></html>"

text
string
required

The email's words as plain text, as the person's Messages thread keeps them, for a compact preview (the HTML stays the email the person receives).

Example:

"Almost there\n\nSome steps need to be completed again.\nHere’s what to fix:\n\nhttps://verify.didit.me/session/abc123"

language
string
required

The language the email is written in. English (en) when the email_language you asked for is not offered.

Example:

"en"

will_be_sent
boolean
required

Whether confirming the change with send_email: true sends this email. false when not_sent_reason is set.

Example:

true

not_sent_reason
enum<string> | null
required

Why confirming would send no email, or null when it will be sent. no_user_action: every selected step runs without the person, so the resubmission finishes on its own and no email goes out. no_recipient: no address is known for the person and you passed none. sandbox: a sandbox session whose recipient has not opted into sandbox email delivery, so the send is only simulated.

Available options:
no_user_action,
no_recipient,
sandbox,
null
Example:

null

nodes_to_resubmit
object[]
required
requires_user_action
boolean
required

Whether at least one selected check requires user interaction. This does not predict the final workflow outcome.

preview_token
string
required

Signed receipt for this exact email, valid for 15 minutes. Pass it as email_preview_token to Update Session Status. An empty string when there is no recipient.

Example:

"eyJkaWdlc3QiOiI0ZjJhIn0:1uExAm:Pl3x4mpleS1gnatureValue000000000000000"

Last modified on November 1, 2026