Sharing documents

Sharing additional documents early in the application process is one of the most effective ways to improve outcomes for your customers. Bank transaction data is by far the most valuable thing you can send us – it has the biggest effect on both decision speed and offer quality.

Why sharing additional data matters

For some applications, iwoca can make instant decisions without the applicant needing to send additional documentation. For others, iwoca needs to see business documentation such as bank statements, VAT returns, or company accounts.

You can use our document upload endpoint to send documents to iwoca in advance. This lets iwoca (or its automated systems) make a decision as soon as possible.

Types of data

Open Banking data (highly recommended)

Other supporting data

In addition to Open Banking data, you can upload:

• Bank statements (PDF format)
• Business accounts (filed accounts, management accounts)
• VAT returns
• Corporation tax returns
• Profit and loss statements
• Balance sheets
• Invoice copies and purchase orders

When to upload documents

Upload all available documents before calling GET /offers or GET /login_link. The earlier we have them, the more of the decision we can automate.

If further documents are required, this information will be returned as part of the GET /offers response, or you can ask your iwoca Partnership Manager for specific document requirements in advance.

How to upload documents

1. 1
   Prepare your request

   Make a multipart/form-data POST request to /document_upload/{customer_id} containing two parts: the document file and the document type.

   Recommended formats: PDF format, or JSON format for bank statement data collected via Open Banking. iwoca's operations team will take longer to process other non-PDF files.

2. 2
   Upload the document

   POST /document_upload/{customer_id}

   If successful this will return some details including a document_id. Uploading the same file twice will result in an error.

   A complete list of document types (for example, bank statement, business accounts) and an example request is available in the POST /document_upload/ API reference.

Sending bank statement data in JSON format

If you have bank statement data that was collected via Open Banking, it's possible to send this in JSON format. You can either send a JSON file to the document_upload endpoint or send JSON data in the body of a POST request to the bank_statements endpoint.

Required data points

Include the following mandatory data points:

• Account number.
• Sort code.
• Account holder name.
• Currency.
• Bank name.
• Each transaction must have a date, reference, amount, and running balance.

These data points aren't mandatory, but we prefer them:

• Account type (business or personal)
• Period (date of earliest and latest transaction)

Example JSON format

{
    "data": {
        "accountInfo": {
            "iban": "123",
            "currency": "GBP",
            "accountType": "sole",
            "bankName": "ABCBank",
            "accountId": "account0",
            "accountHolder": "ABC business",
            "accountName": "xyz",
            "type": "Business",
            "subType": "EMoney",
            "availableBalance": 161.16,
            "currentBalance": 161.16,
            "numberOfTransactions": 1,
            "accountNumber": "12345678",
            "sortCode": "123456"
        },
        "transactions": [
            {
                "accountId": "account0",
                "primaryCategoryDescription": "Transfers / Other",
                "subCategoryDescription": "Bank Transfer",
                "description": "Transfer to Main account. Internal transfer out",
                "transactionDate": "2023-03-21T00:00:00+00:00",
                "amount": -100.0,
                "transactionId": 12345676789,
                "runningBalance": 161.16,
                "currencyCode": "GBP"
            }
        ]
    }
}

You can provide a starting balance and closing balance as an alternative to providing a running balance with each transaction.

Checking uploaded documents (optional)

To see a list of documents previously uploaded for a customer you may use GET /document_upload/{customer_id}. For some types of document this will include the acceptance status of the document and certain information iwoca has extracted from it.

A query parameter can optionally be used to make this endpoint return only certain document types.

Understanding the response

The response contains two arrays: data and included:

data - A list of documents uploaded for this customer. Each item contains a document type, an id, and an attributes object. For some document types, attributes will include a status and reject_reason, indicating whether the document was accepted or why it was rejected.

included - Additional information for bank statement documents, such as the bank name and account number. If an item in data has a relationships field, a corresponding entry exists in included. Use the id and type fields to match the two.