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"

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","documentId":"INV-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

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

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": "documentId", "value": "INV-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 / Bearer token
`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"
}

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

Getting Started

Guides

SDK Reference

Fraud Detection

Available Models

Analyzing a File

Parameters

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

Getting Started

Guides

SDK Reference

​Available Models

​Analyzing a File

​Parameters

​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

Analyzing a File

Parameters

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