Fraud Detection

The Fraud Detection API uses forensic AI to detect manipulated, altered, and AI-generated documents and images in real time.

Available Models

Model	Use Case	Supported File Types
`document`	Detects AI-generated or altered documents and IDs (bank statements, invoices, passports, driver licenses)	jpg, jpeg, png, webp, pdf
`object`	Detects AI-generated or manipulated images (photos, claim evidence, receipts)	jpg, jpeg, png, webp

Retrieve the full list of models programmatically:

curl https://api.deepxl.ai/v1/detection-models \
  -H "x-api-key: YOUR_API_KEY"

Supported Document Types

The document model classifies uploaded files into 71 types via the DOCUMENT_CLASSIFIER check, organized into 8 categories:

Identity (11 types)

Type	Description
`driver_license`	Driver license
`national_id`	National identification card
`municipal_id`	Municipal / local government ID
`passport`	Passport book
`passport_card`	Passport card (wallet-sized)
`residence_card`	Residence permit card
`work_authorization`	Work authorization / permit
`military_id`	Military identification
`professional_id`	Professional license / ID
`voter_registration_card`	Voter registration card
`social_security_card`	Social Security card

Financial (19 types)

Type	Description
`bank_statement`	Bank account statement
`business_bank_statement`	Business bank account statement
`check`	Individual check
`list_of_checks_cashed`	List of checks cashed
`check_register`	Check register
`investment_statement`	Investment / brokerage statement
`retirement_account_statement`	Retirement account statement
`pension_statement`	Pension statement
`annuity_award_letter`	Annuity award letter
`social_security_statement`	Social Security statement
`social_security_cola_notice`	Social Security COLA notice
`disability_income_verification`	Disability income verification
`credit_card_statement`	Credit card statement
`mortgage_statement`	Mortgage statement
`auto_loan_statement`	Auto loan statement
`student_loan_statement`	Student loan statement
`personal_loan_statement`	Personal loan statement
`heloc_statement`	Home Equity Line of Credit statement
`loan_statement`	Loan statement (generic)

Tax (9 types)

Type	Description
`form_1040`	IRS Form 1040 (personal tax return)
`form_1120`	IRS Form 1120 (C-Corporation)
`form_1120s`	IRS Form 1120S (S-Corporation)
`form_1065`	IRS Form 1065 (Partnership)
`w2_form`	W-2 wage and tax statement
`form_1099`	1099 tax form
`schedule_c`	IRS Schedule C (business income)
`schedule_e`	IRS Schedule E (rental income)
`tax_return`	Tax return (generic)

Employment (7 types)

Type	Description
`pay_stub`	Pay stub / earnings statement
`employment_verification_letter`	Employment verification letter
`direct_deposit_verification`	Direct deposit verification
`unemployment_benefits_document`	Unemployment benefits document
`military_les`	Military Leave and Earnings Statement
`offer_letter`	Offer letter
`self_employment_ledger`	Self-employment ledger

Property (6 types)

Type	Description
`property_deed`	Property deed
`property_tax_receipt`	Property tax receipt
`hoa_dues_statement`	HOA / condo dues statement
`lease_agreement`	Lease agreement
`rental_receipt`	Rental receipt
`title_insurance_policy`	Title insurance policy

Insurance (6 types)

Type	Description
`homeowners_insurance_declarations_page`	Homeowners insurance declarations page
`homeowners_insurance_binder`	Homeowners insurance binder
`flood_insurance_declarations_page`	Flood insurance declarations page
`auto_insurance_declarations_page`	Auto insurance declarations page
`insurance_card`	Insurance card
`insurance_document`	Insurance policy document

Commercial (6 types)

Type	Description
`business_license`	Business license
`articles_of_incorporation`	Articles of incorporation
`profit_and_loss_statement`	Profit and loss statement
`utility_bill`	Utility bill (electric, water, gas, etc.)
`phone_bill`	Phone bill
`petty_cash_receipt`	Petty cash receipt

Legal (7 types)

Type	Description
`government_letter`	Government letter (IRS, DMV, SSA, etc.)
`vehicle_registration`	Vehicle registration
`vehicle_title`	Vehicle title
`court_order`	Court order
`power_of_attorney`	Power of attorney
`death_certificate`	Death certificate
`marriage_certificate`	Marriage certificate

Files that do not match a known type are classified as other.

Analyzing a File

Submit a file for fraud detection via POST /v1/detection:

curl -X POST https://api.deepxl.ai/v1/detection \
  -H "x-api-key: YOUR_API_KEY" \
  -F "model=document" \
  -F "file=@invoice.pdf" \
  -F 'tags={"customerId":"9999","customerName":"Acme Corp","documentId":"INV-001","companyName":"DeepXL","companyId":"COMP-001"}'

Parameters

Parameter	Type	Required	Description
`model`	string	Yes	`document` or `object`
`file`	file	Yes	The file to analyze (max 50 MB)
`tags`	string	No	JSON object with metadata key-value pairs
`country`	string	No	Optional country hint. Supported values: `us`, `mx`, `br`. Missing, empty, or invalid values default to `us`.

The maximum file size is 50 MB. Files exceeding this limit will be rejected with a 413 error.

Country Hint Behavior

Use the optional country parameter when you want the API to route or annotate the request with an explicit market hint.

Supported values: us, mx, br
Matching is case-insensitive
Leading and trailing whitespace is ignored
Missing, empty, or invalid values fall back to us

This is a request hint, not a detected issuer-country claim. The service stores the normalized value in metadata and returns it in the response when available. Example:

curl -X POST https://api.deepxl.ai/v1/detection \
  -H "x-api-key: YOUR_API_KEY" \
  -F "model=document" \
  -F "file=@invoice.pdf" \
  -F "country=mx" \
  -F 'tags={"customerId":"9999","customerName":"Acme Corp","documentId":"INV-001","companyName":"DeepXL","companyId":"COMP-001"}'

Response Structure

A detection response contains the following fields:

{
  "result": {
    "detectionId": 42,
    "mediaType": "document",
    "fileType": "pdf",
    "fileName": "bank_statement.pdf",
    "fileSize": 245678,
    "timestamp": 1725795600,
    "timestampISO": "2024-09-08T10:00:00.000000",
    "model": "document",
    "modelVersion": "1.1.0",
    "likelihood": 85.2,
    "fraudSeverity": "high",
    "classification": "verified",
    "reasoning": [
      "Potential manipulation detected in text region",
      "Font inconsistencies found"
    ],
    "modelResults": {
      "technicalChecks": [
        {
          "type": "DOCUMENT_CLASSIFIER",
          "status": "PASS",
          "details": "Classified as bank statement",
          "likelihood": 0.02
        },
        {
          "type": "SEMANTIC_FRAUD",
          "status": "FAIL",
          "details": "Detected inconsistencies in text formatting",
          "likelihood": 0.85
        }
      ]
    },
    "tags": [
      { "name": "customerId", "value": "9999" },
      { "name": "customerName", "value": "Acme Corp" },
      { "name": "documentId", "value": "INV-001" },
      { "name": "companyName", "value": "DeepXL" },
      { "name": "companyId", "value": "COMP-001" }
    ],
    "files": [
      {
        "category": "original_file",
        "fileName": "fd_42_bank_statement.pdf",
        "fileSize": 245678,
        "contentType": "application/pdf",
        "timestamp": 1725795600,
        "timestampISO": "2024-09-08T10:00:00.000000",
        "url": "https://api.deepxl.ai/v1/files/fd_42_bank_statement.pdf"
      },
      {
        "category": "heatmap",
        "fileName": "fd_42_heatmap_1.png",
        "fileSize": 45678,
        "contentType": "image/png",
        "timestamp": 1725795600,
        "timestampISO": "2024-09-08T10:00:00.000000",
        "url": "https://api.deepxl.ai/v1/files/fd_42_heatmap_1.png"
      }
    ]
  }
}

Field Reference

Field	Type	Description
`detectionId`	integer	Unique identifier for the detection record
`mediaType`	string	Media type category (`image` or `document`)
`fileType`	string	File extension (`jpeg`, `png`, `pdf`, `webp`)
`fileName`	string	Original uploaded file name
`fileSize`	integer	File size in bytes
`timestamp`	integer	Unix timestamp of the analysis
`timestampISO`	string	ISO 8601 timestamp of the analysis
`model`	string	Model used (`document` or `object`)
`modelVersion`	string	Version of the model used for analysis
`likelihood`	float	Fraud likelihood as a percentage (0–100)
`fraudSeverity`	string	Severity level: `low`, `medium`, or `high`
`classification`	string	Quality assessment: `verified`, `unverified`, or `rejected`
`reasoning`	string[]	Natural-language explanations of the analysis findings
`modelResults`	object	Contains `technicalChecks` array with detailed check results
`tags`	object[]	Metadata tags attached to this detection
`files`	object[]	Associated files (original upload, heatmaps)

Understanding Results

Likelihood Score

The likelihood field is a 0–100% score indicating the probability of fraud or manipulation:

Range	Severity	Interpretation
0–29%	`low`	No significant indicators of manipulation
30–69%	`medium`	Some indicators of manipulation detected
70–100%	`high`	Strong indicators of fraud detected

Classification

The classification field indicates the document quality assessment — whether the document passed all quality gates and could be properly analyzed. This is separate from the fraud result (likelihood / fraudSeverity).

Classification	Meaning
`verified`	Document quality is good — passed all quality gates and was fully analyzed
`unverified`	Document quality is insufficient — image is blurry, corners are cut off, or semantic quality checks failed
`rejected`	Document type is not supported, text content is insufficient, or multiple documents were submitted in a single file

Reasoning

The reasoning array contains natural-language explanations of the analysis findings. Each entry describes a specific observation or conclusion from the forensic analysis.

Technical Checks

The modelResults.technicalChecks array contains the individual forensic checks performed on the file. The number and type of checks varies depending on the model, file type, and document content. Each check object includes:

Field	Type	Description
`type`	string	Check identifier
`status`	string	`PASS`, `FAIL`, `WARNING`, or `NOT_PRESENT`
`details`	string	Human-readable explanation of the check result
`likelihood`	float	Confidence score for this specific check (0.0–1.0)

Status Values

Status	Meaning
`PASS`	Check passed — no issues found
`FAIL`	Check failed — issue detected
`WARNING`	Potential concern — not conclusive but worth noting
`NOT_PRESENT`	Check could not be performed — required data was not available in the file

Document Model

The document model runs a multi-stage pipeline. First, a series of quality gates determine the classification (whether the document can be properly analyzed). Then, parallel fraud checks analyze the document for manipulation and determine the likelihood score. Additional checks may run depending on the file type and document category.

Object Model

The object model returns fraud detection results via the top-level likelihood, fraudSeverity, and reasoning fields. The technicalChecks array will be empty for the object model. When AI generation or manipulation is detected, a heatmap is included in the files array highlighting the suspicious regions.

Heatmaps

Both the document and object models can generate heatmap images that visually highlight the affected regions. Heatmaps make it easy to see exactly where tampering or AI generation was detected.

How Heatmaps Work

Heatmaps are PNG images overlaid on the original document or image
Document model: for multi-page PDFs, each page gets its own heatmap (fd_{id}_heatmap_1.png, fd_{id}_heatmap_2.png, etc.)
Object model: a single heatmap is generated per image (fd_{id}_heatmap_1.png)
Heatmaps are only generated when manipulation or AI generation is detected
They appear in the files array with category: "heatmap"

Retrieving Heatmaps

Heatmap URLs are included in the detection response under files:

{
  "files": [
    {
      "category": "original_file",
      "fileName": "fd_42_bank_statement.pdf",
      "url": "https://api.deepxl.ai/v1/files/fd_42_bank_statement.pdf"
    },
    {
      "category": "heatmap",
      "fileName": "fd_42_heatmap_1.png",
      "url": "https://api.deepxl.ai/v1/files/fd_42_heatmap_1.png"
    },
    {
      "category": "heatmap",
      "fileName": "fd_42_heatmap_2.png",
      "url": "https://api.deepxl.ai/v1/files/fd_42_heatmap_2.png"
    }
  ]
}

Download a heatmap using the file retrieval endpoint:

curl https://api.deepxl.ai/v1/files/fd_42_heatmap_1.png \
  -H "x-api-key: YOUR_API_KEY" \
  --output heatmap_page1.png

File Categories

Category	Description
`original_file`	The file you originally uploaded
`heatmap`	Generated heatmap highlighting detected manipulation regions

Error Codes

Status	Error	Description
`400`	Bad Request	Invalid model name, invalid sort parameter, malformed JSON in tags, or invalid query parameters
`401`	Unauthorized	Missing or invalid API key
`404`	Not Found	Detection record not found
`413`	Payload Too Large	File exceeds the 50 MB maximum size
`415`	Unsupported Media Type	File type is not supported by the selected model
`500`	Internal Server Error	Unexpected server error — contact support if persistent
`502`	Bad Gateway	Upstream analysis service is temporarily unavailable — retry after a short delay

Tags and Filtering

Pass a JSON object in the tags parameter to attach metadata to your analysis:

{
  "customerId": "9999",
  "customerName": "Acme Corp",
  "documentId": "DOC-2024-001",
  "companyName": "DeepXL",
  "companyId": "COMP-001"
}

Filter your detection history by tags:

curl "https://api.deepxl.ai/v1/detection?tagFilter=customerId=9999" \
  -H "x-api-key: YOUR_API_KEY"

Browsing History

Retrieve paginated detection results with sorting and filtering:

curl "https://api.deepxl.ai/v1/detection?limit=25&offset=0&sortBy=createdOn&direction=desc" \
  -H "x-api-key: YOUR_API_KEY"

Query Parameters

Parameter	Type	Description
`limit`	integer	Number of results per page (default: 25)
`offset`	integer	Number of results to skip
`sortBy`	string	Field to sort by (see options below)
`direction`	string	`asc` or `desc`
`minLikelihood`	float	Minimum likelihood filter (0–100)
`maxLikelihood`	float	Maximum likelihood filter (0–100)
`fraudSeverity`	string	Filter by severity: `low`, `medium`, or `high`
`classification`	string	Filter by classification: `verified`, `unverified`, or `rejected`
`tagFilter`	string	Filter by tag (format: `key=value`)
`minTimestamp`	integer	Minimum Unix timestamp
`maxTimestamp`	integer	Maximum Unix timestamp

Sort Options

fraudDetectionId, fileName, fileSize, fileType, model, likelihood, createdOn

Documentation Index

​Available Models

​Supported Document Types

​Identity (11 types)

​Financial (19 types)

​Tax (9 types)

​Employment (7 types)

​Property (6 types)

​Insurance (6 types)

​Commercial (6 types)

​Legal (7 types)

​Analyzing a File

​Parameters

​Country Hint Behavior

​Response Structure

​Field Reference

​Understanding Results

​Likelihood Score

​Classification

​Reasoning

​Technical Checks

​Status Values

​Document Model

​Object Model

​Heatmaps

​How Heatmaps Work

​Retrieving Heatmaps

​File Categories

​Error Codes

​Tags and Filtering

​Browsing History

​Query Parameters

​Sort Options

Available Models

Supported Document Types

Identity (11 types)

Financial (19 types)

Tax (9 types)

Employment (7 types)

Property (6 types)

Insurance (6 types)

Commercial (6 types)

Legal (7 types)

Analyzing a File

Parameters

Country Hint Behavior

Response Structure

Field Reference

Understanding Results

Likelihood Score

Classification

Reasoning

Technical Checks

Status Values

Document Model

Object Model

Heatmaps

How Heatmaps Work

Retrieving Heatmaps

File Categories

Error Codes

Tags and Filtering

Browsing History

Query Parameters

Sort Options