Documents & secure upload
Register expected evidence, upload bytes through a short-lived controlled target, scan and classify before use, review with structured outcomes, and retain integrity and access history.
Document metadata and document bytes cross different boundaries. The API first registers type, file metadata, expected hash, and case; it then returns a short-lived upload target. Files are unavailable to workers and AI until security processing completes.
Lifecycle
Register metadata
curl -X POST "$BASE/v1/servicing/cases/case_CEDAR_HARDSHIP_4/documents" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: cedar-pay-statement-april" \
-d '{
"type": "income_evidence",
"fileName": "pay-statement-april.pdf",
"mediaType": "application/pdf",
"byteLength": 184220,
"sha256": "sha256:2d8c…188a"
}'The response returns documentId and a short-lived upload method/expiry. It does not expose an internal storage path.
Security processing
Controls validate declared size, actual bytes, digest, media type, file structure, malware, encryption policy, and archive contents. A clean scan means the file passed those controls; it does not mean its claims are true.
Structured review
POST /v1/servicing/documents/{documentId}/review records accepted, rejected, or approved reclassification plus reviewer and note. Accepted evidence can support a case decision; rejected evidence remains in history with restricted access and retention policy.
Provenance classes
| Source | Key evidence |
|---|---|
| Customer upload | Authenticated/verified upload session, request, time, and hash. |
| Worker upload | Actor, case, reason, source, and hash. |
| Provider document | Provider reference, signature/transport verification, and normalized type. |
| System-generated | Template version, fact snapshot, render hash, and generator time. |
Access and download
GET /v1/servicing/documents/{documentId}/download evaluates current permission and returns a short-lived tenant-scoped URL plus hash. Every sensitive access is audited. AI packets receive only explicitly permitted document content or extraction, never an ambient case-folder mount.
Retention
Retention policy considers document class, legal entity, case state, disputes, investigations, and legal hold. Disposal is an auditable lifecycle event. A hold blocks scheduled disposal; closing the case does not automatically delete evidence.