Source: https://docs.debitura.com/clients/integration-guides/upload-documents

# Upload Documents

Attach files to a case using `POST /cases/{id}/files`. Documents strengthen collection efforts by providing evidence of the debt.

<a id="upload-a-file"></a>

## Upload a File

Send a multipart form request with the file and optional metadata:

```bash
curl -X POST https://customer-api.debitura.com/cases/{caseId}/files \
  -H "XApiKey: YOUR_API_KEY" \
  -F "File=@invoice.pdf" \
  -F "DocumentType=OriginalInvoice" \
  -F "Description=Invoice #1234 dated 2025-01-15"
```

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

### Request Fields

| Field | Required | Description |
| --- | --- | --- |
| `File` | Yes | The file to upload (binary) |
| `DocumentType` | No | Category for the document; omit to leave it Not specified (`null`) |
| `Description` | No | Human-readable label |

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

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

### Response

```json
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "caseId": "d3051d9e-8b4a-4c5f-9e1a-123456789abc",
  "fileName": "invoice.pdf",
  "documentType": "OriginalInvoice",
  "description": "Invoice #1234 dated 2025-01-15",
  "url": "https://admino.blob.core.windows.net/...",
  "dateCreated": "2025-06-25T10:30:00Z"
}
```

The `url` is a signed download link valid for approximately 1 hour. To get a fresh URL, call the list endpoint again.

<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 `url` returned in the upload response, and any URL returned later by the list endpoint, is always safe to open regardless of what characters the original filename contains.

<a id="list-files"></a>

## List Files

Retrieve all files attached to a case:

```bash
curl https://customer-api.debitura.com/cases/{caseId}/files \
  -H "XApiKey: YOUR_API_KEY"
```

Returns an array of file objects with the same structure as the upload response.

<a id="constraints"></a>

## Constraints

| Constraint | Limit |
| --- | --- |
| Maximum file size | 25 MB |
| Allowed formats | `.pdf`, `.xls`, `.xlsx`, `.jpg`, `.jpeg`, `.png`, `.gif`, `.txt`, `.csv` |

<a id="error-handling"></a>

## Error Handling

| Status | Cause |
| --- | --- |
| `400` | File missing, empty, failed validation, or `InvalidDocumentType` |
| `404` | Case not found or belongs to another account |
| `413` | File exceeds 25 MB limit |
| `415` | File type not in allowed list |

For error response formats, see [Error Handling](https://docs.debitura.com/developer-concepts/error-handling.md).

[Create a case](https://docs.debitura.com/clients/integration-guides/create-a-case.md) before uploading files. See [Track Case Status](https://docs.debitura.com/clients/integration-guides/track-case-status.md) to monitor case progress after submission.