Upload Files

Attach documents and evidence to a case you work or manage.

Choose the endpoint based on your role for that case:

Your role	Upload endpoint	Retrieve endpoint
Assigned collection partner	POST /cases/{id}/files	GET /cases/{id}/files
Managing partner that submitted the case	POST /managed-cases/{id}/files	GET /managed-cases/{id}/files

The file requirements and request format are the same for both upload endpoints.

When to Use This

Upload files when you need to attach:

• The original invoice or claim document
• Correspondence with the debtor (letters, emails)
• Legal filings or court documents
• Payment proof or receipts
• Evidence supporting the claim
• Settlement agreements

Allowed File Types

Extension	Type
.pdf	PDF document
.doc, .docx	Word document
.xls, .xlsx	Excel spreadsheet
.csv	CSV data file
.jpg, .jpeg, .png	Image
.txt	Plain text
.zip	ZIP archive
.eml	Email file

Files outside this list are rejected with 415 Unsupported Media Type.

Maximum size: 25 MB. Files larger than this are rejected with 413 Request Entity Too Large.

Visibility

All files uploaded through this endpoint are visible to the creditor. There is no visibility toggle.

Status Gate

Case Status	File Upload
Active	Allowed
PendingVerification	Allowed
Paused	Allowed
NeedsAdditionalDetails	Allowed
Closed	Allowed
Merged	Rejected (409)

Asymmetry with claim amount edit

File uploads are allowed on Closed cases. This matches the partner portal — you can still add evidence to a closed case. Merged cases are the only status where uploads are blocked.

Document Types

The optional documentType field classifies the file. Values are case-insensitive. If you omit it, the file remains uncategorised and the response returns documentType: null.

Value	Description
OriginalInvoice	The original invoice document
DebtorDocuments	Documents provided by the debtor
CreditorDocuments	Documents provided by the creditor
PartnerDocuments	Documents from the collection partner
DemandLetter	Formal demand letter
Miscellaneous	Other supporting documents

The optional description is limited to 500 characters.

Safe Retries

Add an Idempotency-Key header when a client may retry an upload. The key can contain up to 255 characters.

• Reusing a key with the same file bytes, filename, document type, and description returns the original response without creating another file.
• Reusing a key with different upload data returns 422 Unprocessable Entity.
• If an upload with the same key is still being processed, the API returns 409 Conflict with a Retry-After header. Wait for that interval before retrying.

Without an idempotency key, every request creates a distinct file, even when the filename is the same. Each upload uses a unique storage path, so a later upload never overwrites an earlier one.

Omitted vs. Blank Keys

Leaving the header out entirely is fine — it simply means replay protection is off for that upload. Sending the header with an empty or whitespace-only value is treated differently and is rejected with 400 Bad Request and the message Idempotency-Key must not be empty. A blank key would otherwise be reserved as if it were a real key, so unrelated uploads all sending a blank value would collide with each other.

The rejection happens before the file is buffered, before any reservation is taken, and before the upload runs, so nothing is created. Retry with either a real key or no header at all. The 255-character ceiling still applies on top of this check.

Scope of this check

The blank-value rejection applies to the two upload routes on this API — POST /cases/{id}/files and POST /managed-cases/{id}/files. It is not a platform-wide rule, and the rest of the platform is not uniform either. POST /cases and POST /divisions on the Customer API, POST /managed-cases and POST /ingestion-jobs on this API, and both Referral Partner API endpoints enforce only the length ceiling, so an empty string is accepted as a real key. POST /cases/{id}/payments and POST /cases/{id}/chats on this API do neither — a blank value is silently ignored and the request proceeds with no replay protection at all. See Idempotency for the general semantics.

Request Example

Upload is multipart/form-data:

POST /cases/{id}/files
Content-Type: multipart/form-data
Idempotency-Key: upload-case-file-123

file=@/path/to/invoice.pdf
documentType=OriginalInvoice
description=Original invoice from creditor

For a case you submitted as managing partner, change the request path to:

POST /managed-cases/{id}/files

Using curl:

curl -X POST https://collectionpartner-api.debitura.com/cases/{id}/files \
  -H "XApiKey: your-api-key" \
  -H "Idempotency-Key: upload-case-file-123" \
  -F "file=@invoice.pdf" \
  -F "documentType=OriginalInvoice" \
  -F "description=Original invoice"

Managing-partner example:

curl -X POST https://collectionpartner-api.debitura.com/managed-cases/{id}/files \
  -H "XApiKey: your-api-key" \
  -H "Idempotency-Key: upload-managed-case-file-123" \
  -F "file=@invoice.pdf" \
  -F "documentType=OriginalInvoice" \
  -F "description=Original invoice"

Response Example

{
  "id": "f1e2d3c4-...",
  "fileName": "invoice.pdf",
  "documentType": "OriginalInvoice",
  "dateCreated": "2026-06-01T10:00:00Z",
  "dateUpdated": "2026-06-01T10:00:00Z",
  "caseId": "a1b2c3d4-...",
  "entityType": "Case",
  "entityId": "a1b2c3d4-...",
  "description": "Original invoice from creditor",
  "url": "https://storage.debitura.com/..."
}

The url is a temporary signed link. Generate a fresh URL by calling the retrieve endpoint for your role again if your link expires.

For full endpoint details, see the Collection Partner API reference.