Upload a document

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

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

#!/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()