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

# Upload a document

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

Upload a customer document. For best results, all documents should be in PDF format.

Bank statement data collected via Open Banking can be sent 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",
      "meta": {},
      "source": {
        "parameter": "string",
        "pointer": "string"
      }
    }
  ]
}
```

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

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

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

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

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

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

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

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