Skip to main content
POST
Run a Fraud Check
Submit typed identifiers and claimed identity attributes, select the checks to run, and inspect each result separately. Use Plan a Fraud Check first to check input requirements and estimated charges.

​
Choose a profile

Pin profile_version so the selected defaults and decision policy are explicit. The default profile is standard, version 2026-08-27. Version 2026-09-14 adds optional email and phone social enrichment and records every completed check as a native User Verification session. In that version, paid add-ons are opt-in. Version 2026-09-14.1 also enables global fraud network identifier lookups for participating, entitled organizations. Version 2026-09-14.2 adds an optional selfie-to-CPF reference check for Brazil. Earlier versions keep their original behavior. The current profiles support email risk, phone risk, IP risk, eligible database validation, and your application’s private network history. Selfie-based identity binding requires version 2026-09-14.2. Selecting it in earlier versions returns not_available_in_profile_version.

​
Claimed identity and context

Put email, phone, and government identifiers in subject.identifiers. Government identifiers require their issuing country; an issuer may also be needed where numbers are only unique within a region. Put names, birth date, nationality, and address in subject.attributes. These are claims to compare where a selected source supports them, not verified facts just because they were submitted. Use context for the attempt’s IP address, user agent, purpose, country, and any required consent assertion. This separates information about the verification attempt from information about the person. For supported biometric checks, supply subject.selfie as base64-encoded JPEG, PNG, or WebP, up to 6 MB. A matching image data URI is also accepted. Do not send a reference image, remote URL, or storage key.

​
Selfie and claimed identifier

Select biometric_identity, submit a Brazilian tax_number identifier and selfie, and confirm context.consent_obtained. The reference checks whether that selfie belongs to the claimed CPF holder. Missing consent returns consent_required, and unsupported countries return unsupported_region. The module has a per-check price based on your organization’s database-validation rate; inspect the plan before running it. When the reference answers, identity_relationship.result is match, mismatch, or inconclusive. An inconclusive answer requires review and is never treated as a mismatch. The result only establishes the selfie-to-CPF relationship. It does not validate a submitted name or birth date, prove liveness, or search for a face across the internet or global fraud network. Names and birth date remain claims unless another selected source supplies evidence for those fields. Timeouts and source errors are unavailable results and are not billed. Completed inconclusive answers are billed at the same reference-check rate. The selfie is not included in the result or stored as session media by this check.

​
Select checks

checks.include selects modules, and checks.exclude takes precedence. An explicit empty include list disables all optional work; normalization still runs. Omitting include uses the pinned profile’s defaults. Email and phone social enrichment are separately selected with email_social and phone_social. They require a valid matching identifier and do not send an OTP.

​
Read results without conflating them

Each module reports its execution status, reason, and billable units. not_requested, excluded_by_caller, missing_required_input, and source_unavailable describe different outcomes. A missing source is not an identity mismatch or a zero-risk result. attribute_evidence describes field-level evidence, while risk keeps identity, contact, device, behavioral, and fraud-network dimensions separate. A shared email, device, or other identifier is an observed connection, not proof that two accounts belong to the same person or committed fraud. recommendation is the check’s recommendation; it does not change another record’s status. Social enrichment results appear under enrichment, with unavailable results distinct from completed results.

​
Global fraud network

Select networks_cross_org to query supported email, phone, and properly namespaced document identifiers against the shared network. The lookup requires organization participation and entitlement, uses the existing organization read budget, and records an audit of the read. It has no per-lookup charge. Planning a check does not query the shared index or consume its read budget. network.cross_organization contains signals_checked and disclosed aggregate insights when the check completes. Each insight contains the signal type, outcome classes, contributor count, recency bucket, and industry categories only when disclosure is enabled. It never identifies another organization, account, person, or verification. Results below the disclosure threshold are omitted; an empty list does not prove the absence of fraud history. A disclosed shared signal triggers a review recommendation, never an automatic rejection or an identity match. An unavailable lookup reports its reason separately from an empty completed lookup. If sharing access is later revoked, result retrieval, retries, and session details hide the shared aggregates and their derived risk evidence. The original recommendation remains a historical decision; reads do not change verification status.

​
Sessions, retries, and charges

check_id retrieves the stored result through Get a Fraud Check. When present, request_id identifies its native verification session. Versions 2026-09-14, 2026-09-14.1, and 2026-09-14.2 always create that session, including when only private network history is selected. Reusing client_reference with the same request body returns the original result without another execution or charge while that check exists. A different body with the same reference returns 409. If execution is still running, retry the same request after the response’s Retry-After interval. Deleting the associated verification also deletes the Fraud Check result; retrieval then returns 404. A check deleted during execution cannot publish a completed result. Prices come from your organization’s current prepaid or contract rates. Unavailable and skipped modules are not billed, and private network history has no per-check charge. Sandbox checks use sample responses without paid supplier calls or charges.

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.

Body

​
subject
object
required
​
client_reference
string

Your own reference for this check. Doubles as the idempotency key: reusing it with the same body returns the original check without running or billing the modules again; reusing it with a different body returns 409.

Required string length: 1 - 255
​
profile
string
default:standard

Orchestration profile id. Defaults to the Didit standard profile.

Required string length: 1 - 64
​
profile_version
string

Pin a frozen profile version. Defaults to the current version of the profile.

Required string length: 1 - 32
​
context
object
​
checks
object
​
vendor_data
string
Maximum string length: 1000
​
metadata
any

Response

​
check_id
string<uuid>
required
​
client_reference
string | null
required
​
processing_status
enum<string>
required
  • pending - Pending
  • running - Running
  • completed - Completed
  • failed - Failed
Available options:
pending,
running,
completed,
failed
​
profile_id
string
required
​
profile_version
string
required
​
created_at
string<date-time>
required
​
completed_at
string<date-time> | null
required
​
inputs
object[]
required
​
modules
object[]
required
​
attribute_evidence
object[]
required
​
compound_evidence
object[]
required
​
risk
object[]
required
​
network
object
required
​
recommendation
enum<string>
required
  • approve - Approve
  • review - Review
  • reject - Reject
Available options:
approve,
review,
reject
​
next_action
enum<string>
required
  • none - None
  • manual_review - Manual Review
  • step_up - Step Up
  • resubmit_capture - Resubmit Capture
Available options:
none,
manual_review,
step_up,
resubmit_capture
​
decision_reasons
string[]
required
​
coverage
object
required
​
usage
object[]
required
​
request_id
string<uuid>

Native verification session created for this check.

​
enrichment
object
​
identity_relationship
object | null
​
vendor_data
string | null
​
metadata
unknown