> ## Documentation Index > Fetch the complete documentation index at: https://docs.deepxl.ai/llms.txt > Use this file to discover all available pages before exploring further. # Fraud Detection > Detect document manipulation and AI-generated content 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: ```bash theme={null} 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`: ```bash theme={null} 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: ```bash theme={null} 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: ```json theme={null} { "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`: ```json theme={null} { "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: ```bash theme={null} 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: ```json theme={null} { "customerId": "9999", "customerName": "Acme Corp", "documentId": "DOC-2024-001", "companyName": "DeepXL", "companyId": "COMP-001" } ``` Filter your detection history by tags: ```bash theme={null} 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: ```bash theme={null} 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`