Documentation Index
Fetch the complete documentation index at: https://umbrella-docs.info/llms.txt
Use this file to discover all available pages before exploring further.
Forensic Scoring API - Detailed Documentation
The IDCanopy Forensic Scoring API provides banks, lenders, fintechs, and regulated financial institutions with a unified document forensic analysis capability designed to identify fraud indicators, manipulated documents, inconsistencies, and suspicious onboarding artefacts during customer acquisition and lending workflows.
Overview
The service accepts identity documents, payslips, bank statements, and supporting onboarding documentation and returns a normalized forensic assessment response containing:
- Final forensic verdict
- Fraud and manipulation indicators
- Detailed findings
- Advisory risk scoring
- Recommended next actions
- Cross-document and cross-applicant anomaly signals
Authentication
To access the Address Verification API, authentication is required. A Bearer Token must be included in every request.
- Tokens are valid for 60 minutes and must be refreshed after expiration.
- Refer to the Authentication for detailed steps on obtaining a token.
- Include the token in the
Authorization header as follows:
Authorization: Bearer YOUR_ACCESS_TOKEN
API Base URL
Production:
https://api-umbrella.io/api/services
Sandbox:
https://sandbox-umbrella-api.azurewebsites.net/api/services
Endpoints
POST /forensic/cases/analyze
Description
This endpoint orchestrates the complete forensic workflow:
- Case creation
- Document ingestion
- Document normalization
- Forensic analysis
- Verdict generation
- Result normalization
Clients only need to make a single API call.
Request Fields
| Field | Type | Required | Description |
|---|
| applicantId | string | No | External applicant or case reference. Auto-generated if omitted. |
| caseMeta | stringified JSON | No | Additional metadata associated with the case. |
| files1 | file[] | Yes | One or more uploaded files for forensic analysis. |
| files2 | file[] | No | Additional files for forensic analysis. |
| files3 | file[] | No | Additional files for forensic analysis. |
Supported File Types
| Format | Supported |
|---|
| PDF | Yes |
| JPG / JPEG | Yes |
| PNG | Yes |
| TIFF | Yes |
| HEIC | Yes |
Upload Limits
| Limit | Value |
|---|
| Maximum files | 15 |
| Maximum file size | 20 MB |
| Maximum total request size | 50 MB |
Example Request
cURL
curl -X POST "https://umbrella-api.io/api/services/forensic/cases/analyze" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "applicantId=loan-app-001" \
-F 'caseMeta={"source":"bankXZY_onboarding","customerReference":"B99-12345"}' \
-F "files1=@id_front.pdf" \
-F "files2=@payslip.pdf" \
-F "files3=@bank_statement.pdf"
JavaScript Example
const formData = new FormData();
formData.append("applicantId", "loan-app-001");
formData.append(
"caseMeta",
JSON.stringify({
source: "bankXZY_onboarding",
customerReference: "B99-12345",
})
);
formData.append("files1", idFrontFile);
formData.append("files2", payslipFile);
formData.append("files3", bankStatementFile);
const response = await fetch(
"https://umbrella-api.io/api/services/forensic/cases/analyze",
{
method: "POST",
headers: {
Authorization: "Bearer YOUR_API_KEY",
},
body: formData,
}
);
const result = await response.json();
console.log(result.result.verdict);
Successful Response
HTTP Status
Response Body
{
"requestId": "req_7d6a9f9d7b4f",
"product": "FORENSIC_SCORING",
"status": "completed",
"applicantId": "loan-app-001",
"tenantId": "bankXZY",
"createdAt": "2026-09-05T10:00:00Z",
"processingTimeMs": 28431,
"documents": [
{
"documentId": "f2c31c7d-8f4e-4d9b-b9f0-2d6baf5a0a13",
"filename": "payslip.pdf",
"byteSize": 124552,
"contentSha256": "af91db3b9f6d4f1f6c5e5e7a4a9f"
}
],
"result": {
"applicantId": "loan-app-001",
"status": "completed",
"verdict": "ESCALATE",
"reasonCodes": [
"KAZ_BACKDATING"
],
"overrideRulesFired": [
"B2"
],
"explanation": "Bank statement creation date precedes stated period by 14 days.",
"advisoryScore": 38,
"advisoryBand": "REVIEW",
"recommendedAction": "Request current bank statement directly from the issuing institution.",
"findings": [
{
"check_id": "kaz_backdating",
"check_category": "bank_statement",
"severity": "HIGH",
"summary": "Bank statement PDF creation date precedes stated period by 14 days.",
"evidence_quote": "CreationDate: 2026-07-17, period: 2026-08-01–2026-08-31"
}
],
"commercialSignals": [],
"checkerVersion": "0.4.0-phase4",
"analysisTimestamp": "2026-09-05T10:01:42Z"
}
}
Verdicts
| Verdict | Description | Recommended Action |
|---|
| PASS | No significant fraud indicators detected | Proceed with onboarding |
| CONDITIONAL | Minor or contextual issues detected | Proceed with additional conditions |
| ESCALATE | Significant suspicious indicators detected | Route for manual review |
| PENDING | Documents insufficient or unreadable | Request additional documentation |
| REJECT | Deterministic fraud indicators identified | Reject application |
Advisory Risk Bands
| Band | Score Range | Meaning |
|---|
| LOW_RISK | 61 - 100 | Minimal fraud indicators |
| REVIEW | 31 - 60 | Moderate risk profile |
| HIGH_RISK | 0 - 30 | Significant fraud indicators |
Findings
Each forensic response may include one or more findings.
Finding Structure
{
"check_id": "kaz_backdating",
"check_category": "bank_statement",
"severity": "HIGH",
"summary": "Bank statement creation date predates stated period by 14 days.",
"evidence_quote": "CreationDate: 2026-07-17; period: 2026-08-01–2026-08-31",
"source_document_id": "uuid",
"extraction_confidence": 0.97
}
Check Categories
| Category | Description |
|---|
| metadata | File and metadata analysis |
| identity | Identity document analysis |
| payslip | Payslip validation |
| bank_statement | Bank statement analysis |
| cross_document | Cross-document consistency checks |
| cross_applicant | Cross-applicant anomaly detection |
| quality_gate | Image/document quality validation |
Severity Levels
| Severity | Meaning |
|---|
| CRITICAL | Deterministic fraud indicator |
| HIGH | Strong suspicious signal |
| MEDIUM | Moderate concern |
| LOW | Minor anomaly |
| INFO | Informational only |
Common Fraud Signals
Examples of forensic signals that may be identified:
- Metadata tampering
- Document backdating
- Payslip arithmetic inconsistencies
- MRZ checksum failures
- Image manipulation indicators
- Cross-document identity mismatches
- Reused applicant data
- Shared IBAN or salary patterns across applicants
- OCR inconsistencies
- Suspicious PDF generation patterns
Error Responses
{
"error": "ERROR_CODE",
"message": "Human readable description",
"detail": "Additional diagnostic information"
}
Error Codes
| HTTP Status | Error | Meaning |
|---|
| 400 | INVALID_REQUEST | Request validation failed |
| 400 | INVALID_CASE_META | caseMeta JSON invalid |
| 400 | NO_FILES_PROVIDED | No uploaded files supplied |
| 401 | UNAUTHORIZED | Invalid API credentials |
| 403 | FORBIDDEN | Product access denied |
| 409 | DUPLICATE_APPLICANT | Applicant already exists |
| 413 | FILE_TOO_LARGE | File exceeds size limit |
| 413 | TOTAL_UPLOAD_TOO_LARGE | Total upload size exceeded |
| 422 | VALIDATION_ERROR | Semantic validation failure |
| 429 | RATE_LIMITED | Too many requests |
| 500 | FORENSIC_CASE_ANALYSIS_FAILED | Upstream forensic processing failure |
| 503 | QUOTA_EXCEEDED | Monthly quota exceeded |
Processing Behaviour
| Characteristic | Behaviour |
|---|
| Processing mode | Synchronous |
| Typical response time | Under 30 seconds |
| Large batch processing | Available separately |
| Document normalization | Automatic |
| File hashing | SHA-256 |
| Cross-document analysis | Enabled |
| Cross-applicant analysis | Enabled |
Security & Data Handling
- All traffic is encrypted in transit using HTTPS/TLS.
- Uploaded documents are processed within the IDCanopy forensic workflow.
- File hashes are generated for audit and traceability.
- Personally identifiable information (PII) is never included in operational logs.
- Request and response auditing may be enabled for regulated financial institutions.
- GDPR-compliant deletion workflows are supported.
Recommended Integration Pattern
The recommended integration sequence for banks and lenders is:
- Customer onboarding initiated
- Customer uploads identity and financial documents
- Documents submitted to IDCanopy forensic endpoint
- Forensic verdict evaluated
- Decision engine applies policy rules
- Application proceeds, escalates, or rejects
Notes
- The forensic verdict should be used as the primary automated decisioning signal.
- Advisory scoring is informational and should not be used as the sole approval or rejection criterion.
- Some findings may require manual review depending on institutional policy.
- IDCanopy abstracts all upstream forensic provider orchestration and normalization.
Support
For onboarding, credentials, production enablement, or integration support:
