{ "openapi": "3.1.0", "info": { "title": "DeepXL API", "description": "Professional document analysis and verification API for fraud detection, identity verification, and data extraction.", "contact": { "name": "DeepXL Support", "url": "https://deepxl.ai/contact", "email": "hello@deepxl.ai" }, "version": "1.1.0" }, "paths": { "/v1/detection-models": { "get": { "tags": [ "Fraud Detection" ], "summary": "Get available fraud detection models", "description": "Get a list of available fraud detection models with their capabilities and supported file types.", "operationId": "get_detection_models_v1_detection_models_get", "responses": { "200": { "description": "List of available fraud detection models", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RootModel_list_ModelMetadata__" }, "example": [ { "name": "document", "description": "Advanced document fraud detection model that analyzes documents for signs of manipulation and tampering.", "tags": [ "fraud-detection", "document-verification" ], "category": "fraud-detection", "validInputTypes": [ "image", "document" ], "validFileTypes": [ "jpg", "jpeg", "png", "webp", "pdf" ], "ownedBy": "DeepXL", "version": "1.1.0" }, { "name": "object", "description": "AI-generated image detection model that identifies synthetic or manipulated images.", "tags": [ "ai-detection", "image-verification" ], "category": "fraud-detection", "validInputTypes": [ "image" ], "validFileTypes": [ "jpg", "jpeg", "png", "webp" ], "ownedBy": "DeepXL", "version": "1.0.0" } ] } } } }, "security": [ { "API Key": [] } ] } }, "/v1/detection": { "get": { "tags": [ "Fraud Detection" ], "summary": "Get fraud detection history", "description": "Get a paginated list of fraud detection records for the organization. Supports sorting, pagination, and tag filtering.", "operationId": "get_detection_history_v1_detection_get", "security": [ { "API Key": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } }, { "name": "sortBy", "in": "query", "required": false, "schema": { "type": "string", "default": "fraudDetectionId", "title": "Sortby" } }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "default": "desc", "title": "Direction" } }, { "name": "tagFilter", "in": "query", "required": false, "schema": { "type": "string", "default": "", "title": "Tagfilter" } }, { "name": "mediaType", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mediatype" } }, { "name": "fileType", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Filetype" } }, { "name": "fileName", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Filename" } }, { "name": "model", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model" } }, { "name": "minLikelihood", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "number", "maximum": 100, "minimum": 0 }, { "type": "null" } ], "title": "Minlikelihood" } }, { "name": "maxLikelihood", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "number", "maximum": 100, "minimum": 0 }, { "type": "null" } ], "title": "Maxlikelihood" } }, { "name": "fraudSeverity", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Fraudseverity" } }, { "name": "classification", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Classification" } }, { "name": "minTimestamp", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 2147483647, "minimum": 0 }, { "type": "null" } ], "title": "Mintimestamp" } }, { "name": "maxTimestamp", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 2147483647, "minimum": 0 }, { "type": "null" } ], "title": "Maxtimestamp" } } ], "responses": { "200": { "description": "Fraud detection history retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetectionHistoryResponse" }, "example": { "totalCount": 42, "count": 1, "data": [ { "detectionId": 123, "mediaType": "image", "fileType": "jpeg", "fileName": "document.jpg", "fileSize": 231433, "model": "document", "likelihood": 15.5, "fraudSeverity": "low", "country": "us", "reasoning": [ "Document structure appears authentic", "No manipulation detected" ], "modelResults": { "technicalChecks": [ { "type": "DOCUMENT_STRUCTURE", "status": "PASS", "details": "Document structure is consistent" } ] }, "classification": "authentic", "timestamp": 1725795600, "timestampISO": "2024-09-08T10:00:00.000000", "tags": [ { "name": "customerId", "value": "9999" }, { "name": "customerName", "value": "Acme Corp" }, { "name": "documentId", "value": "DOC-2024-001" }, { "name": "companyName", "value": "DeepXL" }, { "name": "companyId", "value": "COMP-001" } ], "files": [ { "category": "original_file", "fileName": "document.jpg", "fileSize": 231433, "contentType": "image/jpeg", "timestamp": 1725795600, "timestampISO": "2024-09-08T10:00:00.000000", "url": "https://api.deepxl.ai/v1/files/fd_123_document.jpg" } ] } ] } } } }, "400": { "description": "Invalid request parameters (sortBy or direction)" }, "401": { "description": "Authentication required - API key or Clerk token missing/invalid" }, "500": { "description": "Internal server error" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "Fraud Detection" ], "summary": "Analyze a file for fraud detection", "description": "Analyze a file for fraud detection using the specified model.\n\n**Available Models:**\n- `document` - For PDFs and document images (bank statements, invoices, IDs)\n- `object` - For general images and AI-generated content detection\n\n**Likelihood:** Returned as 0-100% where higher values indicate higher probability of manipulation/fraud.\n\n**Tags Parameter:**\nPass optional metadata as a JSON object to organize and filter your analysis results.\n\n**Recommended tag fields:**\n| Field | Description | Example |\n|-------|-------------|---------|\n| `customerId` | Your customer's unique identifier | `\"9999\"` |\n| `customerName` | Customer or account name | `\"Acme Corp\"` |\n| `documentId` | Your internal document reference | `\"DOC-2024-001\"` |\n| `companyName` | Company name | `\"DeepXL\"` |\n| `companyId` | Company identifier | `\"COMP-001\"` |\n\n**Example tags value:** `{\"customerId\":\"9999\",\"customerName\":\"Acme Corp\",\"documentId\":\"DOC-2024-001\",\"companyName\":\"DeepXL\",\"companyId\":\"COMP-001\"}`\n\nYou can filter results by tags using the GET endpoint: `?tagFilter=customerId=9999`", "operationId": "analyze_file_v1_detection_post", "security": [ { "API Key": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_analyze_file_v1_detection_post" } } } }, "responses": { "200": { "description": "Analysis completed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetectionResponse" }, "examples": { "document_model": { "summary": "Document model response", "description": "Response from the document fraud detection model analyzing a PDF or document image", "value": { "result": { "detectionId": 2, "mediaType": "image", "fileType": "jpeg", "fileName": "bank_statement.jpg", "fileSize": 245678, "model": "document", "likelihood": 85.2, "fraudSeverity": "high", "country": "us", "reasoning": [ "Potential manipulation detected in text region", "Font inconsistencies found" ], "modelResults": { "technicalChecks": [ { "type": "IMAGE_MANIPULATION", "status": "FAIL", "details": "Detected potential manipulation", "likelihood": 0.85 } ] }, "classification": "suspicious", "timestamp": 1725795600, "timestampISO": "2024-09-08T10:00:00.000000", "tags": [ { "name": "customerId", "value": "9999" }, { "name": "customerName", "value": "Acme Corp" }, { "name": "documentId", "value": "DOC-2024-001" }, { "name": "companyName", "value": "DeepXL" }, { "name": "companyId", "value": "COMP-001" } ], "files": [ { "category": "original_file", "fileName": "bank_statement.jpg", "fileSize": 245678, "contentType": "image/jpeg", "timestamp": 1725795600, "timestampISO": "2024-09-08T10:00:00.000000", "url": "https://api.deepxl.ai/v1/files/fd_2_bank_statement.jpg" }, { "category": "heatmap", "fileName": "fd_2_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_2_heatmap_1.png" } ] } } }, "object_model": { "summary": "Object model response", "description": "Response from the object model detecting AI-generated or manipulated images. Likelihood is 0-100% where lower values indicate authentic images.", "value": { "result": { "detectionId": 1, "mediaType": "image", "fileType": "jpeg", "fileName": "photo.jpg", "fileSize": 231433, "model": "object", "likelihood": 4.75, "fraudSeverity": "low", "country": "us", "reasoning": [ "Image appears authentic with only 4.7% AI probability. Natural characteristics suggest genuine photography." ], "modelResults": { "technicalChecks": [] }, "classification": "verified", "timestamp": 1725795600, "timestampISO": "2024-09-08T10:00:00.000000", "tags": [ { "name": "customerId", "value": "9999" }, { "name": "customerName", "value": "Acme Corp" }, { "name": "documentId", "value": "DOC-2024-002" }, { "name": "companyName", "value": "DeepXL" }, { "name": "companyId", "value": "COMP-001" } ], "files": [ { "category": "original_file", "fileName": "photo.jpg", "fileSize": 231433, "contentType": "image/jpeg", "timestamp": 1725795600, "timestampISO": "2024-09-08T10:00:00.000000", "url": "https://api.deepxl.ai/v1/files/fd_1_photo.jpg" } ] } } } } } } }, "400": { "description": "Invalid model name or request parameters" }, "401": { "description": "Authentication required - API key or Clerk token missing/invalid" }, "415": { "description": "Unsupported media type - file type not compatible with selected model" }, "500": { "description": "Internal server error" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/detection/{detectionId}": { "get": { "tags": [ "Fraud Detection" ], "summary": "Get fraud detection by ID", "description": "Get a specific fraud detection record by its ID, including all associated tags and files.", "operationId": "get_detection_by_id_v1_detection__detectionId__get", "security": [ { "API Key": [] } ], "parameters": [ { "name": "detectionId", "in": "path", "required": true, "schema": { "type": "integer", "title": "Detectionid" } } ], "responses": { "200": { "description": "Fraud detection record retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetectionResponse" }, "example": { "result": { "detectionId": 1, "mediaType": "image", "fileType": "jpeg", "fileName": "document.jpg", "fileSize": 231433, "model": "object", "likelihood": 4.75, "fraudSeverity": "low", "country": "us", "reasoning": [ "Image appears authentic with only 4.7% AI probability. Natural characteristics suggest genuine photography." ], "modelResults": { "technicalChecks": [] }, "classification": "verified", "timestamp": 1725795600, "timestampISO": "2024-09-08T10:00:00.000000", "tags": [ { "name": "customerId", "value": "9999" }, { "name": "customerName", "value": "Acme Corp" }, { "name": "documentId", "value": "DOC-2024-001" }, { "name": "companyName", "value": "DeepXL" }, { "name": "companyId", "value": "COMP-001" } ], "files": [ { "category": "original_file", "fileName": "document.jpg", "fileSize": 231433, "contentType": "image/jpeg", "timestamp": 1725795600, "timestampISO": "2024-09-08T10:00:00.000000", "url": "https://api.deepxl.ai/v1/files/fd_1_document.jpg" } ] } } } } }, "401": { "description": "Authentication required - API key or Clerk token missing/invalid" }, "404": { "description": "Detection record not found" }, "500": { "description": "Internal server error" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/detection/{detectionId}/evidence-links": { "get": { "tags": [ "Fraud Detection" ], "summary": "Get cross-document evidence links for a detection", "description": "Get inbound and outbound stored cross-document evidence links for a fraud detection record.", "operationId": "get_detection_evidence_links_v1_detection__detectionId__evidence_links_get", "security": [ { "API Key": [] } ], "parameters": [ { "name": "detectionId", "in": "path", "required": true, "schema": { "type": "integer", "title": "Detectionid" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetectionEvidenceLinksResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/parsing-models": { "get": { "tags": [ "Document Parsing" ], "summary": "Get list of parsing models", "description": "Retrieve a list of available document parsing models with their capabilities and supported file types.", "operationId": "get_parsing_models_v1_parsing_models_get", "responses": { "200": { "description": "List of available parsing models", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RootModel_list_ModelMetadata__" }, "example": [ { "name": "light", "description": "Parsing light model. Data extraction is aimed at Driver License, State ID, Residency Permit, Social Security Card, Military ID", "tags": [ "id-parsing", "fast" ], "category": "document-parsing", "validInputTypes": [ "image", "document" ], "validFileTypes": [ "jpg", "jpeg", "png", "webp", "pdf" ], "ownedBy": "DeepXL", "version": "1.0.0" }, { "name": "performance", "description": "Parsing performance model. Data extraction is aimed at Bank statements, US pay stubs", "tags": [ "document-parsing", "comprehensive" ], "category": "document-parsing", "validInputTypes": [ "image", "document" ], "validFileTypes": [ "jpg", "jpeg", "png", "webp", "pdf" ], "ownedBy": "DeepXL", "version": "1.0.0" } ] } } }, "401": { "description": "Authentication required - API key or Clerk token missing/invalid" } }, "security": [ { "API Key": [] } ] } }, "/v1/parse": { "get": { "tags": [ "Document Parsing" ], "summary": "Get Parse History", "description": "Get the document parse history for the organization. Supports sorting, pagination, and tag filtering.", "operationId": "get_parsing_history_v1_parse_get", "security": [ { "API Key": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } }, { "name": "sortBy", "in": "query", "required": false, "schema": { "type": "string", "default": "parseId", "title": "Sortby" } }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "default": "desc", "title": "Direction" } }, { "name": "tagFilter", "in": "query", "required": false, "schema": { "type": "string", "default": "", "title": "Tagfilter" } }, { "name": "mediaType", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mediatype" } }, { "name": "fileType", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Filetype" } }, { "name": "fileName", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Filename" } }, { "name": "minFileSize", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "title": "Minfilesize" } }, { "name": "maxFileSize", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "title": "Maxfilesize" } }, { "name": "model", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model" } }, { "name": "documentType", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Documenttype" } }, { "name": "minTimestamp", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 2147483647, "minimum": 0 }, { "type": "null" } ], "title": "Mintimestamp" } }, { "name": "maxTimestamp", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 2147483647, "minimum": 0 }, { "type": "null" } ], "title": "Maxtimestamp" } } ], "responses": { "200": { "description": "Parse history retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIParseHistoryResponse" }, "example": { "totalCount": 156, "count": 1, "data": [ { "parseId": 117, "mediaType": "image", "fileType": "jpeg", "fileName": "drivers_license.jpg", "fileSize": 231433, "model": "light", "country": "us", "documentType": "usa_driver_license", "parsedData": { "firstName": "JOHN", "lastName": "DOE", "dateOfBirth": "1990-05-15", "licenseNumber": "D1234567", "expirationDate": "2028-05-15", "address": "123 MAIN ST ANYTOWN, CA 90210" }, "timestamp": 1725795600, "timestampISO": "2024-09-08T10:00:00.000000", "tags": [ { "name": "customerId", "value": "9999" }, { "name": "customerName", "value": "Acme Corp" }, { "name": "documentId", "value": "DOC-2024-001" }, { "name": "companyName", "value": "DeepXL" }, { "name": "companyId", "value": "COMP-001" } ], "files": [ { "category": "original_file", "fileName": "drivers_license.jpg", "fileSize": 231433, "contentType": "image/jpeg", "timestamp": 1725795600, "timestampISO": "2024-09-08T10:00:00.000000", "url": "https://api.deepxl.ai/v1/files/parse_117_drivers_license.jpg" } ] } ] } } } }, "400": { "description": "Invalid request parameters (sortBy or direction)" }, "401": { "description": "Authentication required - API key or Clerk token missing/invalid" }, "500": { "description": "Internal server error" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "Document Parsing" ], "summary": "Parse Document", "description": "Extract visible user information from a document or issued ID.\n\n**Available Models:**\n- `light` - Parsing light model. Data extraction is aimed at Driver License, State ID, Residency Permit, Social Security Card, Military ID\n- `performance` - Parsing performance model. Data extraction is aimed at Bank statements, US pay stubs\n\n**Tags Parameter:**\nPass optional metadata as a JSON object to organize and filter your parsing results.\n\n**Recommended tag fields:**\n| Field | Description | Example |\n|-------|-------------|---------|\n| `customerId` | Your customer's unique identifier | `\"9999\"` |\n| `customerName` | Customer or account name | `\"Acme Corp\"` |\n| `documentId` | Your internal document reference | `\"DOC-2024-001\"` |\n| `companyName` | Company name | `\"DeepXL\"` |\n| `companyId` | Company identifier | `\"COMP-001\"` |\n\n**Example tags value:** `{\"customerId\":\"9999\",\"customerName\":\"Acme Corp\",\"documentId\":\"DOC-2024-001\",\"companyName\":\"DeepXL\",\"companyId\":\"COMP-001\"}`\n\nYou can filter results by tags using the GET endpoint: `?tagFilter=customerId=9999`", "operationId": "parse_document_v1_parse_post", "security": [ { "API Key": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_parse_document_v1_parse_post" } } } }, "responses": { "200": { "description": "Document processed successfully with extracted parsed data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIParseResponse" }, "examples": { "successful_parse": { "summary": "Successful document parse", "description": "Document was recognized and data was extracted successfully", "value": { "result": { "parseId": 117, "mediaType": "image", "fileType": "jpeg", "fileName": "drivers_license.jpg", "fileSize": 231433, "model": "light", "country": "us", "documentType": "usa_driver_license", "parsedData": { "firstName": "JOHN", "lastName": "DOE", "dateOfBirth": "1990-05-15", "licenseNumber": "D1234567", "expirationDate": "2028-05-15", "address": "123 MAIN ST ANYTOWN, CA 90210" }, "timestamp": 1725795600, "timestampISO": "2024-09-08T10:00:00.000000", "tags": [ { "name": "customerId", "value": "9999" }, { "name": "customerName", "value": "Acme Corp" }, { "name": "documentId", "value": "DOC-2024-001" }, { "name": "companyName", "value": "DeepXL" }, { "name": "companyId", "value": "COMP-001" } ], "files": [ { "category": "original_file", "fileName": "drivers_license.jpg", "fileSize": 231433, "contentType": "image/jpeg", "timestamp": 1725795600, "timestampISO": "2024-09-08T10:00:00.000000", "url": "https://api.deepxl.ai/v1/files/parse_117_drivers_license.jpg" } ] } } }, "rejected_document": { "summary": "Document rejected/not recognized", "description": "Document type was not recognized or could not be parsed", "value": { "result": { "parseId": 116, "mediaType": "image", "fileType": "png", "fileName": "photo.png", "fileSize": 395856, "model": "light", "country": "us", "documentType": "other", "parsedData": {}, "timestamp": 1725795600, "timestampISO": "2024-09-08T10:00:00.000000", "tags": [ { "name": "customerId", "value": "9999" }, { "name": "customerName", "value": "Acme Corp" }, { "name": "documentId", "value": "DOC-2024-002" }, { "name": "companyName", "value": "DeepXL" }, { "name": "companyId", "value": "COMP-001" } ], "files": [ { "category": "original_file", "fileName": "photo.png", "fileSize": 395856, "contentType": "image/png", "timestamp": 1725795600, "timestampISO": "2024-09-08T10:00:00.000000", "url": "https://api.deepxl.ai/v1/files/parse_116_photo.png" } ] } } } } } } }, "400": { "description": "Invalid model name or request parameters" }, "401": { "description": "Authentication required - API key or Clerk token missing/invalid" }, "415": { "description": "Unsupported media type - file type not compatible with selected model" }, "500": { "description": "Internal server error" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/parse/{parseId}": { "get": { "tags": [ "Document Parsing" ], "summary": "Get parsed document", "description": "Retrieve the results of a previously parsed document by its ID, including all associated tags and files.", "operationId": "get_parse_v1_parse__parseId__get", "security": [ { "API Key": [] } ], "parameters": [ { "name": "parseId", "in": "path", "required": true, "schema": { "type": "integer", "title": "Parseid" } } ], "responses": { "200": { "description": "Parsed document retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIParseResponse" }, "example": { "result": { "parseId": 117, "mediaType": "image", "fileType": "jpeg", "fileName": "drivers_license.jpg", "fileSize": 231433, "model": "light", "country": "us", "documentType": "usa_driver_license", "parsedData": { "firstName": "JOHN", "lastName": "DOE", "dateOfBirth": "1990-05-15", "licenseNumber": "D1234567", "expirationDate": "2028-05-15", "address": "123 MAIN ST ANYTOWN, CA 90210" }, "timestamp": 1725795600, "timestampISO": "2024-09-08T10:00:00.000000", "tags": [ { "name": "customerId", "value": "9999" }, { "name": "customerName", "value": "Acme Corp" }, { "name": "documentId", "value": "DOC-2024-001" }, { "name": "companyName", "value": "DeepXL" }, { "name": "companyId", "value": "COMP-001" } ], "files": [ { "category": "original_file", "fileName": "drivers_license.jpg", "fileSize": 231433, "contentType": "image/jpeg", "timestamp": 1725795600, "timestampISO": "2024-09-08T10:00:00.000000", "url": "https://api.deepxl.ai/v1/files/parse_117_drivers_license.jpg" } ] } } } } }, "401": { "description": "Authentication required - API key or Clerk token missing/invalid" }, "404": { "description": "Parsed document not found" }, "500": { "description": "Internal server error" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/verification": { "get": { "tags": [ "ID Verification" ], "summary": "List verification history", "description": "List verification history for the organization. Supports sorting, pagination, and tag filtering.", "operationId": "get_verification_history_v1_verification_get", "security": [ { "API Key": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } }, { "name": "sortBy", "in": "query", "required": false, "schema": { "type": "string", "default": "verificationId", "title": "Sortby" } }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "default": "desc", "title": "Direction" } }, { "name": "tagFilter", "in": "query", "required": false, "schema": { "type": "string", "default": "", "title": "Tagfilter" } }, { "name": "idFileName", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idfilename" } }, { "name": "idFileType", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idfiletype" } }, { "name": "selfieFileName", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Selfiefilename" } }, { "name": "selfieFileType", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Selfiefiletype" } }, { "name": "minIdFileSize", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "title": "Minidfilesize" } }, { "name": "maxIdFileSize", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "title": "Maxidfilesize" } }, { "name": "minSelfieFileSize", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "title": "Minselfiefilesize" } }, { "name": "maxSelfieFileSize", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "title": "Maxselfiefilesize" } }, { "name": "verified", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Verified" } }, { "name": "minTimestamp", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 2147483647, "minimum": 0 }, { "type": "null" } ], "title": "Mintimestamp" } }, { "name": "maxTimestamp", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 2147483647, "minimum": 0 }, { "type": "null" } ], "title": "Maxtimestamp" } } ], "responses": { "200": { "description": "Verification history retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIVerificationHistoryResponse" }, "example": { "totalCount": 89, "count": 1, "data": [ { "verificationId": 456, "idFileType": "jpeg", "idFileName": "drivers_license.jpg", "idFileSize": 156789, "selfieFileType": "jpeg", "selfieFileName": "selfie.jpg", "selfieFileSize": 89012, "model": "verification", "country": "us", "verified": true, "modelResults": { "technicalChecks": [ { "type": "FACE_MATCH", "status": "PASS", "confidence": 0.95, "details": "Face match confidence: 95%" }, { "type": "LIVENESS", "status": "PASS", "confidence": 0.98, "details": "Liveness check passed" } ] }, "timestamp": 1725795600, "timestampISO": "2024-09-08T10:00:00.000000", "tags": [ { "name": "customerId", "value": "9999" }, { "name": "customerName", "value": "Acme Corp" }, { "name": "documentId", "value": "DOC-2024-001" }, { "name": "companyName", "value": "DeepXL" }, { "name": "companyId", "value": "COMP-001" } ], "files": [ { "category": "id", "fileName": "drivers_license.jpg", "fileSize": 156789, "contentType": "image/jpeg", "timestamp": 1725795600, "timestampISO": "2024-09-08T10:00:00.000000", "url": "https://api.deepxl.ai/v1/files/v_id_456_drivers_license.jpg" }, { "category": "face", "fileName": "selfie.jpg", "fileSize": 89012, "contentType": "image/jpeg", "timestamp": 1725795600, "timestampISO": "2024-09-08T10:00:00.000000", "url": "https://api.deepxl.ai/v1/files/v_face_456_selfie.jpg" } ] } ] } } } }, "400": { "description": "Invalid request parameters (sortBy or direction)" }, "401": { "description": "Authentication required - API key or Clerk token missing/invalid" }, "500": { "description": "Internal server error" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "ID Verification" ], "summary": "Verify user with their ID and selfie", "description": "Verify a user's identity by uploading an ID document and a selfie.\n\nThe system compares the face in the ID with the selfie and performs liveness checks to ensure the person is real.\n\n**Required Files:**\n- `idFile` - ID document image or PDF (driver license, passport, etc.)\n- `selfieFile` - Selfie still image **or** selfie video (e.g. mp4, mov, webm), same field name for both\n\n**Tags Parameter:**\nPass optional metadata as a JSON object to organize and filter your verification results.\n\n**Recommended tag fields:**\n| Field | Description | Example |\n|-------|-------------|---------|\n| `customerId` | Your customer's unique identifier | `\"9999\"` |\n| `customerName` | Customer or account name | `\"Acme Corp\"` |\n| `documentId` | Your internal document reference | `\"DOC-2024-001\"` |\n| `companyName` | Company name | `\"DeepXL\"` |\n| `companyId` | Company identifier | `\"COMP-001\"` |\n\n**Example tags value:** `{\"customerId\":\"9999\",\"customerName\":\"Acme Corp\",\"documentId\":\"DOC-2024-001\",\"companyName\":\"DeepXL\",\"companyId\":\"COMP-001\"}`\n\nYou can filter results by tags using the GET endpoint: `?tagFilter=customerId=9999`", "operationId": "verify_v1_verification_post", "security": [ { "API Key": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_verify_v1_verification_post" } } } }, "responses": { "200": { "description": "Verification completed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationResponse" }, "example": { "result": { "verificationId": 457, "idFileType": "jpeg", "idFileName": "passport.jpg", "idFileSize": 234567, "selfieFileType": "jpeg", "selfieFileName": "live_selfie.jpg", "selfieFileSize": 112233, "model": "verification", "country": "us", "verified": true, "modelResults": { "technicalChecks": [ { "type": "FACE_MATCH", "status": "PASS", "confidence": 0.97, "details": "Face match confidence: 97%" }, { "type": "LIVENESS", "status": "PASS", "confidence": 0.99, "details": "Liveness check passed" }, { "type": "ID_QUALITY", "status": "PASS", "confidence": 0.92, "details": "ID document quality is acceptable" } ] }, "timestamp": 1725795600, "timestampISO": "2024-09-08T10:00:00.000000", "tags": [ { "name": "customerId", "value": "9999" }, { "name": "customerName", "value": "Acme Corp" }, { "name": "documentId", "value": "DOC-2024-001" }, { "name": "companyName", "value": "DeepXL" }, { "name": "companyId", "value": "COMP-001" } ], "files": [ { "category": "id", "fileName": "passport.jpg", "fileSize": 234567, "contentType": "image/jpeg", "timestamp": 1725795600, "timestampISO": "2024-09-08T10:00:00.000000", "url": "https://api.deepxl.ai/v1/files/v_id_457_passport.jpg" }, { "category": "face", "fileName": "live_selfie.jpg", "fileSize": 112233, "contentType": "image/jpeg", "timestamp": 1725795600, "timestampISO": "2024-09-08T10:00:00.000000", "url": "https://api.deepxl.ai/v1/files/v_face_457_live_selfie.jpg" } ] } } } } }, "400": { "description": "Invalid request - missing required files or invalid JSON in tags" }, "401": { "description": "Authentication required - API key or Clerk token missing/invalid" }, "415": { "description": "Unsupported media type - file type not supported by verification model" }, "500": { "description": "Internal server error" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/verification/{verificationId}": { "get": { "tags": [ "ID Verification" ], "summary": "Get Verification", "description": "Get details of a specific verification by its ID, including all associated tags and files.", "operationId": "get_verification_v1_verification__verificationId__get", "security": [ { "API Key": [] } ], "parameters": [ { "name": "verificationId", "in": "path", "required": true, "schema": { "type": "integer", "title": "Verificationid" } } ], "responses": { "200": { "description": "Verification record retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationResponse" }, "example": { "result": { "verificationId": 456, "idFileType": "jpeg", "idFileName": "drivers_license.jpg", "idFileSize": 156789, "selfieFileType": "jpeg", "selfieFileName": "selfie.jpg", "selfieFileSize": 89012, "model": "verification", "country": "us", "verified": true, "modelResults": { "technicalChecks": [ { "type": "FACE_MATCH", "status": "PASS", "confidence": 0.95, "details": "Face match confidence: 95%" }, { "type": "LIVENESS", "status": "PASS", "confidence": 0.98, "details": "Liveness check passed" } ] }, "timestamp": 1725795600, "timestampISO": "2024-09-08T10:00:00.000000", "tags": [ { "name": "customerId", "value": "9999" }, { "name": "customerName", "value": "Acme Corp" }, { "name": "documentId", "value": "DOC-2024-001" }, { "name": "companyName", "value": "DeepXL" }, { "name": "companyId", "value": "COMP-001" } ], "files": [ { "category": "id", "fileName": "drivers_license.jpg", "fileSize": 156789, "contentType": "image/jpeg", "timestamp": 1725795600, "timestampISO": "2024-09-08T10:00:00.000000", "url": "https://api.deepxl.ai/v1/files/v_id_456_drivers_license.jpg" }, { "category": "face", "fileName": "selfie.jpg", "fileSize": 89012, "contentType": "image/jpeg", "timestamp": 1725795600, "timestampISO": "2024-09-08T10:00:00.000000", "url": "https://api.deepxl.ai/v1/files/v_face_456_selfie.jpg" } ] } } } } }, "401": { "description": "Authentication required - API key or Clerk token missing/invalid" }, "404": { "description": "Verification record not found" }, "500": { "description": "Internal server error" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/files/{fileName}": { "get": { "tags": [ "File Retrieval" ], "summary": "Retrieve a file", "description": "Retrieve a file from cloud storage. Files are associated with analysis results (fraud detection, parsing, verification) and include original uploads and generated heatmaps.", "operationId": "get_file_v1_files__fileName__get", "security": [ { "API Key": [] } ], "parameters": [ { "name": "fileName", "in": "path", "required": true, "schema": { "type": "string", "title": "Filename" } } ], "responses": { "200": { "description": "File retrieved successfully", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Authentication required - API key or Clerk token missing/invalid" }, "404": { "description": "File not found or not accessible by this organization" }, "500": { "description": "Internal server error" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "APIParse": { "properties": { "parseId": { "type": "integer", "title": "Parseid", "description": "Unique identifier for the parse record" }, "mediaType": { "type": "string", "title": "Mediatype", "description": "Media type category (e.g. image, document)" }, "fileType": { "type": "string", "title": "Filetype", "description": "File extension (e.g. jpeg, png, pdf)" }, "fileName": { "type": "string", "title": "Filename", "description": "Original file name" }, "fileSize": { "type": "integer", "title": "Filesize", "description": "File size in bytes" }, "timestamp": { "type": "integer", "title": "Timestamp", "description": "Unix timestamp of when the parsing was performed" }, "timestampISO": { "type": "string", "title": "Timestampiso", "description": "ISO 8601 timestamp of when the parsing was performed" }, "model": { "type": "string", "title": "Model", "description": "Model used for parsing (light or performance)" }, "modelVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Modelversion", "description": "Version of the model used (e.g. 1.2.0)" }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Country", "description": "Normalized country hint applied to this parse (us, mx, br)" }, "documentType": { "type": "string", "title": "Documenttype", "description": "Detected document type (e.g. usa_driver_license, invoice, other)" }, "parsedData": { "additionalProperties": true, "type": "object", "title": "Parseddata", "description": "Extracted key-value pairs from the document" }, "tags": { "items": { "$ref": "#/components/schemas/Tag" }, "type": "array", "title": "Tags", "description": "Metadata tags attached to this parse result", "default": [] }, "files": { "items": { "$ref": "#/components/schemas/FileData" }, "type": "array", "title": "Files", "description": "Associated files (original upload)", "default": [] } }, "type": "object", "required": [ "parseId", "mediaType", "fileType", "fileName", "fileSize", "timestamp", "timestampISO", "model", "documentType", "parsedData" ], "title": "APIParse" }, "APIParseHistoryResponse": { "properties": { "totalCount": { "type": "integer", "title": "Totalcount", "description": "Total number of records matching the query" }, "count": { "type": "integer", "title": "Count", "description": "Number of records returned in this page" }, "data": { "items": { "$ref": "#/components/schemas/APIParse" }, "type": "array", "title": "Data", "description": "List of parse records" } }, "type": "object", "required": [ "totalCount", "count", "data" ], "title": "APIParseHistoryResponse" }, "APIParseResponse": { "properties": { "result": { "$ref": "#/components/schemas/APIParse", "description": "The document parse result" } }, "type": "object", "required": [ "result" ], "title": "APIParseResponse" }, "APIVerificationHistoryResponse": { "properties": { "totalCount": { "type": "integer", "title": "Totalcount", "description": "Total number of records matching the query" }, "count": { "type": "integer", "title": "Count", "description": "Number of records returned in this page" }, "data": { "items": { "$ref": "#/components/schemas/Verification" }, "type": "array", "title": "Data", "description": "List of verification records" } }, "type": "object", "required": [ "totalCount", "count", "data" ], "title": "APIVerificationHistoryResponse" }, "Body_analyze_file_v1_detection_post": { "properties": { "model": { "type": "string", "title": "Model", "description": "Model to use for analysis; Available models: document, object" }, "file": { "type": "string", "contentMediaType": "application/octet-stream", "title": "File" }, "tags": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tags", "description": "Optional JSON object with key-value pairs for organizing and querying results. Example: {\"customerId\":\"9999\",\"customerName\":\"Acme Corp\",\"documentId\":\"DOC-2024-001\",\"companyName\":\"DeepXL\",\"companyId\":\"COMP-001\"}. Common keys: customerId, customerName, documentId, companyName, companyId.", "default": "{}" }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Country", "description": "Optional country hint. Supported values: us, mx, br. Defaults to us when omitted or invalid." }, "photocopy": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Photocopy", "description": "Optional document-model photocopy policy override. For Mexico, omit or set true to reject detected photocopies; set false to disable that policy gate for the request." }, "document": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Document", "description": "Optional document type override for document model requests. Example: bank_statement or financial/bank_statement. When supplied, classification is bypassed." } }, "type": "object", "required": [ "model", "file" ], "title": "Body_analyze_file_v1_detection_post" }, "Body_parse_document_v1_parse_post": { "properties": { "model": { "type": "string", "title": "Model", "description": "AI model to use for parsing. 'light': Parsing light model (Driver License, State ID, Residency Permit, Social Security Card, Military ID). 'performance': Parsing performance model (Bank statements, US pay stubs)." }, "file": { "type": "string", "contentMediaType": "application/octet-stream", "title": "File" }, "tags": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tags", "description": "Optional JSON object with key-value pairs for organizing and querying results. Example: {\"customerId\":\"9999\",\"customerName\":\"Acme Corp\",\"documentId\":\"DOC-2024-001\",\"companyName\":\"DeepXL\",\"companyId\":\"COMP-001\"}. Common keys: customerId, customerName, documentId, companyName, companyId.", "default": "{}" }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Country", "description": "Optional country hint. Supported values: us, mx, br. Defaults to us when omitted or invalid." } }, "type": "object", "required": [ "model", "file" ], "title": "Body_parse_document_v1_parse_post" }, "Body_verify_v1_verification_post": { "properties": { "idFile": { "type": "string", "contentMediaType": "application/octet-stream", "title": "Idfile" }, "selfieFile": { "type": "string", "contentMediaType": "application/octet-stream", "title": "Selfiefile" }, "tags": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tags", "description": "Optional JSON object with key-value pairs for organizing and querying results. Example: {\"customerId\":\"9999\",\"customerName\":\"Acme Corp\",\"documentId\":\"DOC-2024-001\",\"companyName\":\"DeepXL\",\"companyId\":\"COMP-001\"}. Common keys: customerId, customerName, documentId, companyName, companyId.", "default": "{}" }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Country", "description": "Optional country hint. Supported values: us, mx, br. Defaults to us when omitted or invalid." } }, "type": "object", "required": [ "idFile", "selfieFile" ], "title": "Body_verify_v1_verification_post" }, "DetectionEvidenceLink": { "properties": { "direction": { "type": "string", "title": "Direction", "description": "outbound when this detection created the link, inbound when another detection links back to it" }, "sourceFraudDetectionId": { "type": "integer", "title": "Sourcefrauddetectionid", "description": "Detection ID that produced the link" }, "relatedFraudDetectionId": { "type": "integer", "title": "Relatedfrauddetectionid", "description": "Detection ID linked by matching evidence" }, "linkType": { "type": "string", "title": "Linktype", "description": "Semantic cross-document link type" }, "evidenceType": { "type": "string", "title": "Evidencetype", "description": "Evidence category used for the link" }, "evidenceValue": { "type": "string", "title": "Evidencevalue", "description": "Hashed evidence value or fingerprint" }, "sourceCheckType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sourcechecktype", "description": "Check type on the source detection" }, "relatedSourceCheckType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Relatedsourcechecktype", "description": "Check type on the related detection" }, "strength": { "type": "string", "title": "Strength", "description": "Link strength: low, medium, high, or critical" }, "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata", "description": "Additional redacted link context" }, "createdOn": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Createdon", "description": "ISO timestamp for link creation" } }, "type": "object", "required": [ "direction", "sourceFraudDetectionId", "relatedFraudDetectionId", "linkType", "evidenceType", "evidenceValue", "strength" ], "title": "DetectionEvidenceLink" }, "DetectionEvidenceLinksResponse": { "properties": { "detectionId": { "type": "integer", "title": "Detectionid", "description": "Detection ID used as graph center" }, "count": { "type": "integer", "title": "Count", "description": "Number of evidence links returned" }, "summary": { "$ref": "#/components/schemas/DetectionEvidenceLinksSummary", "description": "Aggregated summary for the returned evidence links" }, "relatedDetections": { "items": { "$ref": "#/components/schemas/DetectionEvidenceRelatedDetection" }, "type": "array", "title": "Relateddetections", "description": "Evidence links grouped by related detection" }, "links": { "items": { "$ref": "#/components/schemas/DetectionEvidenceLink" }, "type": "array", "title": "Links", "description": "Inbound and outbound evidence links" } }, "type": "object", "required": [ "detectionId", "count", "summary", "relatedDetections", "links" ], "title": "DetectionEvidenceLinksResponse" }, "DetectionEvidenceLinksSummary": { "properties": { "byLinkType": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Bylinktype", "description": "Evidence link counts grouped by semantic link type" }, "byStrength": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Bystrength", "description": "Evidence link counts grouped by strength" }, "criticalCount": { "type": "integer", "title": "Criticalcount", "description": "Number of critical-strength evidence links" }, "hasCriticalLinks": { "type": "boolean", "title": "Hascriticallinks", "description": "True when any critical-strength link exists" }, "strongestStrength": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Strongeststrength", "description": "Strongest link strength in the returned page" } }, "type": "object", "required": [ "byLinkType", "byStrength", "criticalCount", "hasCriticalLinks" ], "title": "DetectionEvidenceLinksSummary" }, "DetectionEvidenceRelatedDetection": { "properties": { "detectionId": { "type": "integer", "title": "Detectionid", "description": "Other detection connected to the graph center" }, "linkCount": { "type": "integer", "title": "Linkcount", "description": "Number of evidence links to this detection" }, "strongestStrength": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Strongeststrength", "description": "Strongest link strength for this related detection" }, "linkTypes": { "items": { "type": "string" }, "type": "array", "title": "Linktypes", "description": "Semantic link types connecting this detection" }, "directions": { "items": { "type": "string" }, "type": "array", "title": "Directions", "description": "Directions represented by links to this detection" }, "sourceFilename": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sourcefilename", "description": "Redacted filename for the related detection when known" }, "docCategory": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Doccategory", "description": "Document category for the related detection when known" }, "documentType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Documenttype", "description": "Document type for the related detection when known" }, "likelihood": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Likelihood", "description": "Fraud likelihood for the related detection when known" }, "likelihoodBand": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Likelihoodband", "description": "Fraud likelihood band for the related detection when known" } }, "type": "object", "required": [ "detectionId", "linkCount", "linkTypes", "directions" ], "title": "DetectionEvidenceRelatedDetection" }, "DetectionHistoryResponse": { "properties": { "totalCount": { "type": "integer", "title": "Totalcount", "description": "Total number of records matching the query" }, "count": { "type": "integer", "title": "Count", "description": "Number of records returned in this page" }, "data": { "items": { "$ref": "#/components/schemas/FraudDetection" }, "type": "array", "title": "Data", "description": "List of fraud detection records" } }, "type": "object", "required": [ "totalCount", "count", "data" ], "title": "DetectionHistoryResponse" }, "DetectionResponse": { "properties": { "result": { "$ref": "#/components/schemas/FraudDetection", "description": "The fraud detection result" } }, "type": "object", "required": [ "result" ], "title": "DetectionResponse" }, "FileData": { "properties": { "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category", "description": "File category (e.g. original_file, heatmap, id, face)" }, "fileName": { "type": "string", "title": "Filename", "description": "Name of the file" }, "fileSize": { "type": "integer", "title": "Filesize", "description": "File size in bytes" }, "contentType": { "type": "string", "title": "Contenttype", "description": "MIME content type (e.g. image/jpeg, application/pdf)" }, "timestamp": { "type": "integer", "title": "Timestamp", "description": "Unix timestamp of when the file was created" }, "timestampISO": { "type": "string", "title": "Timestampiso", "description": "ISO 8601 timestamp of when the file was created" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url", "description": "URL to retrieve the file via GET /v1/files/{fileName}" } }, "type": "object", "required": [ "fileName", "fileSize", "contentType", "timestamp", "timestampISO" ], "title": "FileData" }, "FraudDetection": { "properties": { "detectionId": { "type": "integer", "title": "Detectionid", "description": "Unique identifier for the detection record" }, "mediaType": { "type": "string", "title": "Mediatype", "description": "Media type category (e.g. image, document)" }, "fileType": { "type": "string", "title": "Filetype", "description": "File extension (e.g. jpeg, png, pdf)" }, "fileName": { "type": "string", "title": "Filename", "description": "Original file name" }, "fileSize": { "type": "integer", "title": "Filesize", "description": "File size in bytes" }, "timestamp": { "type": "integer", "title": "Timestamp", "description": "Unix timestamp of when the analysis was performed" }, "timestampISO": { "type": "string", "title": "Timestampiso", "description": "ISO 8601 timestamp of when the analysis was performed" }, "model": { "type": "string", "title": "Model", "description": "Model used for analysis (document or object)" }, "modelVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Modelversion", "description": "Version of the model used (e.g. 1.1.0)" }, "likelihood": { "type": "number", "title": "Likelihood", "description": "Fraud likelihood as a percentage (0-100)" }, "fraudSeverity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Fraudseverity", "description": "Fraud severity level: rejected (-1%), low (0-30%), medium (>30-60%), high (>60-90%), or critical (>90-100%)" }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Country", "description": "Normalized country hint for this request (us, mx, br)" }, "classification": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Classification", "description": "Classification label (e.g. authentic, suspicious, verified)" }, "reasoning": { "items": { "type": "string" }, "type": "array", "title": "Reasoning", "description": "List of natural-language explanations for the analysis findings" }, "modelResults": { "additionalProperties": true, "type": "object", "title": "Modelresults", "description": "Technical check results from the model" }, "tags": { "items": { "$ref": "#/components/schemas/Tag" }, "type": "array", "title": "Tags", "description": "Metadata tags attached to this detection", "default": [] }, "files": { "items": { "$ref": "#/components/schemas/FileData" }, "type": "array", "title": "Files", "description": "Associated files (original upload, heatmaps)", "default": [] } }, "type": "object", "required": [ "detectionId", "mediaType", "fileType", "fileName", "fileSize", "timestamp", "timestampISO", "model", "likelihood", "reasoning", "modelResults" ], "title": "FraudDetection" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ModelMetadata": { "properties": { "name": { "type": "string", "title": "Name" }, "description": { "type": "string", "title": "Description" }, "tags": { "items": { "type": "string" }, "type": "array", "title": "Tags" }, "category": { "type": "string", "title": "Category" }, "validInputTypes": { "items": { "type": "string" }, "type": "array", "title": "Validinputtypes" }, "validFileTypes": { "items": { "type": "string" }, "type": "array", "title": "Validfiletypes" }, "ownedBy": { "type": "string", "title": "Ownedby" }, "version": { "type": "string", "title": "Version" } }, "type": "object", "required": [ "name", "description", "tags", "category", "validInputTypes", "validFileTypes", "ownedBy", "version" ], "title": "ModelMetadata" }, "RootModel_list_ModelMetadata__": { "items": { "$ref": "#/components/schemas/ModelMetadata" }, "type": "array", "title": "RootModel[list[ModelMetadata]]" }, "Tag": { "properties": { "name": { "type": "string", "title": "Name", "description": "Tag key name" }, "value": { "type": "string", "title": "Value", "description": "Tag value" } }, "type": "object", "required": [ "name", "value" ], "title": "Tag" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "Verification": { "properties": { "verificationId": { "type": "integer", "title": "Verificationid", "description": "Unique identifier for the verification record" }, "idFileType": { "type": "string", "title": "Idfiletype", "description": "File extension of the ID document (e.g. jpeg, png)" }, "idFileName": { "type": "string", "title": "Idfilename", "description": "Original file name of the ID document" }, "idFileSize": { "type": "integer", "title": "Idfilesize", "description": "ID document file size in bytes" }, "selfieFileType": { "type": "string", "title": "Selfiefiletype", "description": "File extension of the selfie (e.g. jpeg, png)" }, "selfieFileName": { "type": "string", "title": "Selfiefilename", "description": "Original file name of the selfie" }, "selfieFileSize": { "type": "integer", "title": "Selfiefilesize", "description": "Selfie file size in bytes" }, "timestamp": { "type": "integer", "title": "Timestamp", "description": "Unix timestamp of when the verification was performed" }, "timestampISO": { "type": "string", "title": "Timestampiso", "description": "ISO 8601 timestamp of when the verification was performed" }, "model": { "type": "string", "title": "Model", "description": "Model used for verification" }, "modelVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Modelversion", "description": "Version of the model used (e.g. 1.0.0)" }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Country", "description": "Normalized country hint applied to this verification (us, mx, br)" }, "verified": { "type": "boolean", "title": "Verified", "description": "Whether the identity was verified successfully" }, "modelResults": { "additionalProperties": true, "type": "object", "title": "Modelresults", "description": "Technical check results including face match and liveness scores" }, "tags": { "items": { "$ref": "#/components/schemas/Tag" }, "type": "array", "title": "Tags", "description": "Metadata tags attached to this verification", "default": [] }, "files": { "items": { "$ref": "#/components/schemas/FileData" }, "type": "array", "title": "Files", "description": "Associated files (ID document and selfie)", "default": [] } }, "type": "object", "required": [ "verificationId", "idFileType", "idFileName", "idFileSize", "selfieFileType", "selfieFileName", "selfieFileSize", "timestamp", "timestampISO", "model", "verified", "modelResults" ], "title": "Verification" }, "VerificationResponse": { "properties": { "result": { "$ref": "#/components/schemas/Verification", "description": "The verification result" } }, "type": "object", "required": [ "result" ], "title": "VerificationResponse" } }, "securitySchemes": { "API Key": { "type": "apiKey", "description": "API key created in the dashboard", "in": "header", "name": "x-api-key" } } }, "tags": [ { "name": "Fraud Detection", "description": "Detect manipulated or AI-generated content in documents and images." }, { "name": "Document Parsing", "description": "Extract structured data from IDs, bank statements, and pay stubs." }, { "name": "ID Verification", "description": "Match an ID document against a selfie." }, { "name": "File Retrieval", "description": "Fetch original uploads or generated heatmaps from a prior analysis." } ], "servers": [ { "url": "https://api.deepxl.ai", "description": "Production" } ] }