Document Uploads#

Document Uploads allow tenants to submit bank statements, paystubs, ID documents, and proof of address. CasaPay performs fraud detection and data extraction on uploaded documents.

The Document Upload object#

Attribute	Type	Description
`id`	string	Unique identifier with `du_` prefix
`object`	string	Always `"document_upload"`
`session`	string	Associated Verification Session ID
`document_type`	enum	`bank_statement`, `paystub`, `id_document`, `proof_of_address`
`status`	enum	`pending`, `processing`, `verified`, `rejected`
`file_name`	string	Original file name
`file_size`	integer	File size in bytes
`mime_type`	string	MIME type of the uploaded file
`irregularity_detection`	object	Fraud detection results
`irregularity_detection.status`	enum	`clear`, `suspicious`, `fraudulent`
`irregularity_detection.reasons`	array	Detected irregularities
`extracted_data`	object	Data extracted from the document
`file_url`	string	Signed URL to retrieve the file (expires in 1 hour)
`created`	timestamp	Time at which the upload was created

{
  "id": "du_xyz789",
  "object": "document_upload",
  "session": "vs_1a2b3c4d5e6f",
  "document_type": "bank_statement",
  "status": "verified",
  "file_name": "bank_statement_jan_2025.pdf",
  "file_size": 245000,
  "mime_type": "application/pdf",
  "irregularity_detection": {
    "status": "clear",
    "reasons": []
  },
  "extracted_data": {
    "institution": "High Street Bank",
    "account_holder": "Jane Doe",
    "period_start": "2025-01-01",
    "period_end": "2025-01-31",
    "opening_balance": 750000,
    "closing_balance": 850000
  },
  "file_url": "https://files.casapay.com/documents/du_xyz789?token=...",
  "created": 1706140800
}

Upload a Document#

Upload a document to a verification session.

POST /v1/document_uploads

Content-Type: multipart/form-data

Parameter	Type	Required	Description
`session`	string	Yes	Verification Session ID
`document_type`	string	Yes	Type of document
`file`	file	Yes	The document file (PDF, PNG, JPG)
`description`	string	No	Optional description

curl https://api.casapay.com/v1/document_uploads \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc" \
  -F "session=vs_1a2b3c4d5e6f" \
  -F "document_type=bank_statement" \
  -F "file=@bank_statement.pdf"

Retrieve a Document Upload#

GET /v1/document_uploads/:id

curl https://api.casapay.com/v1/document_uploads/du_xyz789 \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"

List Document Uploads#

GET /v1/document_uploads

Parameter	Type	Description
`session`	string	Filter by Verification Session ID
`document_type`	string	Filter by document type
`status`	string	Filter by status

curl https://api.casapay.com/v1/document_uploads?session=vs_1a2b3c4d5e6f \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"