Preview Decision Email - Didit Documentation

curl

curl -X POST \
  https://verification.didit.me/v3/session/3fa85f64-5717-4562-b3fc-2c963f66afa6/decision-email-preview/ \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"new_status": "Approved", "email_language": "en"}'

import requests

response = requests.post(
    "https://verification.didit.me/v3/session/3fa85f64-5717-4562-b3fc-2c963f66afa6/decision-email-preview/",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={"new_status": "Approved", "email_language": "en"},
)
response.raise_for_status()
print(response.json())

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({new_status: 'Approved'})
};

fetch('https://verification.didit.me/v3/session/{sessionId}/decision-email-preview/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://verification.didit.me/v3/session/{sessionId}/decision-email-preview/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'new_status' => 'Approved'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://verification.didit.me/v3/session/{sessionId}/decision-email-preview/"

	payload := strings.NewReader("{\n  \"new_status\": \"Approved\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://verification.didit.me/v3/session/{sessionId}/decision-email-preview/")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"new_status\": \"Approved\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://verification.didit.me/v3/session/{sessionId}/decision-email-preview/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"new_status\": \"Approved\"\n}"

response = http.request(request)
puts response.read_body

{
  "recipient": "person@example.com",
  "recipient_source": "email_verification",
  "sender": "Example App <no-reply@mail.example.com>",
  "sender_name": "Example App",
  "sender_email": "no-reply@mail.example.com",
  "sender_kind": "customer",
  "subject": "Your verification has been approved in Example App",
  "html": "<!DOCTYPE html><html><body>...</body></html>",
  "language": "en",
  "will_be_sent": true,
  "not_sent_reason": null,
  "preview_token": "eyJkaWdlc3QiOiI0ZjJhIn0:1uExAm:Pl3x4mpleS1gnatureValue000000000000000"
}

POST

session

{sessionId}

decision-email-preview

curl

curl -X POST \
  https://verification.didit.me/v3/session/3fa85f64-5717-4562-b3fc-2c963f66afa6/decision-email-preview/ \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"new_status": "Approved", "email_language": "en"}'

import requests

response = requests.post(
    "https://verification.didit.me/v3/session/3fa85f64-5717-4562-b3fc-2c963f66afa6/decision-email-preview/",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={"new_status": "Approved", "email_language": "en"},
)
response.raise_for_status()
print(response.json())

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({new_status: 'Approved'})
};

fetch('https://verification.didit.me/v3/session/{sessionId}/decision-email-preview/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://verification.didit.me/v3/session/{sessionId}/decision-email-preview/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'new_status' => 'Approved'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://verification.didit.me/v3/session/{sessionId}/decision-email-preview/"

	payload := strings.NewReader("{\n  \"new_status\": \"Approved\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://verification.didit.me/v3/session/{sessionId}/decision-email-preview/")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"new_status\": \"Approved\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://verification.didit.me/v3/session/{sessionId}/decision-email-preview/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"new_status\": \"Approved\"\n}"

response = http.request(request)
puts response.read_body

{
  "recipient": "person@example.com",
  "recipient_source": "email_verification",
  "sender": "Example App <no-reply@mail.example.com>",
  "sender_name": "Example App",
  "sender_email": "no-reply@mail.example.com",
  "sender_kind": "customer",
  "subject": "Your verification has been approved in Example App",
  "html": "<!DOCTYPE html><html><body>...</body></html>",
  "language": "en",
  "will_be_sent": true,
  "not_sent_reason": null,
  "preview_token": "eyJkaWdlc3QiOiI0ZjJhIn0:1uExAm:Pl3x4mpleS1gnatureValue000000000000000"
}

Previewing changes nothing and sends nothing. The response shows the email exactly as the person receives it when you set the session to Approved or Declined with send_email: true. It also tells you who receives it, who it comes from, and whether confirming sends it at all.

Who receives the email

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. recipient_source says which one applies (email_verification or contact_details). When the session has no address for the person, recipient, recipient_source and preview_token are empty strings and no email can be sent. The email goes out from your application’s verified sender domain when your white-label configuration applies (sender_kind: customer), else from Didit’s sender (sender_kind: didit).

Whether the email goes out

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

`not_sent_reason`	What it means
`status_unchanged`	The session already has this status, so the update changes nothing and sends nothing.
`notification_emails_disabled`	The session was created without `contact_details.send_notification_emails: true`, so no decision email goes to the address given in `contact_details`.
`no_recipient`	No address is known for the person.
`sandbox`	The session is a sandbox session and the recipient has not opted into sandbox email delivery, so the email is only simulated. See email opt-in.

Confirm the decision

Call Update Session Status with these fields:

Update Session Status field	Value
`new_status`	The same `new_status` you previewed
`send_email`	`true`
`email_address`	`recipient` from the preview
`email_language`	`language` from the preview
`email_preview_token`	`preview_token` from the preview

The receipt expires after 15 minutes. If the recipient, language, session status, sender or email changed since the preview, the update returns 409 before anything changes. Preview again and confirm with the new receipt.

Update Session Status: approve or decline the session and send the email.
Preview Resubmission Email: preview the email for a resubmission instead.
White label: the sender and branding the email uses.

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 missing, wrong, revoked or expired; 403 means 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.

Path Parameters

sessionId

string<uuid>

required

UUID of the verification session. Accepts both user (KYC) and business (KYB) session IDs.

Example:

"3fa85f64-5717-4562-b3fc-2c963f66afa6"

Body

application/json

new_status

enum<string>

required

The decision whose email you want to preview.

Available options:

Approved,

Declined

Example:

"Approved"

email_language

string

default:en

Language of the email, the same default as Update Session Status. A language that is not offered falls back to English; language in the response says which one is used.

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. 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,

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:

"Your verification has been approved 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>"

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. status_unchanged: the session already has this status, so the update changes nothing and sends nothing. notification_emails_disabled: the session was created without contact_details.send_notification_emails: true, so no decision email goes to the address given in contact_details. no_recipient: no address is known for the person. sandbox: a sandbox session whose recipient has not opted into sandbox email delivery, so the send is only simulated.

Available options:

status_unchanged,

notification_emails_disabled,

no_recipient,

sandbox,

null

Example:

null

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"

​Who receives the email

​Whether the email goes out

​Confirm the decision

​Related

Authorizations

Path Parameters

Body

Response

Who receives the email

Whether the email goes out

Confirm the decision

Related