Skip to main content
POST
curl
Use POST /v3/email/risk/ when you need email intelligence without asking the user to enter a one-time code. It does not send an email. It creates an API session, enriches the address, applies your email-risk rules, and returns the same normalized email block used by Email Verification in one synchronous response. When the request is saved, Didit can also use the scored email as aggregate evidence in Networks. Network graphs may show high-risk email intelligence, breach context, and social-profile coverage on shared email signals, but they do not reveal the raw email address to other organizations.

Interpret the response

  • status is the final decision for this API session. It is normally Approved; the risk evaluation can produce In Review or Declined.
  • email.is_breached, email.is_disposable, and email.is_undeliverable are the stable yes/no signals for application logic.
  • email.breaches lists the most recent known breaches containing the address when coverage is available, with the breach date and the data classes exposed.
  • email.email_intelligence.score uses a 0-100 risk scale where a higher number means higher risk. breach_risk_level (Low, Medium, High) and no_of_breaches are derived views.
  • email.email_intelligence.reason_codes explains which normalized signals contributed to the result. Values can grow over time, so do not reject unknown codes.
  • email.email_intelligence and email.enrichment are compatibility aliases with the same normalized object. New integrations can read email.enrichment.
  • email.matches lists other sessions of your application where the same address was used by a different user. Use it for duplicate-account detection.
  • request_id is the API session id. Store it with vendor_data if you need to correlate the result with later webhooks or console activity.
email.email_intelligence and email.enrichment are best-effort fields. A completed lookup can omit both when no usable intelligence data is returned for that address, domain, or plan. Build rules on is_breached, is_disposable, and is_undeliverable first and treat missing intelligence as “unknown”, not “safe”.

Social footprint add-on

Set enable_social to true to add a email_social block to the response under email: the online platforms this email address is registered on, grouped by category, with the summary counts and any profile details our data partners return.
  • email.email_social.profiles_registered and email.email_social.profiles_checked are the headline numbers: platforms where the email address is confirmed registered, out of the platforms evaluated.
  • email.email_social.registered_platforms and email.email_social.not_registered_platforms list each platform with its category and scope (global, or local for region-specific platforms).
  • email.email_social.categories gives the registered count and ratio per category, and email.email_social.profiles carries per-platform profile details when a platform exposes them (name, photo URL, about text, privacy status, business-account flag).
  • Summary indexes (digital_footprint_diversity, digital_sophistication_index, engagement_depth_index, subscription_affordability_index) are 0-10 composites. Every count can be null when the check returned no data for it.
profiles_registered: 0 is a real answer, not a failure: the platforms were checked and the email address was found on none of them, which is a common synthetic-identity signal. This endpoint does not act on it by itself - use email_no_social_presence_action in a workflow to turn it into a Review or Decline verdict. The block is absent when enable_social is not set, and also when the social check could not be completed - in which case it is not billed.

Sandbox behavior

Sandbox keys validate the request and return deterministic approved data. They do not send an email, consume credits, create a session, or contribute to Networks. With enable_social set, they also return a deterministic email_social block.

Billing

Email Risk API calls use Email Risk API pricing, lower than full Email Verification because no email is sent. A live request is billable once the lookup starts, even when some best-effort fields are unavailable. The social footprint add-on is billed separately: one email_social unit per request on top of the Email Risk API price, whenever the check completes. The credit check before the lookup covers both.

Authorizations

x-api-key
string
header
required

Body

application/json
email
string<email>
required

Email address to score.

Example:

"alice@example.com"

country_code
string

Optional ISO 3166-1 alpha-2 or alpha-3 country hint for intelligence coverage.

Maximum string length: 3
Example:

"US"

signals
object

Optional device and network context observed by your application. All fields are optional. Passing them feeds cross-session match detection in Networks.

vendor_data
string

Your stable reference for this request. Stored on the API session and echoed in the response.

metadata
object | null

Your non-sensitive JSON metadata. Stored on the API session and echoed in the response.

enable_social
boolean
default:false

When true, also look up the social footprint of the address - the email, social, professional, e-commerce and entertainment platforms it is registered on. Billed as one email_social unit per request in addition to this endpoint's own price.

Example:

true

Response

The risk evaluation completed. Inspect status for the decision; HTTP is always 200 for completed lookups.

request_id
string<uuid>
required

Id of the API session created for this request. Store it with vendor_data if you need to correlate the result with later webhooks or console activity.

status
enum<string>
required

Final decision for this API session. Normally Approved; the risk evaluation can produce In Review or Declined.

Available options:
Approved,
In Review,
Declined
created_at
string<date-time>
required

Timestamp of this response.

vendor_data
string | null

Echo of the vendor_data you sent, null when you did not send one.

metadata
object | null

Echo of the metadata you sent, null when you did not send one.

email
object

Normalized email report, the same block used by Email Verification responses.