Document Verification & Tamper Detection (/api/v1/uploads)

Document upload, retrieval, verification (with extraction), and standalone tamper analysis.

All endpoints require authentication via X-API-Key.

---

1. Upload a Document

Uploads a file for a given document type. The multipart field name must be exactly doc. If a document of the same type already exists, it is replaced.

• Method: POST
• Endpoint: /api/v1/uploads/docs/:docType
• Headers:
  • Content-Type: multipart/form-data

Field (form)	Type	Description
doc	File	The document file (PDF, max 10MB)

Path param: docType — e.g., bank_statements, credit_score, passport, driving_license, tax_returns, pay_stubs, mortgage_statements, business_p_and_l, etc.

Response (201 Created)

{
  "message": "File uploaded successfully.",
  "document": {
    "id": "doc-uuid",
    "docType": "bank_statements",
    "url": "https://storage.googleapis.com/...",
    "filename": "statement.pdf",
    "fileSize": 123456,
    "createdAt": "2025-01-01T00:00:00.000Z"
  }
}

---

2. Verify Document & Extract Data

Triggers verification (tamper check + name matching) and structured extraction for an existing uploaded document. Consumes credits (DOC_EXTRACTION).

• Method: POST
• Endpoint: /api/v1/uploads/docs/:id/verify
• Headers: Content-Type: application/json

Request Body

Parameter	Type	Description
forceExtraction	Boolean	If true, forces extraction even if tampering or name mismatch is detected

{ "forceExtraction": false }

Response

Field	Type	Description
documentId	String	The ID of the verified document
verified	Boolean	Overall verification status (true if both tamper check and name match pass)
verification.verified	Boolean	Verification result
verification.reason	String	Detailed reason for the status
verification.extractedName	String	The name extracted from the document (or null)
verification.userName	String	The user's registered name for comparison
verification.forcedExtraction	Boolean	Whether forced extraction was used
verification.dataExtracted	Boolean	Whether data was extracted and saved
verification.tamperStatus	String	Tamper check verdict (No Tampering Evidence, Tampered, Error)
verification.nameMatchStatus	String	Name match result (Matched, Mismatch (...), Not Found)

{
  "documentId": "doc-uuid",
  "verified": true,
  "verification": {
    "verified": true,
    "reason": "Document verified successfully",
    "extractedName": "John Doe",
    "userName": "John Doe",
    "forcedExtraction": false,
    "dataExtracted": true,
    "tamperStatus": "No Tampering Evidence",
    "nameMatchStatus": "Matched"
  }
}

Verification Logic

1. Tamper check — The document is analyzed for digital tampering.
2. Extraction — Structured data is extracted from the document via AI.
3. Name match — The extracted name is compared against the user's registered name.
4. Result — If all checks pass, the document is marked verified and data is saved. If forceExtraction is true, extraction proceeds regardless of tampering or name mismatch.

---

3. Standalone Tamper Check

Analyzes a file for tampering without persisting it as a stored document. Consumes credits (TAMPER_VERIFICATION).

• Method: POST
• Endpoint: /api/v1/uploads/tamper
• Headers: Content-Type: multipart/form-data

Field (form)	Type	Description
doc	File	PDF or supported document to scan

cURL

curl -X POST https://api.riskinmind.ai/api/v1/uploads/tamper \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "doc=@/path/to/bank_statement.pdf"

Response

{
  "filename": "bank_statement.pdf",
  "tamperCheck": {
    "isTampered": false,
    "verdict": "No Tampering Evidence",
    "confidence": "HIGH",
    "riskScore": 0.05,
    "reasons": []
  },
  "analysis": {
    "verdict": "No Tampering Evidence",
    "confidence": "HIGH",
    "risk_score": 0.05,
    "reasons": []
  }
}

Field	Type	Description
tamperCheck.isTampered	Boolean	Whether tampering was detected
tamperCheck.verdict	String	Verdict string
tamperCheck.confidence	String	Confidence level (HIGH, MEDIUM, LOW)
tamperCheck.riskScore	Number	Numeric risk score (0-1)
tamperCheck.reasons	Array	Top reasons if tampered (max 3)

---

4. Get Document by ID

Retrieve an uploaded document's metadata.

• Method: GET
• Endpoint: /api/v1/uploads/docs/:id

Response

{
  "message": "Document retrieved successfully.",
  "document": {
    "id": "uuid",
    "docType": "bank_statements",
    "url": "https://storage.googleapis.com/...",
    "publicId": "file-name",
    "isVerified": true,
    "tamperStatus": "No Tampering Evidence",
    "nameMatchStatus": "Matched",
    "filename": "statement.pdf",
    "fileSize": 123456,
    "mimeType": "application/pdf",
    "createdAt": "2025-01-01T00:00:00.000Z",
    "updatedAt": "2025-01-01T00:00:00.000Z",
    "signedUrl": "https://storage.googleapis.com/..."
  }
}

---

5. Delete Document

Delete an uploaded document from both storage and the database.

• Method: DELETE
• Endpoint: /api/v1/uploads/docs/:id

Response

{ "message": "Document deleted successfully." }