> For the complete documentation index, see [llms.txt](/llms.txt).

# Upload a document

**POST** `https://www.iwoca.de/api/lending/v2.2/document_upload/{customer_id}/`

Upload a customer document. Send PDFs rather than images or word processor files, which take longer for iwoca to process.

Better still, if you have bank statement data collected via Open Banking, send it as a JSON file.
To send multiple bank statements as JSON, make a separate request for each statement.
(Do not combine multiple statements into one file).
See the `bank_statements` endpoint description for how the bank statement JSON can be formatted.

## Request example

This endpoint requires a HTTP multipart form data POST request.
The `document_type` part indicates what kind of document is being uploaded (e.g. bank statement or VAT return).
The `document` part contains the file itself.

This is what the HTTP request body looks like when uploading a short text file called `profit-and-loss.txt`
for the customer id `823de4e0-c741-4fbe-b926-c6c04f5a7c35` using the v2.1 Lending API in the
`stage.iwoca-dev.co.uk` environment:

```
POST /api/lending/v2.1/document_upload/823de4e0-c741-4fbe-b926-c6c04f5a7c35/ HTTP/1.1
Authorization: Bearer 0000000000000000000000000000000000000000
Accept: */*
Cache-Control: no-cache
Host: stage.iwoca-dev.co.uk
Accept-Encoding: gzip, deflate, br
Content-Type: multipart/form-data; boundary=--------------------------630838601337119842678298
Content-Length: 373

----------------------------630838601337119842678298
Content-Disposition: form-data; name="document_type"
Content-Type: text/plain

profit and loss
----------------------------630838601337119842678298
Content-Disposition: form-data; name="document"; filename="profit-and-loss.txt"
Content-Type: text/plain

This is the Profit And Loss Statement for Example Company.
This year, we made...

----------------------------630838601337119842678298--
```

It is uploading the file as the document type 'profit and loss'. To send a PDF bank statement you would:
- In the `document_type` part, replace `profit and loss` with `bank statement`
- In the `document` part, change the `Content-Type` to `application/pdf`

And don't forget to:
- Change the customer ID in the URL to the appropriate customer ID
- Set the headers as appropriate (with the correct `Authorization`, `Content-Length`, `Host` etc.)

## curl example

```bash
curl --request POST \
  --url https://stage.iwoca-dev.co.uk/api/lending/v2.1/document_upload/823de4e0-c741-4fbe-b926-c6c04f5a7c35/ \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer 0000000000000000000000000000000000000000' \
  --header 'Content-Type: multipart/form-data' \
  --form document=@profit-and-loss.txt \
  --form 'document_type=profit and loss'
```

## python3 example

```python
#!/usr/bin/python3

import requests

api_token = "0000000000000000000000000000000000000000"
customer_id = "823de4e0-c741-4fbe-b926-c6c04f5a7c35"
filename = "profit-and-loss.txt"

url = f"https://stage.iwoca-dev.co.uk/api/lending/v2.1/document_upload/{customer_id}/"
headers = {"Authorization": f"Bearer {api_token}"}

with open(filename, "rb") as opened_file:
    files_dict = {"document": (filename, opened_file)}
    form_dict = {"document_type": "profit and loss"}

    response = requests.post(url, files=files_dict, data=form_dict, headers=headers)

    assert response.status_code == 201, response.content.decode()
```


## Path parameters
- `customer_id` (string, required) — The unique customer_id used to represent a customer.

## Responses
### 201 — Success
```json
{
  "data": {
    "document_id": "string",
    "document_name": "string",
    "document_type": "bank statement",
    "upload_date": "2024-01-01T00:00:00Z"
  }
}
```

### 400 — Bad Request
```json
{
  "errors": [
    {
      "code": "string",
      "detail": "string"
    }
  ]
}
```

### 401 — Unauthorized
```json
{
  "errors": [
    {
      "code": "string",
      "detail": "string"
    }
  ]
}
```

### 403 — Permission Denied
```json
{
  "errors": [
    {
      "code": "string",
      "detail": "string"
    }
  ]
}
```

### 406 — Not Acceptable
```json
{
  "errors": [
    {
      "code": "string",
      "detail": "string"
    }
  ]
}
```

### 409 — Conflict
```json
{
  "errors": [
    {
      "code": "string",
      "detail": "string"
    }
  ]
}
```

### 415 — Unsupported Media Type
```json
{
  "errors": [
    {
      "code": "string",
      "detail": "string"
    }
  ]
}
```

### 429 — Too Many Requests
```json
{
  "errors": [
    {
      "code": "string",
      "detail": "string"
    }
  ]
}
```

### 500 — Unexpected Error
```json
{
  "errors": [
    {
      "code": "string",
      "detail": "string"
    }
  ]
}
```

## Example (curl)
```bash
curl 'https://www.iwoca.de/api/lending/v2.2/document_upload/<customer_id>/' \
  --request POST \
  --header 'Authorization: Bearer <api-key>'
```