Source: https://docs.debitura.com/collection-partners/integration-guides/upload-files

# 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.

<a id="when-to-use-this"></a>

## 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

<a id="allowed-file-types"></a>

## 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`.

<a id="filenames"></a>

## Filenames

Filenames are preserved exactly as uploaded, including non-ASCII characters such as accented letters or umlauts (for example, `Versäumnisurteil.pdf`). The signed `url` returned by this endpoint, and by the retrieve endpoints (`GET /cases/{id}/files`, `GET /managed-cases/{id}/files`), is always safe to open regardless of what characters the original filename contains.

<a id="visibility"></a>

## Visibility

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

<a id="status-gate"></a>

## 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.

<a id="document-types"></a>

## Document Types

The optional `documentType` field describes what the file is. API names are case-insensitive and surrounding whitespace is ignored. Omit the field when you do not know the type: the file is stored as **Not specified**, returned as `documentType: null`. `Miscellaneous` explicitly means **Other**.

| API name | Use for |
| --- | --- |
| `OriginalInvoice` | Invoice or credit note |
| `AccountStatement` | Statement of account showing invoices, payments, and the outstanding balance |
| `Contract` | Contract or agreement |
| `TermsAndConditions` | Terms and conditions |
| `ProofOfDelivery` | Order or proof of delivery |
| `DemandLetter` | Reminder or demand letter |
| `Correspondence` | Correspondence with the debtor |
| `PaymentProof` | Proof of payment |
| `CourtDocument` | Court or legal document |
| `IdentityDocument` | Identity document |
| `Miscellaneous` | Other supporting documents |
| `DebtorDocuments` | Legacy: dispute documents from the debtor |
| `CreditorDocuments` | Legacy: dispute documents from the creditor |
| `PartnerDocuments` | Legacy: dispute documents from the collection partner |

The three legacy names remain accepted for existing integrations. Prefer the specific document types for new uploads.

Unknown names, numeric values, and `AutoGeneratedSummary` are rejected with `400` and error `InvalidDocumentType`. `AutoGeneratedSummary` is system-only and may appear in file-list responses.

A file's type can change after upload: admins can correct it, and an omitted type may later be filled automatically when automatic classification is enabled. Handle `null` on reads and do not assume it is permanent.

The optional `description` is limited to 500 characters.

<a id="safe-retries"></a>

## 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.

<a id="omitted-vs-blank-keys"></a>

### 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

Present blank keys return `400` on the Customer API's `POST /cases` and `POST /divisions`; this API's `POST /managed-cases`, both case-file upload routes and `POST /managed-clients` (where the key is required); and the Referral Partner API's `POST /clients`, case-file uploads and KYC uploads. Collection Partner `POST /cases/{id}/payments` and `POST /cases/{id}/chats` still treat blank keys as omitted, with no replay protection. Payment keys enforce the 255-character ceiling; chat keys do not. See [Idempotency](https://docs.debitura.com/developer-concepts/idempotency.md) for the general semantics.

<a id="request-example"></a>

## Request Example

Upload is `multipart/form-data`:

```http
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:

```http
POST /managed-cases/{id}/files
```

Using curl:

```bash
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:

```bash
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"
```

<a id="response-example"></a>

## Response Example

```json
{
  "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](https://docs.debitura.com/api/collection-partner.md).