> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # Fraud Check API > Plan and run selected identity, contact risk, enrichment, and network checks in one request. Submit typed identifiers and claimed identity attributes, select the checks to run, and inspect each result separately. Use [Plan a Fraud Check](/standalone-apis/fraud-check-plan) 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. ```json theme={null} { "profile_version": "2026-09-14.1", "client_reference": "review-attempt-001", "subject": { "identifiers": [ { "type": "email", "value": "applicant@example.com" } ], "attributes": { "first_name": "Alex", "last_name": "Example" } }, "checks": { "include": ["networks_same_org", "networks_cross_org", "email_risk"] } } ``` ## 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](/standalone-apis/fraud-check-result). 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. ## OpenAPI ````yaml POST /v3/fraud/checks/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: Identity verification API. Authenticate with x-api-key header. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/fraud/checks/: post: tags: - Fraud Check summary: Run a Fraud Check description: >- Submit one or more typed identifiers and receive normalization, fresh enrichment, authoritative validation where the country and identifier type are covered, independent risk dimensions and a recommendation in one response. These profiles support identifier checks. Selfie-based identity binding (`biometric_identity`) requires profile version `2026-09-14.2` and a Brazilian CPF; it runs only with the user's consent and when your organization is entitled to it. Earlier versions report it as `not_available_in_profile_version`. Modules that cannot run are reported as skipped with a deterministic reason; a source that could not answer is never reported as an identity mismatch. operationId: create_fraud_check requestBody: content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/FraudCheckRequestRequest' application/json: schema: $ref: '#/components/schemas/FraudCheckRequestRequest' multipart/form-data: schema: $ref: '#/components/schemas/FraudCheckRequestRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/FraudCheckResponse' description: '' '401': content: application/json: schema: $ref: '#/components/schemas/FraudClientCredentialsErrorMessage' description: '' '403': content: application/json: schema: $ref: >- #/components/schemas/FraudClientCredentialsForbiddenErrorMessage description: '' '409': description: >- Conflict, returned without a charge: the `client_reference` was already used with a different request body; a check with the same `client_reference` is still running (retry after `Retry-After` seconds with the same reference); or the verification this check records into was deleted before the check completed. content: application/json: schema: type: object properties: error: type: string required: - error examples: different_body: summary: Reference reused with a different body value: error: >- client_reference has already been used with a different request body. still_running: summary: A check with this reference is still running value: error: >- A check with this client_reference is already running. Retry with the same reference later. verification_deleted: summary: The verification was deleted before the check completed value: error: This verification was deleted before the check completed. headers: Retry-After: description: >- Seconds to wait before retrying, sent when a check with the same `client_reference` is still running. schema: type: integer security: - ApiKeyAuth: [] - BearerAuth: [] components: schemas: FraudCheckRequestRequest: type: object properties: client_reference: type: string minLength: 1 description: >- 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. maxLength: 255 profile: type: string minLength: 1 default: standard description: Orchestration profile id. Defaults to the Didit `standard` profile. maxLength: 64 profile_version: type: string minLength: 1 description: >- Pin a frozen profile version. Defaults to the current version of the profile. maxLength: 32 subject: $ref: '#/components/schemas/FraudCheckSubjectRequest' context: $ref: '#/components/schemas/FraudCheckContextRequest' checks: $ref: '#/components/schemas/FraudCheckModuleSelectionRequest' vendor_data: type: string maxLength: 1000 metadata: {} required: - subject FraudCheckResponse: type: object properties: check_id: type: string format: uuid request_id: type: string format: uuid description: Native verification session created for this check. client_reference: type: string nullable: true processing_status: $ref: '#/components/schemas/FraudProcessingStatusEnum' profile_id: type: string profile_version: type: string created_at: type: string format: date-time completed_at: type: string format: date-time nullable: true inputs: type: array items: $ref: '#/components/schemas/FraudCheckInput' modules: type: array items: $ref: '#/components/schemas/FraudCheckModuleReport' attribute_evidence: type: array items: type: object additionalProperties: {} compound_evidence: type: array items: type: object additionalProperties: {} risk: type: array items: $ref: '#/components/schemas/FraudCheckRisk' network: type: object additionalProperties: {} enrichment: type: object additionalProperties: {} identity_relationship: allOf: - $ref: '#/components/schemas/FraudCheckIdentityRelationship' nullable: true recommendation: $ref: '#/components/schemas/FraudRecommendationEnum' next_action: $ref: '#/components/schemas/FraudNextActionEnum' decision_reasons: type: array items: type: string coverage: type: object additionalProperties: {} usage: type: array items: type: object additionalProperties: {} vendor_data: type: string nullable: true metadata: nullable: true required: - attribute_evidence - check_id - client_reference - completed_at - compound_evidence - coverage - created_at - decision_reasons - inputs - modules - network - next_action - processing_status - profile_id - profile_version - recommendation - risk - usage FraudClientCredentialsErrorMessage: type: object properties: detail: type: string default: 'Authentication failed: Invalid client access token.' FraudClientCredentialsForbiddenErrorMessage: type: object properties: detail: type: string default: Forbidden - User doesn't have permission FraudCheckSubjectRequest: type: object properties: selfie: type: string minLength: 1 description: >- Base64 JPEG, PNG or WebP selfie, up to 6 MB. No reference image or URL. maxLength: 8388672 identifiers: type: array items: $ref: '#/components/schemas/FraudCheckIdentifierRequest' description: One or more typed identifiers. One is enough. maxItems: 10 minItems: 1 attributes: $ref: '#/components/schemas/FraudCheckAttributesRequest' required: - identifiers FraudCheckContextRequest: type: object properties: ip_address: type: string minLength: 1 user_agent: type: string maxLength: 512 country: type: string description: >- Country the subject claims to be in. Contextual only - never proof of identity ownership. maxLength: 3 purpose: type: string maxLength: 128 consent_obtained: type: boolean FraudCheckModuleSelectionRequest: type: object properties: include: type: array items: $ref: '#/components/schemas/FraudExcludeEnum' exclude: type: array items: $ref: '#/components/schemas/FraudExcludeEnum' FraudProcessingStatusEnum: enum: - pending - running - completed - failed type: string description: |- * `pending` - Pending * `running` - Running * `completed` - Completed * `failed` - Failed FraudCheckInput: type: object properties: reference: type: string description: Redacted handle for the submitted identifier. type: $ref: '#/components/schemas/FraudTypeEnum' namespace: type: object additionalProperties: {} quality: type: string normalization: type: object additionalProperties: {} availability: $ref: '#/components/schemas/FraudAvailabilityEnum' required: - availability - namespace - normalization - quality - reference - type FraudCheckModuleReport: type: object properties: module: $ref: '#/components/schemas/FraudExcludeEnum' status: $ref: '#/components/schemas/FraudStatusEnum' reason: type: string nullable: true latency_ms: type: integer freshness: type: string nullable: true billable_units: type: integer required: - billable_units - freshness - latency_ms - module - reason - status FraudCheckRisk: type: object properties: dimension: $ref: '#/components/schemas/FraudDimensionEnum' score: type: integer nullable: true band: $ref: '#/components/schemas/FraudBandEnum' availability: $ref: '#/components/schemas/FraudAvailabilityEnum' requested_but_unavailable: type: boolean description: >- True when the request supplied everything this dimension needed and the platform still could not answer it. Such a check is never recommended for approval on the strength of the dimensions that did answer. reason_codes: type: array items: type: string evidence_indexes: type: array items: type: integer required: - availability - band - dimension - evidence_indexes - reason_codes - requested_but_unavailable - score FraudCheckIdentityRelationship: type: object properties: result: $ref: '#/components/schemas/FraudResultEnum' reference_type: type: string country: type: string availability: $ref: '#/components/schemas/FraudAvailabilityEnum' reason_codes: type: array items: type: string required: - availability - country - reason_codes - reference_type - result FraudRecommendationEnum: enum: - approve - review - reject type: string description: |- * `approve` - Approve * `review` - Review * `reject` - Reject FraudNextActionEnum: enum: - none - manual_review - step_up - resubmit_capture type: string description: |- * `none` - None * `manual_review` - Manual Review * `step_up` - Step Up * `resubmit_capture` - Resubmit Capture FraudCheckIdentifierRequest: type: object properties: type: allOf: - $ref: '#/components/schemas/FraudTypeEnum' description: |- Identifier type. Determines which namespace fields are required. * `email` - Email * `phone` - Phone * `national_id` - National Id * `tax_number` - Tax Number * `passport_number` - Passport Number * `driving_licence_number` - Driving Licence Number * `residence_permit_number` - Residence Permit Number * `voter_id` - Voter Id * `external_id` - External Id value: type: string minLength: 1 description: The identifier value, in any customary format. maxLength: 255 country: type: string description: >- ISO-3166 alpha-2 or alpha-3 issuing country. Required for government identifier types: the same digits mean different people in different countries. maxLength: 3 issuer: type: string description: >- Optional issuing authority or sub-national issuer, when the country alone is not unique. maxLength: 128 required: - type - value FraudCheckAttributesRequest: type: object description: Corroborating attributes. All optional; they widen module coverage. properties: first_name: type: string maxLength: 128 last_name: type: string maxLength: 128 full_name: type: string maxLength: 256 date_of_birth: type: string format: date nationality: type: string maxLength: 3 gender: type: string maxLength: 16 address: type: string maxLength: 512 city: type: string maxLength: 128 state: type: string maxLength: 128 postal_code: type: string maxLength: 32 FraudExcludeEnum: enum: - normalization - email_risk - email_social - phone_social - phone_risk - ip_risk - database_validation - networks_same_org - networks_cross_org - biometric_identity type: string description: |- * `normalization` - Normalization * `email_risk` - Email Risk * `email_social` - Email Social * `phone_social` - Phone Social * `phone_risk` - Phone Risk * `ip_risk` - Ip Risk * `database_validation` - Database Validation * `networks_same_org` - Networks Same Org * `networks_cross_org` - Networks Cross Org * `biometric_identity` - Biometric Identity FraudTypeEnum: enum: - email - phone - national_id - tax_number - passport_number - driving_licence_number - residence_permit_number - voter_id - external_id type: string description: |- * `email` - Email * `phone` - Phone * `national_id` - National Id * `tax_number` - Tax Number * `passport_number` - Passport Number * `driving_licence_number` - Driving Licence Number * `residence_permit_number` - Residence Permit Number * `voter_id` - Voter Id * `external_id` - External Id FraudAvailabilityEnum: enum: - available - not_requested - no_reference - insufficient_history - unsupported_region - source_unavailable type: string description: |- * `available` - Available * `not_requested` - Not Requested * `no_reference` - No Reference * `insufficient_history` - Insufficient History * `unsupported_region` - Unsupported Region * `source_unavailable` - Source Unavailable FraudStatusEnum: enum: - planned - completed - skipped - failed type: string description: |- * `planned` - Planned * `completed` - Completed * `skipped` - Skipped * `failed` - Failed FraudDimensionEnum: enum: - identity - contact - device_network - behavioral - fraud_network type: string description: |- * `identity` - Identity * `contact` - Contact * `device_network` - Device Network * `behavioral` - Behavioral * `fraud_network` - Fraud Network FraudBandEnum: enum: - low - medium - high - unknown type: string description: |- * `low` - Low * `medium` - Medium * `high` - High * `unknown` - Unknown FraudResultEnum: enum: - match - mismatch - inconclusive - no_reference type: string description: |- * `match` - Match * `mismatch` - Mismatch * `inconclusive` - Inconclusive * `no_reference` - No Reference securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- 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. BearerAuth: type: http scheme: bearer description: The application's client-credentials access token. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.