Skip to main content
POST
curl
Use POST /v3/phone/risk/ when you need phone intelligence before, instead of, or outside an OTP flow. It does not send a code to the user. It creates an API session, enriches the number, applies your phone-risk rules, and returns the same normalized phone block used by Phone Verification in one synchronous response. When the request is saved, Didit can also use the scored phone number as aggregate evidence in Networks. Network graphs may show high-risk phone intelligence, porting and line-type context on shared phone signals, but they do not reveal the raw phone number 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.
  • phone.full_number is the normalized E.164 number. phone.phone_number_prefix and phone.phone_number split it into the international prefix and national number.
  • phone.is_disposable and phone.is_virtual are the stable yes/no signals for application logic. The carrier lookup adds carrier.name and carrier.type (mobile, voip, and similar).
  • phone.phone_intelligence.score uses a 0-100 risk scale where a higher number means higher risk. phone_type_risk (Low, Medium, High) and phone_trust_index (inverse of the score) are derived views.
  • phone.phone_intelligence and phone.enrichment are compatibility aliases with the same normalized object. New integrations can read phone.enrichment.
  • phone.matches lists other sessions of your application where the same number 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.
phone.phone_intelligence and phone.enrichment are best-effort fields. A completed lookup can omit both when no usable intelligence data is returned for that number, country, or plan. Build rules on the stable normalized fields first and treat missing intelligence as “unknown”, not “safe”.

​
Social footprint add-on

Set enable_social to true to add a phone_social block to the response under phone: the online platforms this phone number is registered on, grouped by category, with the summary counts and any profile details our data partners return.
  • phone.phone_social.profiles_registered and phone.phone_social.profiles_checked are the headline numbers: platforms where the phone number is confirmed registered, out of the platforms evaluated.
  • phone.phone_social.registered_platforms and phone.phone_social.not_registered_platforms list each platform with its category and scope (global, or local for region-specific platforms).
  • phone.phone_social.categories gives the registered count and ratio per category, and phone.phone_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 phone number was found on none of them, which is a common synthetic-identity signal. This endpoint does not act on it by itself - use phone_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 OTP, consume credits, create a session, or contribute to Networks. With enable_social set, they also return a deterministic phone_social block.

​
Billing

Phone Risk API calls use Phone Risk API pricing, lower than full Phone Verification because no OTP 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 phone_social unit per request on top of the Phone 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
​
phone_number
string
required

Phone number to score. It is validated and normalized to E.164.

Maximum string length: 20
Example:

"+14155552671"

​
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 number - the messaging, social, e-commerce and professional platforms it is registered on. Billed as one phone_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.

​
phone
object

Normalized phone report, the same block used by Phone Verification responses.