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 Format

multipart/form-data

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

200 OK

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 Format

{
  "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:

support@idcanopy.com

​Forensic Scoring API - Detailed Documentation

​Overview

​Authentication

​API Base URL

​Production:

​Sandbox:

​Endpoints

​POST /forensic/cases/analyze

​Description

​Request Format

​Request Fields

​Supported File Types

​Upload Limits

​Example Request

​cURL

​JavaScript Example

​Successful Response

​HTTP Status

​Response Body

​Verdicts

​Advisory Risk Bands

​Findings

​Finding Structure

​Check Categories

​Severity Levels

​Common Fraud Signals

​Error Responses

​Error Format

​Error Codes

​Processing Behaviour

​Security & Data Handling

​Recommended Integration Pattern

​Notes

​Support