# iwoca Lending API — Full documentation

> Everything an integrator needs, in one file. Guides first, then the full API reference.

---

## Guides

<!-- llms-section: guides/additional-concepts/funding-account-details -->
### Funding account details
_Pre-populate customer bank account information to streamline drawdown_

Pre-populate customer bank account information to streamline the drawdown process.

## What are funding account details?

The funding account details endpoint lets you share your customer's bank account information with iwoca during the application process.
This pre-populates the account details where funds will be sent, saving the customer time when they're ready to draw down.

The bank details you share are automatically added to the customer's account.
The customer can review those details before drawing down.

## Why share funding account details?

**Faster drawdown**
Customers can access their funds more quickly without needing to manually enter their bank details.

**Seamless integration**
If you offer current accounts, you can have loan funds paid directly into your customer's account on your platform.

**Reduced errors**
Pre-populated information reduces the risk of customers entering incorrect account details.

## How it works

<Steps>
  <Step title="Use the bank details you already hold">
    Use the bank account details you already hold for the customer, or collect them during your application flow if you don't.
  </Step>
  <Step title="Submit to iwoca">
    Submit the details using the `POST /funding_account_details/` endpoint after creating an application.
  </Step>
  <Step title="Customer reviews">
    The customer reviews the pre-populated details in their iwoca account.
  </Step>
  <Step title="Drawdown">
    The customer proceeds with drawdown using the verified account information.
  </Step>
</Steps>

<Info>
**Note**: This endpoint can only be used after an application has been created for the customer.
</Info>

## Customer control

The customer always has final control:

- They can review the pre-populated information before drawing down.
- They can edit or change the account details if needed.
- They must confirm the details before funds are transferred.

## Next steps

<CardGroup cols={2}>
  <Card title="API reference" icon="code" href="/api-reference/overview">
    Funding Account Details endpoint specifications
  </Card>
</CardGroup>

---

<!-- llms-section: guides/additional-concepts/prequalification -->
### Prequalification
_Show customers personalised loan amounts before they apply_

Prequalify your customers for lending offers before they've even applied.
Show them personalised loan amounts based on their business data, making your marketing more effective than generic campaigns.
Prequalification is only worthwhile if you can give us a reasonable indication of each customer's revenue – without it, we can't estimate an amount for them.

<Info>
**Not enabled by default.** The prequalification endpoint must be switched on for your account before you can use it.
To get started, contact your iwoca Partnership Manager or email [partners@iwoca.co.uk](mailto:partners@iwoca.co.uk).
</Info>

## What is prequalification?

Prequalification gives you estimated loan amounts for your customers without requiring them to complete a full application.
These prequalified offers show customers how much they could potentially borrow from iwoca, allowing them to make informed decisions about whether to proceed.

You can use prequalification quotes to:

- Surface offers within your application or dashboard
- Power targeted email campaigns
- Send push notifications to customers with relevant offers

<Info>
**Why implement prequalification?** We've found prequalification is a great mechanism to increase application rates, helping your customers get the funding they need.
</Info>

## How prequalification works

<Steps>
  <Step title="Share customer data">
    Upload your customers' business information through a CSV file via our API.
    You'll typically provide:

    - External customer ID (your internal reference)
    - Company registration number
    - SIC or MCC code (industry classification)
    - Average monthly turnover

    The CSV file can contain up to 1,000 unique customers per upload.
    You can share this file using the below endpoint:

    ```http
    POST /prequalification_data
    ```

    **Response:** You'll receive a `prequalification_data_id` — the ID of the processed file (a filename-style string) that you pass to `GET /prequalification_data` to retrieve the quotes.

    <Info>
    Check with your iwoca Partnership Manager about which data files are required.
    </Info>
  </Step>
  <Step title="We process automatically">
    Our system processes the shared data to create a prequalified offer of how much we think we could lend, if the customer were to be approved.
    At this stage, we don't run any credit decisions on your customer (we only do this when your customer applies for a loan).
  </Step>
  <Step title="Receive prequalification quotes">
    Once processing is complete, you can access prequalification quotes in two ways:

    **Option 1: Webhook with full quotes (recommended)**
    Receive the complete prequalification quotes directly in the webhook payload, allowing immediate access without an additional API call.
    For this option, you must subscribe to the following webhook:

    ```text
    prequalification_202505
    ```

    **Option 2: Webhook with file ID + API request**
    Receive a webhook notification containing the `prequalification_data_id` when quotes are ready.
    Use this ID to retrieve quotes via the API. For this option, subscribe to the following webhook:

    ```text
    prequalification_data_file_processed_202510
    ```

    You can then fetch all quotes or filter by `external_customer_id` or `prequalification_data_id`.
    Retrieve quotes at any time by calling:

    ```http
    GET /prequalification_data
    ```

    See the [Get Prequalification Data](/api-reference/prequalification/get-prequalification-data) endpoint reference for details.
  </Step>
  <Step title="Engage your customers">
    With the prequalified quotes, you can encourage customers to create an application through email campaigns, push notifications, or in-app messaging.

    Each prequalified quote covers a single customer and shows whether they're prequalified.
    If they are, it includes the prequalified offer amount. Some customers won't be prequalified because they don't qualify or we don't have enough data to generate a prequalified offer amount.

    Every prequalified quote has a `marketing_type` field which suggests how you should market to your customers.
    There are three options:

    | Marketing type | Description |
    |---|---|
    | `prequalified_marketing` | Customer is prequalified with a specific amount. Use the amount in your marketing. |
    | `generic_marketing` | Customer may be eligible but we can't determine a specific amount. Use generic lending marketing. |
    | `no_marketing` | Customer is not eligible. Do not market lending to this customer. |
  </Step>
  <Step title="Update quotes regularly">
    As long as you keep sharing your customers' turnover data, we regenerate prequalification quotes each time you send us a new file, so your offers stay current as businesses grow and circumstances change.
    Most partners send a new file monthly.

    You'll receive webhook notifications for each update, or you can retrieve the latest quotes via the API at any time.
  </Step>
</Steps>

## Prequalification webhooks

There are two webhook events for prequalification:

<AccordionGroup>
  <Accordion title="prequalification_202505 (recommended)">
    Fired when a prequalification data file has been processed.
    Contains the full quotes directly in the payload, so you don't need an additional API call.

    **Payload fields:** Array of `quote_id`, `external_customer_id`, `is_prequalified`, `prequalified_amount`, `marketing_type`

    ```json
    {
      "event_type": "prequalification_202505",
      "timestamp": "2026-01-15T10:30:00Z",
      "data": [
        {
          "quote_id": "1c6e2a6f-41ed-490e-8d05-87e34e756f7a",
          "external_customer_id": "16aa735d-9890-479d-8cce-89d5c1c1df3d",
          "is_prequalified": true,
          "prequalified_amount": 10000,
          "marketing_type": "prequalified_marketing"
        },
        {
          "quote_id": "97976169-e0ff-4b60-afd0-869133a49828",
          "external_customer_id": "c21a167f-7aef-47f1-aeb6-c4d2c3d7799d",
          "is_prequalified": false,
          "prequalified_amount": null,
          "marketing_type": "generic_marketing"
        }
      ]
    }
    ```

    **Marketing types:**

    | Type | Description |
    |---|---|
    | `prequalified_marketing` | Eligible with a predicted offer amount – show amount in marketing. |
    | `generic_marketing` | Could be eligible but no amount available – use generic marketing. |
    | `no_marketing` | Not eligible due to failing eligibility criteria – do not market. |
  </Accordion>
  <Accordion title="prequalification_data_file_processed_202510">
    Lighter alternative.
    Fired when a prequalification data file has been processed, but only contains the file identifier.
    Use this ID with `GET /prequalification_data` to retrieve the quotes.

    **Payload fields:** `prequalification_data_id`

    ```json
    {
      "event_type": "prequalification_data_file_processed_202510",
      "timestamp": "2026-01-15T10:30:00Z",
      "data": {
        "prequalification_data_id": "file-uploaded-for-prequalification.csv"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## From prequalification to application

When a prequalified customer is ready to apply, they follow the same application process as any other customer.
Kick off the application using the integration steps for your chosen path: [API Lite](/guides/integration-options/referral-api-integration#integration-steps) or [API Plus](/guides/integration-options/enhanced-integration#integration-steps).

---

## Next steps

<CardGroup cols={2}>
  <Card title="API reference" icon="code" href="/api-reference/prequalification/overview">
    Prequalification endpoint specifications
  </Card>
  <Card title="Webhooks" icon="bell" href="/guides/webhooks/overview">
    Set up real-time notifications
  </Card>
</CardGroup>

---

<!-- llms-section: guides/additional-concepts/repayment-schedule -->
### Repayment Schedule
_Generate detailed repayment breakdowns to help customers plan their cash flow_

The repayment schedule endpoint generates a detailed breakdown of loan repayments for a specific confirmed offer.
This helps customers understand exactly what they'll pay and when, building confidence and transparency before they commit.

## Why repayment schedules matter to your customers

Showing customers a clear repayment schedule upfront helps them plan their cash flow, compare different loan amounts, and make informed decisions.
Transparency around repayments improves conversion rates and reduces questions later in the process.

## How it works

<Steps>
  <Step title="Retrieve a confirmed offer">
    First, retrieve the customer's offers using `GET /offers/`.
    You'll need the `offer_id` of a confirmed offer – repayment schedules are only generated for confirmed offers.
  </Step>
  <Step title="Request the repayment schedule">
    Use the `offer_id` to generate a repayment schedule:

    ```http
    GET /offers/{offer_id}/repayment_schedule/
    ```
  </Step>
  <Step title="Customise with parameters (optional)">
    You can optionally include query parameters:

    - **`amount=[number]`** – Sets a simulated draw down amount (minimum 100, maximum is the offer max amount).
    - **`pay_off_early_on=[date]`** – Simulates early repayment; specify the last payment date in the format `YYYY-MM-DD`.

    Requests can include none, either, or both parameters.
  </Step>
</Steps>

<Info>
**PDF output**: An HTTP request with an `Accept` header of `application/pdf` will generate a PDF document with the proposed repayment schedule and the applicant's information.
</Info>

<Warning>
**Note**: This endpoint only works for confirmed offers.
</Warning>

---

<!-- llms-section: guides/additional-concepts/sharing-documents -->
### Sharing documents
_Upload documents and bank statements to improve outcomes for your customers_

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)

<Tip>
**JSON is our preferred format for bank statements.**
Structured JSON from Open Banking is faster and more reliable for us to process than PDFs, which means quicker decisions and more competitive offers.
See [Sending bank statement data in JSON format](#sending-bank-statement-data-in-json-format) below.
</Tip>

### 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**

<Info>
**The more, the better**: Each additional document helps us build a more complete picture of the business, improving both offer quality and speed.
</Info>

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

<Steps>
  <Step title="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.
  </Step>
  <Step title="Upload the document">
    ```http
    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.
  </Step>
</Steps>

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

<Info>
**iwoca is flexible with the format of the data**, but please inform your iwoca Partnership Manager of your desired format in advance.
</Info>

### 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)

<Warning>
**Important**: Please only send one bank account per request/file, and only send JSON for bank statement data collected via Open Banking.
</Warning>

### Example JSON format

```json
{
    "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.

<Info>
Example: a VAT return might be rejected with `DETAILED_PNL_SECTION_MISSING`.
</Info>

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

<Warning>
**Important**: When sharing customer data with iwoca, make sure your privacy policy and customer consent process supports this data sharing.
</Warning>

---

<!-- llms-section: guides/brokers/overview -->
### Broker integration guidance
_How iwoca works for brokers and hybrid partners_

<Info>
This section is under maintenance – we're rewriting it, so it's light on detail for now.
Your iwoca technical contact can help in the meantime.
</Info>

---

<!-- llms-section: guides/general/api-versioning-policy -->
### API versioning policy
_How iwoca manages API versions, upgrades, and deprecation_

## What this policy covers

This policy outlines how iwoca manages API versions and upgrades.
It covers how we handle backwards incompatible API changes and how we communicate the deprecation and removal of older versions.

## Versioning strategy

iwoca will not make backwards incompatible changes to current API versions.

<AccordionGroup>
  <Accordion title="Backwards compatible changes">
    Backwards compatible changes may be released into existing versions.
    These changes include:

    - Adding new endpoints.
    - Adding new optional fields to request bodies or parameters.
    - Adding new fields to existing API responses.
      Note that this does not include changing the structure of existing fields, which would be considered a backwards incompatible change.
    - Making changes to the OpenAPI schema for the API when this does not affect the behaviour of the API.
  </Accordion>
  <Accordion title="Backwards incompatible changes">
    When iwoca makes a backwards incompatible change, it will be released as a new numbered version of the API.
    This approach ensures that existing integrations remain functional and users have the option to upgrade and benefit from new features.
  </Accordion>
</AccordionGroup>

## Version numbering

iwoca uses a numbering system to mark API versions.
If we make a backwards compatible change, it will be released to existing versions and we will not increment the version number.

| Type | Description | Example |
|---|---|---|
| **Minor** | Most common upgrade. Released for smaller backwards incompatible changes. | v2.1 → v2.2 |
| **Major** | Significant structural changes to the API. | v1.0 → v2.0 |

## Version release schedule

iwoca does not follow a set schedule for releasing new versions.
New versions are released when we want to add a new feature that would require a backwards incompatible change.
We may also use new versions to simplify the API, for example by removing fields that are no longer necessary.

## Version deprecation policy

iwoca supports multiple versions of the API at the same time, but occasionally previous versions of the API may be deprecated when we release a new version.
iwoca will notify partners when a version of the API is deprecated.

<Warning>
iwoca will give at least **one year's notice** before a deprecated version is made unavailable.
</Warning>

## How to upgrade API versions

If you're planning to upgrade to a new API version or need assistance, please contact us via your usual channel or at [partners@iwoca.co.uk](mailto:partners@iwoca.co.uk).

<Info>
Your existing API tokens will work across all versions – you don't need to request replacement tokens during an upgrade.
Ask us for a summary of changes between versions.
</Info>

---

<!-- llms-section: guides/general/dsla -->
### Developer Services Licence Agreement
_Terms and conditions for using iwoca's Developer Services and Lending API_

<Info>
Last updated: March 19, 2018 (Version 1.5)
</Info>

The following Developer Services Licence Agreement (DSLA) applies where you use our Developer Services including the iwoca Lending API. By proceeding to access or use the Developer Services, You accept this DSLA and bind yourself and the business or entity that you represent to it. If you do not accept this DSLA (or any part of it) you must not access or use our Developer Services.

You may not access or use the Developer Services if you are prevented from doing so under the laws of any territory including the territory in which you are resident.

## 1. Definitions and Interpretation

1.1 The following definitions apply to this DSLA:

- **"Affiliate"** means any entity that directly or indirectly controls, is controlled by, or is under common control with the subject entity. For the purposes of this definition, **"Control"** means direct or indirect ownership or control of more than 50% of the voting interests in the subject entity;
- **"API"** means the application program interface specifically created for, and used within, the iwoca Software and Services and its associated documentation and other materials that we may make available to you from time to time;
- **"Application"** means your own software and/or services developed using the Developer Services or with data derived from calls to components within Developer Services;
- **"Customer"** means either (i) an end user of iwoca Software and Services or (ii) an end user of your Application;
- **"Developer Services"** means the API and/or any additional software development tools iwoca may make available to you from time to time;
- **"IPR"** means all vested contingent and future intellectual property rights including goodwill, reputation, rights in confidential information, rights to sue for passing off or unfair competition, copyright, trademarks and design rights whether registered or unregistered, logos, devices, plans, models, diagrams, specifications, source and object code materials, data and processes, patents, know-how, trade secrets, inventions, get-up, database rights and (as applicable) any applications or registrations for the protection of these rights and renewals and extensions of them, existing in any part of the world, whether now known or created in the future;
- **"iwoca Marks"** any name, trademark, logo, symbol or slogan (whether registered or not) owned or used by us or any of our Affiliates now or in the future anywhere in the world, including but not limited to the word mark "iwoca";
- **"iwoca Software and Services"** means iwoca's proprietary software and services for which the Developer Services has been developed;
- **"Partner Agreement"** means any agreement or agreements setting out the terms upon which you are providing services to or receiving services from iwoca;
- **"we" "us" "our" or "iwoca"** means the relevant iwoca entity as set out in your Partner Agreement;
- **"you" "your"** means the individual, business or entity accepting this DSLA.

1.2 A reference to a statute, statutory provision or subordinate legislation is a reference to it as it is in force from time to time and includes any statute, statutory provision or subordinate legislation which it amends or re-enacts.

1.3 Other technical expressions relating to computers and/or software programs shall have the meaning commonly attributed to them in the computer and IT industry.

## 2. Use of the Developer Services

2.1 Subject to your compliance with all of the provisions of this DSLA we now grant you a limited, worldwide, royalty free, revocable, non-assignable and non-exclusive personal licence to access and use the Developer Services solely to develop Applications and for related testing only.

2.2 The Developer Services is licensed as a single product.

2.3 You acknowledge and agree that we own all right, title and interest in and to the Developer Services and the iwoca Marks, and all IPR therein. We reserve all rights not expressly granted under this DSLA. You may only access and use the Developer Services for the express purpose set out in this DSLA. In particular, you must not and must not allow anyone else to:

1. work around any technical limitations in the Developer Services;
2. other than in accordance with section 2.4.7 below and as otherwise expressly set out in this DSLA, distribute, redistribute, make copies of, sell or otherwise commercially exploit the Developer Services (or any part of it);
3. reverse engineer, decompile or disassemble the Developer Services, other than (and only) to the extent that applicable law expressly permits or with our prior written consent;
4. access or use the Developer Services for any immoral, illegal or any other purpose which may be threatening, abusive or harmful including but not limited to the creation or transmission of any virus, Trojan horse, worm or other destructive or contaminating program;
5. circumvent technological measures to prevent direct database access, nor manufacture tools or products to that effect nor build conversion functionality that converts any end user data from iwoca Software and Services to a competing product or service;
6. for the purpose of incorporation into or the development of any software or other product or technology which competes with iwoca Software and Services, use or copy (irrespective of the extent of copying) the whole or any part of the Developer Services operating logic or underlying database structure and database fields; or
7. unless we expressly permit, allow others to modify or distribute the Developer Services.

2.4 You understand that your access, use and distribution of certain components of the Developer Services may be subject to additional terms (including third party licence terms) and that such components are governed by those terms in addition to this DSLA. Where there is a conflict between this DSLA and any additional terms accompanying the applicable component of the Developer Services, those additional terms shall prevail in respect of the conflicting subject matter.

2.5 Your right to access or use the Developer Services may be time limited (as otherwise notified by us) or may be subject to obtaining other rights from a third party including but not limited to a third party platform provider.

2.6 You may not access or use the Developer Services in any way that could damage iwoca Software and Services or any third party's use of them.

2.7 You agree to access and use the Developer Services in accordance with this DSLA and all applicable laws and to develop Applications that comply with all applicable laws.

2.8 You are solely responsible for your access and use of the Developer Services and for your own and any third party applications, data or other content which you access via the Developer Services and we shall have no liability in respect of such applications, data and other content. Any exchange of data between you and a third party is solely between you and that third party.

2.9 You acknowledge that you are not granted any right under this DSLA to sell or distribute the iwoca Software and Services or the Developer Services. Such right, if any, will be granted only under a separate agreement with us.

## 3. Your Obligations

3.1 You must ensure that you provide us with full and accurate registration information upon registration for access and use of the Developer Services and during the term of this DSLA.

3.2 You must maintain your user credentials (including usernames and password) in confidence. You remain fully responsible for all use of and access to the Developer Services using your user credentials.

3.3 You agree to restrict access to and use of the Developer Services and if applicable to any iwoca Software and Services so that only those employees of yours with a need to know may see, access or use the Developer Services and if applicable, the iwoca Software and Services.

3.4 Subject to your compliance with this DSLA, you may develop your own Applications providing that:

1. prior to distribution to a third party, your Application is sufficiently tested to ensure that it:
   1. provides the functions and facilities and performs as described by you; and
   2. will not adversely affect the functions and facilities of any iwoca Software and Services with which your Application is intended to or may be used;
2. you make clear to every licensee or third party user of your Application that your Application belongs to you and that you are solely responsible for any such Application and any issues associated with it. Under no circumstances will we be liable and/or responsible.
3. For the avoidance of doubt, we will not be responsible for any customer support of Applications. You shall be solely responsible, at your expense, for providing customer support to end users, customers and distributors of Applications.

3.5 Whilst it is impossible to provide an exhaustive list of exactly what constitutes acceptable and unacceptable use of the Developer Services, you must not access or use the Developer Services in a way that could interfere with or disrupt the availability or integrity of the Developer Services or any data or any of our products or services. You must ensure that you access and use the Developer Services in a secure way at all times and that your Applications which interact with iwoca Software and Services will remain secure and that they will not compromise the iwoca Software and Services or any data contained within iwoca Software and Services or any third party services.

3.6 If you integrate your Application with any iwoca Software and Services or any other product or services, you remain solely responsible for any such Application and any issues associated with it. Under no circumstances will we be liable and/or responsible.

3.7 We may from time to time modify, update, suspend or terminate the Developer Services or any part of the Developer Services at our discretion by providing reasonable notice to you. We make no guarantee that the Developer Services will be readily available, suitable for your intended use or error or bug-free. You understand and acknowledge that as a consequence the Developer Services may become incompatible with applications developed using earlier versions of the Developer Services. It is your responsibility to ensure that you access and use the latest version of the Developer Services.

## 4. Technical Support

4.1 We have no obligation to support the Developer Services. We may (at our sole discretion) choose to offer support in respect of the Developer Services. Any such support will be subject to our own policies at that time (which we may change at any time at our discretion). We may end any support of the Developer Services at any time and without notice or other obligation to you. In all cases, support excludes any support of third party applications or services.

## 5. Duration and Termination

5.1 This DSLA will continue until terminated as provided in this Section 5.

5.2 You may terminate this DSLA by ceasing use of the Developer Services and access to our Developer Services site.

5.3 We may terminate without cause this DSLA and your access and use of the Developer Services giving reasonable notice at any time.

5.4 In addition to our right to terminate this DSLA, we may also suspend your access and use of the Developer Services at any time if we suspect that you have breached any part of this DSLA. Any suspension of your access and use of the Developer Services will continue until such time that the breach in question has been remedied to our reasonable satisfaction. Where we suspend your access and use of the Developer Services under this clause, we may at our discretion agree to reactivate your use and access.

## 6. Effect of termination

6.1 Where this DSLA is terminated, you will:

1. cease to be entitled to receive any rights or benefits associated with it;
2. immediately cease access and use of the Developer Services;
3. (if applicable) discontinue use of the iwoca Mark; and
4. destroy all materials and other documentation which you obtained in relation to or as a result of entering into this DSLA.

6.2 Termination of this DSLA will not affect any accrued rights or liabilities of either party or the coming into force or continuance in force of any provision of this DSLA which is expressly or by implication intended to come into force or continue in force on or after Termination.

## 7. Warranties and Liability

7.1 If you are agreeing to be bound by this DSLA on behalf of any business or entity, you represent and warrant that you have full legal authority to bind such business or entity to this DSLA. If you do not have authority, you must not accept this DSLA or access nor use the Developer Services on behalf of that business or entity.

7.2 You agree that (i) the developer services is provided "as-is" and no representations, conditions, warranties or other terms of any kind are given in respect of it; (ii) we have no obligation to make the Developer Services available and your access and use of the Developer Services is entirely at your discretion, and (iii) prior to making any application available to any third party, you will undertake rigorous testing of the application in a test environment, and (iv) you will not use any Customer data when testing the application in a test environment.

7.3 Nothing in this agreement seeks to limit or exclude our own, our affiliates or our licensors liability for: death and personal injury resulting from that party's own or its employees' negligence; or (ii) liability arising as a result of such party's fraud or fraudulent misrepresentation; or (iii) any other liability that cannot be excluded or limited by applicable law.

7.4 Subject to section 7.3 above, to the extent permitted by law, we, our affiliates and our licensors shall have no liability of any kind to you in any circumstances whatever in respect of this DSLA and your use of the Developer Services. In particular, we, our affiliates and our licensors shall have no liability (whether in contract, tort (including negligence) or otherwise) for any indirect, special, consequential or exemplary loss or damage that you may suffer in connection with this DSLA or your access and use of the Developer Services or for any loss or corruption of data (however caused).

7.5 Each party acknowledges that the exclusions contained in section 7.4 above are reasonable as we are not obliged to make the Developer Services available to you and that it is entirely up to you whether or not you access and use the Developer Services for your own commercial purposes.

7.6 You agree to defend and hold us, our Affiliates and our third party licensors harmless from and against any claims, demands, proceedings, liabilities, losses, damages, costs and expenses (including reasonable legal fees) arising out of or in relation to (i) your access or use of the Developer Services; (ii) any Application you develop using the Developer Services including but not limited to any third parties use of any such Application; and (iii) any breach of this DSLA by you. Without limiting the previous sentence, you warrant that each Application is and will be developed and owned by you and you will defend us and other companies within our group from and against any claim or action that the use or possession of your Application (or any part) infringes the IPR of a third party ("IPR Claim") and you will indemnify us and other companies within our group from and against any losses, damages, costs (including legal fees) and expenses incurred by or awarded against us and any other company in our group as a result of, or in connection with, that IPR Claim. The indemnities and warranty in this clause will remain in full force and effect irrespective of any termination of this DSLA.

7.7 We agree to defend you against any claim or action that the Developer Services (or any part) infringes the IPR of a third party ("DS IPR Claim") and we will indemnify you from and against any losses, damages, costs (including legal fees) and expenses incurred by or awarded against you as a result of, or in connection with, that DS IPR Claim. The indemnities and warranty in this clause will remain in full force and effect irrespective of any termination of this DSLA.

## 8. Our rights

8.1 We may decide at any time to charge fees for access and use of the Developer Services. In such circumstances, we will publish our intention to do so and establish the terms relating to such fees. If you do not wish to pay such fees, you must stop accessing and using the Developer Services prior to the commencement of the period from which fees will become chargeable.

8.2 We, our licensors or our Affiliates (as applicable) own and will continue to own IPR in and to the Developer Services including any copies. Other than as expressly permitted under this DSLA, you will not use, or permit any third party to use, any of our IPR, including without limit the iwoca Marks, or any mark, words, logo, device or any other branding which is similar to or mimics any iwoca Marks, without first obtaining our prior written consent.

8.3 You agree not to remove, obscure or alter any proprietary rights notices that appear within or upon any part of the Developer Services.

8.4 You agree that we may use any information that you provide to us on an unrestricted basis to improve and develop our software and services.

## 9. Privacy

9.1 Some Developer Services features connect to iwoca information technology services and infrastructure and transmit data to them. By accessing and using the Developer Services, you consent to the transmission of this information.

9.2 The iwoca Software and Services and/or the Developer Services may contain technologies that monitor, record and report to iwoca information regarding the use of the iwoca Software and Services and the Developer Services, including but not limited to information concerning the computer or workstation, or personal digital assistant, or smart phone or other similar electronic device with which the iwoca Software and Services or the Developer Services operates; the frequency, type and manner of use to which the iwoca Software and Services or the Developer Services are put; the updating of the iwoca Software and Services or the Developer Services and conversion of data, and the data inputted to or through the iwoca Software and Services and the Developer Services by you or on your behalf (collectively the "Transaction Data"). iwoca collects and uses the Transaction Data to support, maintain and improve the iwoca Software and Services and the Developer Services, and to enforce iwoca's rights under this DSLA. To the extent any of the Transaction Data is personal information within the meaning of applicable law, you hereby: (a) consent to iwoca's collection, use and disclosure of such Transaction Data for these purposes; and (b) represent and warrant that you have obtained the consent of any individual to whom such Transaction Data relates to iwoca's collection, use and disclosure of such Transaction Data for these purposes, or that the consent of any such individuals is not required to be obtained under applicable law.

9.3 If you use any part of the Developer Services to access a Customer's data from any iwoca Software and Services, you must only do so with the Customer's explicit consent and only for the limited purposes for which the Customer has given you permission.

## 10. Confidentiality and Publicity

10.1 The Developer Services may contain our Confidential Information. Confidential Information means any information of ours or a third party that you may access and which is either marked as confidential or which ought to be reasonably considered as confidential (including, for example, content, source code, or documentation). If you receive any such Confidential Information, you must not disclose it to any third party other than as expressly permitted by this DSLA or with our prior written consent. You may disclose our Confidential Information where required by law, court order or any governmental or regulatory authority.

## 11. General terms

11.1 This DSLA is personal to you and you may not assign, subcontract, license, charge or otherwise deal with or dispose of (whether in whole or in part) this DSLA without our prior written consent.

11.2 We may propose amendments to update this DSLA at any time. Where we do so, we will notify you of such amendments in writing by sending an email or by other appropriate means using the contact details we hold for you. We will provide you with 30 days' notice of such amendment taking effect and you will be deemed to accept all amendments in the event that you do not notify us of your refusal to such amendments.

11.3 This DSLA constitutes the entire understanding between the parties with respect to their subject matter and supersedes all prior agreements, negotiations and discussions between the parties relating to them. You agree that you have not relied on any representations or statements in entering into this DSLA which are not set out expressly in it, except this does not exclude your or our liability for fraud.

11.4 If a court or similar body decides that any wording in this DSLA cannot be enforced, that decision will not affect the rest of this DSLA, which will remain binding on both parties. However, if the wording that cannot be enforced could be enforced if part of it is deleted, we and you will treat the relevant part of the wording as if it is deleted.

11.5 Each party is an independent contractor and neither party will represent itself (as applicable) as agent, servant, franchisee, joint venturer or legal partner of the other.

11.6 If a party fails to, or delays in, exercising any rights under this DSLA, that will not mean that those rights cannot be exercised in the future.

11.7 Except as expressly set out in this DSLA, a person who is not a party to this DSLA will have no rights to enforce any terms of this DSLA.

11.8 This DSLA is drafted in the English language. If this DSLA is translated into any other language, the English language text will prevail. Any notice given under or in connection with this DSLA will be in the English language. All other documents provided under or in connection with this DSLA will be in the English language. If such document is translated into any other language, the English language text will prevail.

11.9 This DSLA and any dispute or claim arising out of or in connection with it or their subject matter or formation (including non-contractual disputes or claims) will be governed by and construed in accordance with the laws of England and Wales. Each of you and us irrevocably agrees to submit to the exclusive jurisdiction of the courts of England and Wales over any claim or matter arising out of or in connection with this DSLA or the legal relationships established by it.

11.10 Unauthorized use of the iwoca Software and Services or Developer Services or Confidential Information will diminish the value thereof to us and could cause irreparable harm and significant injury to us that could be difficult to fully ascertain. Therefore, if you breach any obligations set forth herein, we shall be entitled to equitable relief to protect our interests in the iwoca Software and Services, Developer Services or Confidential Information, including but not limited to immediate injunctive relief, as well as any other remedies available to us in equity or at law.

---

<!-- llms-section: guides/general/faqs -->
### FAQs
_Frequently asked questions about the iwoca Lending API_

<AccordionGroup>
  <Accordion title="How can I change my application?">
    You can update a customer's application if anything changes (for example, they want to request a different amount).

    Use the `PATCH /applications/` endpoint – send the information that has changed in the request body, and the `customer_id` in the request URL.

    <Info>
    You need to regenerate offers if information about the customer or their application has changed.
    </Info>
  </Accordion>

  <Accordion title="What does it mean for an application to be open or closed?">
    An open application usually means a decision hasn't been made yet, or more information is needed.

    A closed application is one where:

    - A decision has been made and an offer has been returned.
    - A decision has been made and the customer has been declined.
    - The application has timed out or been deferred after no action was taken.

    <Info>
    The status returned with offers tells you what is happening with your customer's application.
    </Info>
  </Accordion>

  <Accordion title="How can I reapply?">
    A customer can always reapply – just send through a new application with what they're looking for.
  </Accordion>

  <Accordion title="Do I need to keep track of the customer_id?">
    Yes.
    The `customer_id` is a unique identifier for each customer in iwoca's systems.
    You need it for all future actions related to that customer.

    If you create a duplicate customer, it creates an internal block that stops iwoca from returning a decision until someone resolves the block.
    Always store and reuse the `customer_id` to avoid this.
  </Accordion>

  <Accordion title="How does /offers/ decide what to show?">
    The `/offers/` endpoint takes into account information about your customer, what they requested in their application, and what iwoca might be able to lend them.

    You'll receive confirmed or indicative offers if iwoca thinks it can lend to your customer.
    If a decision can't be made yet, you'll get a status instead.

    If the customer can't be lent to, you'll receive a `decline` status.
  </Accordion>

  <Accordion title="What happens if the customer is declined?">
    You'll receive a `decline` status and the application will be closed.
    See the [Offers](/api-reference/offers/overview) API reference for more detail.
  </Accordion>
</AccordionGroup>

---

<!-- llms-section: guides/general/ui-implementation-guidance -->
### UX guidance
_Screen-by-screen guidance for building your customer-facing lending journey_

How to present iwoca's lending flow in your UI.
This guide covers what to show, what to hide, and what each user action should trigger.

---

## Customer form

<Tabs>
  <Tab title="Mobile">
    <div className="rounded-xl overflow-hidden dark:bg-gray-200 dark:p-2">
      ![Create a customer mobile](/images/create-a-customer-mobile.png)
    </div>
  </Tab>
  <Tab title="Desktop">
    <div className="rounded-xl overflow-hidden dark:bg-gray-200 dark:p-2">
      ![Create a customer desktop](/images/create-a-customer-desktop.png)
    </div>
  </Tab>
</Tabs>

### Key decisions

<AccordionGroup>
  <Accordion title="Company search">
    Implement a free text field that searches company name or number via the Companies House API.
    Return results in a dropdown for the customer to select.
    This autofills `company_number`, `registered_company_name`, and `type`.
  </Accordion>
  <Accordion title="Director selection">
    Rather than free-text name entry, present a dropdown of directors from Companies House.
    iwoca only accepts directors as applicants – this pre-filters ineligible users and reduces errors.
  </Accordion>
  <Accordion title="Address lookup">
    Use a postcode lookup (Equifax API recommended).
    This returns an Equifax token (`equifax_token`) that significantly improves automated decision rates – pass it through in the request.
  </Accordion>
  <Accordion title="Privacy policy copy">
    Your privacy policy must cover:
    - Data sharing with iwoca.
    - Soft credit checks will be performed.
    - Data shared with fraud prevention agencies.

    The consent checkbox and notification must be obvious – don't bury them in terms.
  </Accordion>
  <Accordion title="After submission">
    - **API Lite** – Redirect the customer to iwoca via `GET /login_link/`.
    - **API Plus** (decision-relayed) – Call `GET /offers/` to retrieve offers or a decline.
  </Accordion>
</AccordionGroup>

---

## Application form

<div className="rounded-xl overflow-hidden dark:bg-gray-200 dark:p-2">
  ![Create an application](/images/create-an-application.png)
</div>

### Key decisions

<AccordionGroup>
  <Accordion title="Amount validation">
    Validate the requested amount is between £1,000 and £1,000,000 on the front end.
  </Accordion>
  <Accordion title="Duration and purpose">
    Both are optional but improve the customer experience.
    Collect duration in months.
    Purpose of funds should be a dropdown with the [allowed purpose values](/api-reference/application/overview).
  </Accordion>
</AccordionGroup>

---

## Offers screen

<Tabs>
  <Tab title="Mobile">
    <div className="rounded-xl overflow-hidden dark:bg-gray-200 dark:p-2">
      ![Display offers mobile](/images/display-offers-mobile-v4.png)
    </div>
  </Tab>
  <Tab title="Desktop">
    <div className="rounded-xl overflow-hidden dark:bg-gray-200 dark:p-2">
      ![Display offers desktop](/images/display-offers-desktop-v3.png)
    </div>
  </Tab>
</Tabs>

### What to show vs hide

| Show | Hide |
|---|---|
| Offer amount | `probability_of_offer` |
| Duration | `offer_type` label (treat all the same visually) |
| Monthly interest rate | Other internal fields |
| Transaction fee | |
| Total repayable (confirmed only) | |
| Monthly repayment (confirmed only) | |

<Info>
`normal_repayment_amount` and `total_repayable` are only available when `offer_type` is `confirmed`.
For sample and indicative offers, don't show repayment amounts.
</Info>

### Offer hierarchy

<div className="rounded-xl overflow-hidden dark:bg-gray-200 dark:p-2">
  ![Offer hierarchy](/images/offer-hierarchy.png)
</div>

Each offer type supersedes the previous as more data becomes available.
Your UI should always show the latest offers – earlier ones become irrelevant.

### Button behaviour

<AccordionGroup>
  <Accordion title="'Continue to upload docs' - sample/indicative offer">
    Either:
    - Direct the customer to iwoca via `GET /customers/{customer_id}/login_link/?offer_id={offer_id}` to upload documents.
    - Or show a page displaying document requirements from the `GET /offers/` response.
  </Accordion>
  <Accordion title="'Proceed with this offer' - confirmed offer">
    Either:
    - Direct the customer to iwoca via `GET /customers/{customer_id}/login_link/?offer_id={offer_id}` to draw down.
    - Or show a separate approval/confirmation page before sending them to the login link.
  </Accordion>
  <Accordion title="'Proceed with offer' - sample offer, no documents needed">
    Direct the customer to iwoca via `GET /customers/{customer_id}/login_link/?offer_id={offer_id}`.
  </Accordion>
</AccordionGroup>

---

## Decision outcomes

After a customer submits their application, three outcomes are possible.
Your UI should handle each clearly.

<CardGroup cols={3}>
  <Card title="Approved" icon="check">
    Offers are ready.
    Direct the customer to your offers screen or to iwoca via login link to review and draw down.
  </Card>
  <Card title="Reviewing" icon="clock">
    iwoca is assessing the application.
    Show a confirmation message and set expectations on timing.
    The customer can check back via iwoca's platform.
  </Card>
  <Card title="Declined" icon="xmark">
    iwoca did not approve the application.
    Show a clear message with iwoca's contact details.
    Do not reveal internal decline reasons.
  </Card>
</CardGroup>

<Warning>
If iwoca declines the customer, do not show reasons from the API.
Display a generic message and direct them to iwoca's support if they have questions.
</Warning>

---

<!-- llms-section: guides/getting-started/ai-integration -->
### Build with AI
_Use AI coding tools to build your iwoca integration faster_

Use AI coding assistants like Claude, Cursor, or ChatGPT to build your iwoca integration faster.
Our docs are optimised for AI consumption – your AI tool can read our full documentation and generate working integration code.

## Connect your AI tool

<CardGroup cols={3}>
  <Card title="Full docs as one file" icon="file-lines">
    For Claude, ChatGPT, Cursor, or any AI tool.

    <Prompt description="Paste into your AI tool" actions={["copy"]}>
Read the iwoca Lending API docs at https://lending-api-docs.iwoca.co.uk/llms-full.txt and help me build my integration.
    </Prompt>
  </Card>
  <Card title="OpenAPI schema" icon="code" href="/api-reference/openapi/overview">
    Machine-readable OpenAPI 3.1, including every webhook payload schema.
    Download it from `/openapi.json`.
  </Card>
  <Card title="Any page as Markdown" icon="link">
    Append `.md` to any page URL to get its raw Markdown.

    <Prompt description="Example" actions={["copy"]}>
https://lending-api-docs.iwoca.co.uk/guides/webhooks/overview.md
    </Prompt>
  </Card>
</CardGroup>

---

## Example prompts

<Tabs>
  <Tab title="No Code">
    <Prompt description="Add an iwoca lending link to my [checkout page / partner dashboard / customer portal]. The link is: [LENDING_LINK_URL]. Place it [in the sidebar / after order confirmation / in the finance section]." actions={["copy", "cursor"]}>
Add an iwoca lending link to my [checkout page / partner dashboard / customer portal]. The link is: [LENDING_LINK_URL]. Place it [in the sidebar / after order confirmation / in the finance section].
    </Prompt>
  </Tab>
  <Tab title="API Lite">
    <Prompt description="I'm building an API Lite integration with iwoca's lending API. Help me create a customer, submit a loan application, and retrieve a login link so the customer can complete their journey on iwoca's platform. Use the iwoca lending docs for reference." actions={["copy", "cursor"]}>
I'm building an API Lite integration with iwoca's lending API. Help me create a customer, submit a loan application, and retrieve a login link so the customer can complete their journey on iwoca's platform. Use the iwoca lending docs for reference.
    </Prompt>
  </Tab>
  <Tab title="API Plus">
    <Prompt description="I'm building an API Plus integration with iwoca's lending API. Help me create a customer, submit an application, retrieve and display offers, and select an offer. I want to use webhooks for status updates. Use the iwoca lending docs for reference." actions={["copy", "cursor"]}>
I'm building an API Plus integration with iwoca's lending API. Help me create a customer, submit an application, retrieve and display offers, and select an offer. I want to use webhooks for status updates. Use the iwoca lending docs for reference.
    </Prompt>
  </Tab>
</Tabs>

---

## What the AI can help with

With access to our docs, your AI assistant can:

- **Generate integration code** – Working API calls with correct authentication, headers, and payloads.
- **Explain the lending flow** – Walk through the full journey from customer creation to drawdown.
- **Handle edge cases** – Webhook setup, error handling, retry logic.
- **Write tests** – Generate test scenarios using our sandbox environment.
- **Debug issues** – Interpret API error responses and suggest fixes.

---

## Tips for better results

- **Be specific about your stack** – Tell the AI what language and framework you're using.
- **Mention your integration type** – API Plus, API Lite, or No Code.
- **Ask about webhooks early** – They're key to a production-ready integration.
- **Reference the sandbox** – Ask the AI to use sandbox credentials for testing.

---

## Next steps

<CardGroup cols={3}>
  <Card title="Integration options" icon="plug" href="/guides/integration-options/overview">
    Choose your integration approach
  </Card>
  <Card title="Webhooks" icon="bell" href="/guides/webhooks/overview">
    Set up real-time status notifications
  </Card>
  <Card title="Testing & go-live" icon="flask" href="/guides/testing/overview">
    Test your integration before going live
  </Card>
</CardGroup>

---

<!-- llms-section: guides/getting-started/authentication -->
### Access the API
_How to authenticate with the iwoca Lending API_

Get access to the iwoca Lending API sandbox environment and start building your integration.

## Getting your API token

<Steps>
  <Step title="Join the Developer Portal">
    After discussing your integration plans with iwoca, you'll be invited to our [Partner Developer Portal](https://stage.iwoca-dev.co.uk/login/), where you can retrieve your sandbox API token.
  </Step>
  <Step title="Connect to the sandbox">
    The sandbox base URL is:

    ```text
    https://stage.iwoca-dev.co.uk
    ```
  </Step>
  <Step title="Verify your connection">
    Use the `/authentication_check/` endpoint to confirm your token is working.
    A successful request returns `200 OK` with the API version.
  </Step>
</Steps>

## Authentication

Make every request over HTTPS and authenticate with a Bearer token in the `Authorization` header:

```http
Authorization: Bearer {your_api_token}
```

## Required headers

| Header | Value | When |
|---|---|---|
| `Accept` | `application/json` | Every request |
| `Content-Type` | `application/json` | POST requests |
| `Authorization` | `Bearer {token}` | Every request |

<Warning>
Requests must come directly from your back end – never expose your API token in client-side code.
</Warning>

---

## Next steps

<CardGroup cols={3}>
  <Card title="Integration options" icon="plug" href="/guides/integration-options/overview">
    Choose your integration approach
  </Card>
  <Card title="API reference" icon="code" href="/api-reference/overview">
    Explore the full endpoint documentation
  </Card>
  <Card title="Build with AI" icon="microchip-ai" href="/guides/getting-started/ai-integration">
    Point your AI coding tool at our docs
  </Card>
</CardGroup>

---

<!-- llms-section: guides/getting-started/flexi-loan -->
### Our product: Flexi-Loan
_Understanding iwoca's flagship flexible credit facility for small businesses_

The iwoca Flexi-Loan is our flagship product – an unsecured, flexible credit facility from £1,000 to £1 million.
Customers are approved for a credit limit and draw down funds whenever they need them.
They only pay interest on what they use and can repay early without penalty.

## Key benefits

<CardGroup cols={2}>
  <Card title="Fast decisions" icon="clock">
    Automated decisions are typically returned in under 40 seconds.
    More complex cases are typically reviewed within 24 hours.
  </Card>
  <Card title="Access funds when they need it" icon="arrows-rotate">
    Customers can draw down funds as they need them, up to their approved limit.
    They don't need to take the full amount at once.
  </Card>
  <Card title="Pay only for what they use" icon="piggy-bank">
    Customers only pay interest on the funds they've drawn, not on their full credit limit.
    They pay interest only for the time they hold the funds, as interest accrues daily.
  </Card>
  <Card title="No penalties for early repayment" icon="check">
    Customers can repay ahead of schedule without extra fees.
  </Card>
  <Card title="Top up as they repay" icon="arrow-up">
    Once customers have repaid enough of their balance, they can apply for a top-up to increase their available credit.
  </Card>
  <Card title="Flexible repayment terms" icon="calendar">
    Each drawdown is repaid in monthly instalments over various terms from 12 to 60 months.
  </Card>
</CardGroup>

## Who's eligible

<AccordionGroup>
  <Accordion title="Business structure and applicant">
    We lend to UK-based limited companies and limited liability partnerships (LLPs).
    We don't lend to sole traders.
    Applicants must be a director of the business, based in the UK, and at least 18 years old.
  </Accordion>
</AccordionGroup>

---

## How it works

```mermaid
graph LR
    A[Application] --> B[Assessment]
    B --> C[Offer]
    C --> D[Verification]
    D --> E[Funding]
```

- **Application** – Customers give basic business information – as little as 10 seconds with integrated partners.
- **Assessment** – Automated decisions in under 40 seconds; complex cases typically reviewed within 24 hours.
- **Offer** – Customers receive their approved credit limit and terms.
- **Verification** – Identity, bank account, and loan agreement confirmed digitally.
- **Funding** – Funds transferred to the business account, typically within 24 hours.

---

## Next steps

<CardGroup cols={2}>
  <Card title="Integration options" icon="plug" href="/guides/integration-options/overview">
    Explore how to offer Flexi-Loans to your customers
  </Card>
  <Card title="Access the API" icon="key" href="/guides/getting-started/authentication">
    Get your API key and connect to the sandbox
  </Card>
</CardGroup>

---

<!-- llms-section: guides/getting-started/introduction-to-iwoca -->
### Introduction to iwoca
_Learn about iwoca's embedded lending platform for partners_

<div className="rounded-2xl overflow-hidden dark:bg-[#EEF4F7] dark:p-4">
  <img
    src="/images/embedded-lending-hero.png"
    alt="iwoca embedded lending"
    className="block"
  />
</div>

Since 2012, iwoca has helped over 150,000 UK businesses access fast, flexible funding.
We use technology and data to make smarter lending decisions – and we've built an embedded platform so partners can offer that same funding to their customers.

## Who we are

iwoca is a fintech lender built for small businesses.
We make faster lending decisions than traditional banks, with the personal service you'd expect from a specialist.
We support small businesses across the UK and Germany.

## What we do

We provide straightforward access to finance where and when a business needs it.

<ul className="icon-list">
  <li><Icon icon="clock" /> <strong>Quick decisions</strong>: most answers in under a minute.</li>
  <li><Icon icon="arrows-rotate" /> <strong>Flexible repayment</strong>: customers only pay interest on what they use, and can repay early without penalties.</li>
  <li><Icon icon="file-lines" /> <strong>Straightforward process</strong>: apply online without mountains of paperwork.</li>
  <li><Icon icon="user" /> <strong>Personal support</strong>: dedicated account managers who understand each business.</li>
  <li><Icon icon="puzzle-piece" /> <strong>Embedded lending</strong>: integration options to help partners offer our finance to their customers.</li>
</ul>

## Our embedded lending platform

Embedded lending means integrating finance directly into the platforms businesses already use – whether that's a bank account, accounting software, payment provider, or industry platform.
We've built a suite of integration options so you can offer iwoca funding to your customers, whether you have developer resource available or need a no-code approach.

## Why choose iwoca

<CardGroup cols={2}>
  <Card title="Grow a new revenue stream" icon="chart-line-up">
    Earn commission when one of your customers borrows from us.
  </Card>

  <Card title="All the support you need" icon="headset">
    Technical support from our Integration and Product Managers, plus a dedicated Partnership Manager.
  </Card>

  <Card title="Easy integration to launch quickly" icon="bolt">
    Go live in days with our no-code lending link or integrate in weeks with our embedded API.
  </Card>

  <Card title="We're an experienced partner" icon="handshake">
    We work with more than 50 partners across many industries.
  </Card>

  <Card title="Your customers will love us" icon="star">
    Rated 4.8 on Trustpilot from over 10,000 businesses.
    Every customer gets a dedicated account manager.
  </Card>
</CardGroup>

## Interested in partnering with us?

Contact our partnerships team at [partners@iwoca.co.uk](mailto:partners@iwoca.co.uk).

---

## Next steps

<CardGroup cols={2}>
  <Card title="Flexi-Loan" icon="coins" href="/guides/getting-started/flexi-loan">
    Learn about our flagship flexible credit facility
  </Card>

  <Card title="Integration options" icon="plug" href="/guides/integration-options/overview">
    Choose how to connect your platform to iwoca
  </Card>
</CardGroup>

---

<!-- llms-section: guides/integration-options/enhanced-integration -->
### API Plus
_Build a fully customised lending experience where customers see offers from within your platform_

Build a fully customised lending experience where customers see iwoca's offers in your platform.
API Plus gives you maximum control over the customer journey, up to the point they select an offer.
It often delivers higher conversion than our other integration options.

## Prerequisites

Before you begin, make sure you have:

- Access to our Partner Developer Portal, where you can get your API token for the sandbox environment.

<Info>
**Don't have access?** Chat with your Partnership Manager to gain access to the Partner Developer Portal.
</Info>


<Accordion title="Meet our compliance requirements" icon="shield" variant="important">
  Before sharing the customer's information with iwoca, you must include a clear privacy notice.
  Your privacy notice must disclose the following:

  1. **Data sharing with iwoca** – Customer data will be shared with iwoca to process their application.
  2. **Soft credit checks** – Credit reference agencies will run soft credit and identity checks (which will not affect the customer's credit score).
  3. **Fraud prevention agencies** – Data will be shared with fraud prevention agencies, and if fraud is detected, the customer or others could be refused services, finance, or employment.
  4. **iwoca's privacy policy** – Include an easily accessible link to iwoca's privacy policy.
     You can also include this within your own privacy policy.

  <Warning>
  This notice must be clearly visible to the customer before you submit their data to iwoca.
  It cannot be buried in general terms and conditions. iwoca will verify this is in place during the go-live review.
  </Warning>

  **Example wording:**

  Use the version that matches who you share customer data with.

  **Sharing with iwoca only**

  <Info>
  'We plan to show you credit offers from our finance partner iwoca. Tick here to let us know that we have your permission to share relevant data with iwoca. iwoca will share your information with credit reference agencies to run soft credit and identity checks, but don't worry – this will not affect your credit score. They will also share it with fraud prevention agencies – please be aware, if they do spot fraud, you or others could be refused services, finance, or employment. For more information, please see [iwoca's privacy policy](https://www.iwoca.co.uk/privacy-policy/).'
  </Info>

  **Sharing with a panel of lenders**

  Use this version if you share data with a wider panel of providers.
  Here, 'our privacy policy' links to your own privacy policy, which must in turn link to [iwoca's privacy policy](https://www.iwoca.co.uk/privacy-policy/).

  <Info>
  'We plan to show you credit offers from carefully selected providers. Tick here to let us know that we have your permission to share relevant data with these providers. These providers will share your information with credit reference agencies to run soft credit and identity checks, but don't worry – this will not affect your credit score. They will also share it with fraud prevention agencies – please be aware, if they do spot fraud, you or others could be refused services, finance, or employment. For more information please see [our privacy policy](#).'
  </Info>
</Accordion>

<Accordion title="Build with AI?" icon="microchip-ai" variant="boxed">
Add our docs to your AI coding tool and let it scaffold the integration for you. The manual steps below remain the source of truth if you'd rather build by hand.

<Steps>
  <Step title="Point your AI tool at our docs">
    This gives your AI assistant the full text of our documentation to work from.

    <Prompt description="Paste into your AI tool" actions={["copy"]}>
Read the iwoca Lending API docs at https://lending-api-docs.iwoca.co.uk/llms-full.txt and help me build my integration.
    </Prompt>
  </Step>
  <Step title="Use this prompt to get started">
    Copy this into Claude, Cursor, or ChatGPT:

    <Prompt description="I'm building an API Plus integration with iwoca's lending API. Help me create a customer, submit an application, retrieve and display offers, and select an offer – all via the API with webhooks for status updates. Use the iwoca lending docs for reference." actions={["copy", "cursor"]}>
I'm building an API Plus integration with iwoca's lending API. Help me create a customer, submit an application, retrieve and display offers, and select an offer – all via the API with webhooks for status updates. Use the iwoca lending docs for reference.
    </Prompt>
  </Step>
</Steps>
</Accordion>

---

## Integration steps

<Tip>
**Building the customer-facing screens?**
See our [UX guidance](/guides/general/ui-implementation-guidance) for screen-by-screen direction on the customer and application forms, what to show and hide on the offers screen, offer hierarchy, button behaviour per offer type, and decision outcomes.
</Tip>

API Plus builds on API Lite with one extra step: **Get offers**, so you can show customers their iwoca loan offers within your app or platform.

```mermaid
graph LR
    A[Create customer] --> B[Submit application]
    B --> C[Get offers]
    C --> D[Redirect to iwoca]
```

<Steps>
  <Step title="Create a customer">
    Send your customer's contact information to iwoca.

    ```http
    POST /customers/
    ```

    **You'll need:**

    - Company details (for example, registration number, name, turnover in last 12 months, VAT status)
    - Applicant details (name, email, phone, address, date of birth)

    **Response:** You'll receive a `customer_id` to use in subsequent requests.
    Store it — you'll need it later.

    See the [Customer overview](/api-reference/customer/overview) for full field requirements.
  </Step>
  <Step title="Submit an application">
    Send your customer's product request information.

    ```http
    POST /customers/{customer_id}/applications/
    ```

    **You'll need:**

    - Loan amount (£1,000–£1,000,000)
    - Loan duration (optional)
    - Purpose of funds (optional)

    **Response:** You'll receive an `application_id` and the application status.
    Store it — you'll need it later.

    This creates the application, which allows iwoca to start the credit decision.
    One of our Account Managers will reach out to you or your customer (according to your contact strategy — the agreed plan for who iwoca contacts and how).

    See the [Application overview](/api-reference/application/overview) for details.
  </Step>
  <Step title="Get offers">
    Retrieve loan offers to display within your platform.

    ```http
    GET /applications/{application_id}/offers/
    ```

    **Response:** You'll receive available loan offers with details including:

    - Loan amounts and terms.
    - Interest rates and fees (if any).
    - Any further requirements we need the customer to complete.

    Offers can be retrieved at any time and will contain information about any outstanding documentation or next steps.

    See the [Offers overview](/api-reference/offers/overview) for details.
  </Step>
  <Step title="Redirect the customer">
    When your customer chooses an offer, get a login link and redirect them to iwoca, passing the offer they chose.

    ```http
    GET /customers/{customer_id}/login_link/?offer_id={offer_id}
    ```

    **Response:** You'll receive a single-use login link.
    Redirect your customer there to continue with the drawdown steps, or to upload additional information if needed.

    See the [Login link overview](/api-reference/login-link/overview) for details.
  </Step>
</Steps>

---

## Next steps

<CardGroup cols={2}>
  <Card title="UX guidance" icon="map" href="/guides/general/ui-implementation-guidance">
    Screen-by-screen direction for your lending journey
  </Card>
  <Card title="Additional features" icon="puzzle-piece" href="/guides/additional-concepts/sharing-documents">
    Discover endpoints for a better customer experience
  </Card>
  <Card title="Webhooks" icon="bell" href="/guides/webhooks/overview">
    Real-time notifications on application status changes
  </Card>
  <Card title="Testing & go-live" icon="flask" href="/guides/testing/overview">
    Test your integration before going live
  </Card>
</CardGroup>

---

<!-- llms-section: guides/integration-options/no-code-lending-link -->
### No-code link
_Offer your customers iwoca lending in minutes – just share a link_

Help your customers access iwoca lending with zero development required.

## How to get started

<Steps>
  <Step title="Send your brand assets">
    Send the following to your Partnership Manager:

    - **Company logo** – SVG format with transparent background
    - **Primary brand colour** – Hex code (for example, `#1C5296`)
    - **Secondary brand colour** – Hex code (for example, `#FB534A`)

    Your customers will see a co-branded experience using these details.
  </Step>
  <Step title="Receive your referral link">
    You'll receive a referral link hosted on iwoca's platform.
    Share this link anywhere your customers might need finance:

    - On your website or customer portal
    - In email communications
    - Within your platform or app
    - In marketing materials
  </Step>
  <Step title="Pre-fill company information (recommended)">
    To make the journey even easier for your customers, add their company registration number to your referral link as a `company_number` query parameter.
    This pre-fills the application, reducing friction.

    For example, if your referral link is `www.iwoca.co.uk/partner-signup/iwoca/new` and the customer's registration number is `12345678`:

    ```text
    www.iwoca.co.uk/partner-signup/iwoca/new?company_number=12345678
    ```
  </Step>
</Steps>

---

**Have questions?** Contact your Partnership Manager or email [partners@iwoca.co.uk](mailto:partners@iwoca.co.uk).

---

<!-- llms-section: guides/integration-options/overview -->
### Overview
_Choose how to integrate iwoca's business lending into your platform_

Choose how you want to integrate iwoca's business lending into your platform.
We offer three options, each designed for different business needs.

## Our integration types

<CardGroup cols={1}>
  <Card title="No-code lending link" icon="wand-magic-sparkles" href="/guides/integration-options/no-code-lending-link">
    **Go live in one day – no development required.** Share a co-branded link anywhere your customers need finance.
  </Card>
  <Card title="API Lite" icon="code" href="/guides/integration-options/referral-api-integration">
    **Go live in a few days with three straightforward API calls.** Collect customer information in your platform and refer them to iwoca.
  </Card>
  <Card title="API Plus" icon="rocket" href="/guides/integration-options/enhanced-integration">
    **Build a fully customisable lending experience.** Surface iwoca's offers directly in your platform for maximum conversion.
  </Card>
</CardGroup>

---

## Common enhancements

API Lite and API Plus can be enhanced with:

<CardGroup cols={3}>
  <Card title="Sharing documents" icon="file-arrow-up" href="/guides/additional-concepts/sharing-documents">
    Send bank statements and documents for faster decisions
  </Card>
  <Card title="Prequalification" icon="chart-line-up" href="/guides/additional-concepts/prequalification">
    Prequalify customers to encourage applications
  </Card>
  <Card title="Webhooks" icon="bell" href="/guides/webhooks/overview">
    Get notified when application status changes
  </Card>
</CardGroup>

## Need help choosing?

Contact our partnerships team at [partners@iwoca.co.uk](mailto:partners@iwoca.co.uk) to discuss which integration fits your needs.

---

<!-- llms-section: guides/integration-options/referral-api-integration -->
### API Lite
_Collect customer information in your platform and refer them to iwoca_

Integrate iwoca's lending by collecting customer information in your platform, then referring the customer to iwoca to view their decision and complete the final steps.
API Lite strikes a good balance between impact and effort – you reduce customer friction without building complex UI.

## Prerequisites

Before you begin, make sure you have:

- Access to our Partner Developer Portal, where you can get your API token for the sandbox environment.

<Info>
**Don't have access?** Chat with your Partnership Manager to gain access to the Partner Developer Portal.
</Info>


<Accordion title="Meet our compliance requirements" icon="shield" variant="important">
  Before sharing the customer's information with iwoca, you must include a clear privacy notice.
  Your privacy notice must disclose the following:

  1. **Data sharing with iwoca** – Customer data will be shared with iwoca to process their application.
  2. **Soft credit checks** – Credit reference agencies will run soft credit and identity checks (which will not affect the customer's credit score).
  3. **Fraud prevention agencies** – Data will be shared with fraud prevention agencies, and if fraud is detected, the customer or others could be refused services, finance, or employment.
  4. **iwoca's privacy policy** – Include an easily accessible link to iwoca's privacy policy.
     You can also include this within your own privacy policy.

  <Warning>
  This notice must be clearly visible to the customer before you submit their data to iwoca.
  It cannot be buried in general terms and conditions. iwoca will verify this is in place during the go-live review.
  </Warning>

  **Example wording:**

  Use the version that matches who you share customer data with.

  **Sharing with iwoca only**

  <Info>
  'We plan to show you credit offers from our finance partner iwoca. Tick here to let us know that we have your permission to share relevant data with iwoca. iwoca will share your information with credit reference agencies to run soft credit and identity checks, but don't worry – this will not affect your credit score. They will also share it with fraud prevention agencies – please be aware, if they do spot fraud, you or others could be refused services, finance, or employment. For more information, please see [iwoca's privacy policy](https://www.iwoca.co.uk/privacy-policy/).'
  </Info>

  **Sharing with a panel of lenders**

  Use this version if you share data with a wider panel of providers.
  Here, 'our privacy policy' links to your own privacy policy, which must in turn link to [iwoca's privacy policy](https://www.iwoca.co.uk/privacy-policy/).

  <Info>
  'We plan to show you credit offers from carefully selected providers. Tick here to let us know that we have your permission to share relevant data with these providers. These providers will share your information with credit reference agencies to run soft credit and identity checks, but don't worry – this will not affect your credit score. They will also share it with fraud prevention agencies – please be aware, if they do spot fraud, you or others could be refused services, finance, or employment. For more information please see [our privacy policy](#).'
  </Info>
</Accordion>

---

<Accordion title="Build with AI?" icon="microchip-ai" variant="boxed">
Add our docs to your AI coding tool and let it scaffold the integration for you. The manual steps below remain the source of truth if you'd rather build by hand.

<Steps>
  <Step title="Point your AI tool at our docs">
    This gives your AI assistant the full text of our documentation to work from.

    <Prompt description="Paste into your AI tool" actions={["copy"]}>
Read the iwoca Lending API docs at https://lending-api-docs.iwoca.co.uk/llms-full.txt and help me build my integration.
    </Prompt>
  </Step>
  <Step title="Use this prompt to get started">
    Copy this into Claude, Cursor, or ChatGPT:

    <Prompt description="I'm building an API Lite integration with iwoca's lending API. Help me create a customer, submit a loan application, and retrieve a login link so the customer can complete their journey on iwoca's platform. Use the iwoca lending docs for reference." actions={["copy", "cursor"]}>
I'm building an API Lite integration with iwoca's lending API. Help me create a customer, submit a loan application, and retrieve a login link so the customer can complete their journey on iwoca's platform. Use the iwoca lending docs for reference.
    </Prompt>
  </Step>
</Steps>
</Accordion>

---

## Integration steps

<Tip>
**Building the customer-facing screens?**
See our [UX guidance](/guides/general/ui-implementation-guidance) for the customer and application forms – company search, director selection, address lookup, amount validation, and the privacy notice.
</Tip>

<Steps>
  <Step title="Create a customer">
    Send your customer's contact information to iwoca.

    ```http
    POST /customers/
    ```

    **You'll need:**

    - Company details (for example, registration number, name, turnover in last 12 months, VAT status)
    - Applicant details (name, email, phone, address, date of birth)

    **Response:** You'll receive a `customer_id` to use in subsequent requests.
    Store it — you'll need it later.

    See the [Customer overview](/api-reference/customer/overview) for full field requirements.
  </Step>
  <Step title="Submit an application">
    Send your customer's product request information.

    ```http
    POST /customers/{customer_id}/applications/
    ```

    **You'll need:**

    - Loan amount (£1,000–£1,000,000)
    - Loan duration (optional)
    - Purpose of funds (optional)

    **Response:** You'll receive an `application_id` and the application status.
    Store it — you'll need it later.

    This creates the application, which allows iwoca to start the credit decision.
    One of our Account Managers will reach out to you or your customer (according to your contact strategy — the agreed plan for who iwoca contacts and how).

    See the [Application overview](/api-reference/application/overview) for details.
  </Step>
  <Step title="Retrieve a login link">
    Generate a secure link that allows the customer to view their application or offer on iwoca's website directly, with a single click.

    ```http
    GET /customers/{customer_id}/login_link/
    ```

    **Response:** You'll receive a single-use URL.

    This redirects your customer to iwoca's platform.
    Depending on their assessment, they'll either upload additional documents or accept an offer and draw down the funds.

    See the [Login link overview](/api-reference/login-link/overview) for details.
  </Step>
</Steps>

---

## Next steps

<CardGroup cols={2}>
  <Card title="API Plus" icon="arrow-up-right-dots" href="/guides/integration-options/enhanced-integration">
    Surface offers directly in your platform
  </Card>
  <Card title="Additional features" icon="puzzle-piece" href="/guides/additional-concepts/sharing-documents">
    Discover endpoints for a better customer experience
  </Card>
  <Card title="Webhooks" icon="bell" href="/guides/webhooks/overview">
    Real-time notifications on application status changes
  </Card>
  <Card title="Testing & go-live" icon="flask" href="/guides/testing/overview">
    Test your integration before going live
  </Card>
</CardGroup>

---

<!-- llms-section: guides/testing/decision-relayed-testing -->
### API Plus testing
_Test scenarios and data for the API Plus integration_

Use this guide to test your API Plus (decision relayed) integration in the sandbox environment.
API Plus requires additional testing beyond API Lite because your platform displays offers directly to the customer.

## What you need to test

Your integration must show all of the following:

- A new customer and application using the minimum data requirements.
- A customer with a **confirmed offer** displayed correctly.
- A customer **decline** handled correctly.
- A customer **deferral** (your iwoca Partnership Manager will assist).
- Each **offer type** (confirmed, indicative, and sample) handled correctly.
- Offer selection redirecting the customer via `GET /customers/{customer_id}/login_link/?offer_id={offer_id}`.

## Test data

Use the same base test data as the referral integration.
See [Referral integration testing](/guides/testing/referral-integration-testing#test-data) for the full customer and application payloads.

<Info>
Replace `{{currentDate}}` in `valid_from` with today's date in ISO 8601 format.
</Info>

## Simulating different outcomes

| Scenario | How to trigger |
|---|---|
| **Confirmed offer** — firm, ready-to-draw-down terms | Set `amount` to 15,000 or less (default test data) |
| **Indicative offer** — an estimate that needs more information before it's confirmed | Set `amount` to greater than 15,000, up to 75,000 |
| **Indicative offer (large)** — an indicative offer for amounts above £75,000 | Set `amount` to greater than 75,000 |
| **Sample offer** | Leave out a required field, or send an invalid one such as a wrong `trading_from_date`. With too little data to assess, iwoca returns a sample estimate. |
| **Decline** | Use decline test data (see below) |
| **Deferral** | Contact your iwoca Partnership Manager |

### Decline test data

Change the following fields in the customer payload:

```json
{
    "first_name": "James",
    "last_name": "Smythe",
    "date_of_birth": "1985-01-01",
    "company_number": "01111113",
    "house_number": "123",
    "street_line_1": "Decline St",
    "town": "Decline",
    "postcode": "DE61NA"
}
```

This returns an empty `offers` array with `offer_creation_status: "decline"`.

## Validation checklist

Before submitting for review, verify:

- [ ] Customer data formatted correctly with minimum required fields.
- [ ] Application created successfully with valid amount.
- [ ] `GET /offers/` returns and displays confirmed offers correctly.
- [ ] `GET /offers/` returns and displays indicative/sample offers correctly.
- [ ] Decline scenario handled gracefully in your UI.
- [ ] Offer selection redirects the customer via the login link, carrying `offer_id`.
- [ ] Application statuses displayed correctly at each stage.
- [ ] Webhook responses received as expected (if applicable).
- [ ] Multiple webhook responses handled correctly (if applicable).

## What else is required

During testing, iwoca will also ask to see:

- Screenshots of all UI screens including data collection forms.
- A video or live demo showing the full journey within your platform.
- Evidence of both happy and unhappy paths and compliant offer display.

---

## Next steps

<CardGroup cols={2}>
  <Card title="Go live" icon="rocket" href="/guides/testing/go-live">
    Submit your integration for review and launch to production
  </Card>
</CardGroup>

---

<!-- llms-section: guides/testing/go-live -->
### Go live
_Submit your integration for review and launch to production_

After testing in the sandbox, submit your integration for iwoca's review before accessing the production environment.

## Submit for review

Before you get production access, iwoca checks that your customer journey meets lending obligations.
This also catches pre-launch bugs.

<Steps>
  <Step title="Complete sandbox testing">
    Ensure you've run through all required test scenarios for your integration type.
    Submit test customers via the sandbox environment.
  </Step>
  <Step title="Prepare your demo">
    iwoca needs to see the full working customer journey, including:

    - Happy path (successful application and offer).
    - Common unhappy paths (decline, missing documents).
    - Privacy notice visibility meets our compliance requirements.
    - Correct offer display (if applicable).

    This can be a recorded walkthrough, access to your sandbox flow, or a live call to walk through the journey.
  </Step>
  <Step title="Submit UI evidence">
    Share screenshots or a demo link showing:

    - All forms used to collect customer data.
    - How the integration looks within your platform.
    - How different offer types are displayed (if applicable).
  </Step>
  <Step title="Verify backend integration">
    iwoca will verify that leads are sent correctly to our back-end:

    - All minimum data requirements are met.
    - Data is in the correct format.
    - Company and applicant address fields are validated at the point of entry.
    - Duplicate customers are handled appropriately.

    This can be demonstrated with a recorded walkthrough of the journey – your iwoca Partnership Manager will check the corresponding customer and application in our system.
  </Step>
  <Step title="Receive production API token">
    Once approved, iwoca sends you your production API token via secure Gmail or PGP encryption – the same method used for your sandbox token.
  </Step>
</Steps>

<Warning>
**Data validation is required.** Before going live, company fields and applicants' home addresses must be validated at the point of capture.
We recommend a Companies House integration for company data and an address lookup for residential addresses – see [UX guidance](/guides/general/ui-implementation-guidance).
If you already validate these fields another way, no further action is needed.
</Warning>

## Tips for a successful launch

<CardGroup cols={2}>
  <Card title="Notify iwoca of your launch date" icon="calendar">
    We'll have our teams ready for your first applications and be on hand for any launch issues.
  </Card>
  <Card title="Soft launch first" icon="seedling">
    Limit your initial launch to a small subset of customers.
    This lets both teams verify everything works before full volume, and gives our customer success team a chance to familiarise themselves with your customers.
  </Card>
</CardGroup>

<Info>
iwoca closely monitors new integrations for the first few days and will notify you of any concerns.
Get in touch at any time if something comes up.
</Info>

---

<!-- llms-section: guides/testing/overview -->
### Test your integration
_Test your integration in the sandbox environment before going live_

Before your integration can access production, you need to test it in the sandbox environment.
This verifies that you're sending the right data to iwoca, and that you've built the right experience for every customer journey.

## How sandbox works

The sandbox is fully isolated and mirrors production exactly.
API endpoints are identical.
Webhooks fire in real time to your registered endpoint.
Application statuses behave the same way.
The only difference is that decisions are triggered by reserved test values rather than real credit assessment, and no real customer data is ever used.

## Getting access

<Steps>
  <Step title="Get your sandbox API token">
    Your iwoca Partnership Manager will give you access to the Developer Portal, where you can find your sandbox API token.
  </Step>
  <Step title="Explore test scenarios">
    Use our public Postman collection which contains all the relevant scenarios, or follow the guide for your integration type below.
  </Step>
  <Step title="Test and validate">
    Run through every scenario yourself, instantly, without involving anyone at iwoca.
  </Step>
</Steps>

## Choose your integration type

Follow the testing guide for the integration type you are building.

<CardGroup cols={2}>
  <Card title="API Lite" icon="code" href="/guides/testing/referral-integration-testing">
    Your platform collects customer data and sends it to iwoca.
    Testing confirms your data is formatted correctly and your login link works.
  </Card>
  <Card title="API Plus" icon="rocket" href="/guides/testing/decision-relayed-testing">
    Your platform displays every outcome to the customer.
    Testing confirms you've built the right experience for each scenario.
  </Card>
</CardGroup>

---

<!-- llms-section: guides/testing/referral-integration-testing -->
### API Lite testing
_Test scenarios and data for the API Lite integration_

Use this guide to test your API Lite integration in the sandbox environment.
The test data below triggers specific outcomes so you can verify every customer pathway.

## What you need to test

As a minimum, your integration needs to show:

- A new customer and application using the minimum data requirements
- Data formatted correctly following best-practice guidelines
- Endpoints used correctly and at the right stage in the journey
- Login link generated and displayed to the customer

## Test data

The data below should be used as the basis for all tests.
Sending this data unchanged returns a **confirmed offer**.

<Info>
Replace `{{currentDate}}` in `valid_from` with today's date in ISO 8601 format (for example, `2026-05-20T00:00:00.000Z`).
</Info>

### Customer payload

```json
{
    "data": {
        "company": {
            "company_number": "01111112",
            "registered_company_name": "COMPANY NAME",
            "type": "limited_liability_company",
            "trading_from_date": "2010-02-01",
            "last_12_months_turnover": {
                "amount": 700000,
                "valid_from": "{{currentDate}}"
            },
            "vat_status": {
                "is_vat_registered": false
            }
        },
        "people": [
            {
                "uid": "6cf7319e-f9ec-4038-ba4f-3561a6097484",
                "title": "mr",
                "first_name": "Ervin",
                "last_name": "Norton",
                "date_of_birth": "1980-01-01",
                "emails": [
                    {
                        "email": "enorton1777+test@iwoca.co.uk",
                        "type": "primary"
                    }
                ],
                "phones": [
                    {
                        "type": "primary",
                        "number": "07700900370"
                    }
                ],
                "residential_addresses": [
                    {
                        "country": "GB",
                        "date_from": "2014-02-03",
                        "house_number": "286",
                        "postcode": "CB62AG",
                        "residential_status": "owner_with_mortgage",
                        "street_line_1": "Idverifier St",
                        "town": "Ely"
                    }
                ],
                "privacy_policy": {
                    "agreed": true,
                    "valid_from": "{{currentDate}}"
                },
                "roles": [
                    "applicant",
                    "shareholder",
                    "guarantor",
                    "director"
                ]
            }
        ]
    }
}
```

### Application payload

```json
{
    "data": {
        "requests": [
            {
                "amount": 15000,
                "duration": {
                    "amount": 12,
                    "unit": "months"
                }
            }
        ]
    }
}
```

## Simulating different outcomes

Adjust the test data to trigger specific scenarios:

| Scenario | How to trigger |
|---|---|
| **Confirmed offer** — firm, ready-to-draw-down terms | Set `amount` to 15,000 or less (default test data) |
| **Indicative offer** — an estimate that needs more information before it's confirmed | Set `amount` to greater than 15,000, up to 75,000 |
| **Indicative offer (large)** — an indicative offer for amounts above £75,000 | Set `amount` to greater than 75,000 |
| **Decline** | Use the decline test data below |

### Decline test data

Change the following fields in the customer payload:

```json
{
    "first_name": "James",
    "last_name": "Smythe",
    "date_of_birth": "1985-01-01",
    "company_number": "01111113",
    "house_number": "123",
    "street_line_1": "Decline St",
    "town": "Decline",
    "postcode": "DE61NA"
}
```

This returns an empty `offers` array with `offer_creation_status: "decline"` when you call `GET /offers/`.

## Validation checklist

Before submitting for review, verify:

- [ ] Customer data formatted correctly with minimum required fields.
- [ ] Application created successfully with valid amount.
- [ ] Login link generated and redirects to iwoca.
- [ ] Webhook responses received (if applicable).

---

## Next steps

<CardGroup cols={2}>
  <Card title="Go live" icon="rocket" href="/guides/testing/go-live">
    Submit your integration for review and launch to production
  </Card>
</CardGroup>

---

<!-- llms-section: guides/webhooks/event-types -->
### Event types
_Available webhook events, when they fire, and example payloads_

Subscribe only to the events you need.
See the [list webhook event types](/api-reference/webhook-management/get-webhooks-event-types) endpoint for the full API reference.

## Available events

<AccordionGroup>
  <Accordion title="application_status_changed">
    Fired on every status transition.
    The most commonly used event.

    **Payload fields:** `customer_id`, `application_id`, `external_customer_id`, `is_closed`, `status`

    ```json
    {
      "event_type": "application_status_changed",
      "timestamp": "2026-01-15T10:30:00Z",
      "data": {
        "customer_id": "c9f4f988-a98e-446e-a121-ff3d631e3246",
        "application_id": "f200bd36-5257-41d6-a11e-51a1d3a23336",
        "external_customer_id": "your-reference-123",
        "is_closed": false,
        "status": "offered"
      }
    }
    ```

    **Possible statuses:**

    | Status | Description |
    |---|---|
    | `open` | The application has not reached the decision stage, usually because more information is needed. |
    | `action_required` | The documents uploaded or information shared does not meet iwoca's minimum requirements. You can generate offers to view the updated document requirements. |
    | `awaiting_underwriter` | The uploaded documents have met iwoca's requirements and the application is now awaiting a manual review by an underwriter. |
    | `in_underwriting` | The application is under review by a credit analyst. |
    | `conditional_offer` | iwoca has made an offer subject to special conditions, such as uploading VAT returns. |
    | `conditional_offer_criteria_met` | Reserved. Not currently sent. |
    | `customer_to_link_open_banking` | The customer needs to link open banking to proceed. |
    | `offered` | The customer has at least one confirmed offer. |
    | `talking_to_customer` | Customer has a confirmed offer and iwoca is in contact with them. |
    | `funded` | The customer has drawn down on the funds. |
    | `expired` | A formal offer was made but it has now expired. Offers are valid for 30 days. |
    | `declined` | iwoca has credit assessed the customer and they have been declined. No offers will be available. |
    | `deferred` | The application has been closed before the decision stage. All applications automatically defer after 30 days of inactivity. This is likely if the customer does not share the necessary information, they decide they no longer want to go ahead, or there is a block on iwoca's side (for example, they already have a facility). |
    | `offer_revoked` | iwoca had to revoke the offer, most likely due to failing compliance checks. |

    <Note>
    A customer rejecting their offer does not produce a distinct status.
    The application continues to report `offered` until the offer expires or is revoked.
    If you need to know whether a customer went ahead, use funding events rather than inferring it from status.
    </Note>

  </Accordion>

  <Accordion title="application_offered">
    Fired when a confirmed offer is generated.
    If multiple confirmed offers are generated, you receive multiple webhooks.

    **Payload fields:** `customer_id`, `application_id`, `external_customer_id`, `offer_id`, `max_amount`, `duration`, `interest_rates`, `interest_only_repayments`, `fee_percentage`, `approximate_apr`, `product_type`, `payment_interval`, `personal_guarantee_proportion`, `expiry_date`, `promotions`, `revoked_at`, `is_closed`

    ```json
    {
      "event_type": "application_offered",
      "timestamp": "2026-01-15T10:30:00Z",
      "data": {
        "application_id": "48ac72d0-a829-4896-a067-dcb1c2b0f30c",
        "approximate_apr": 0.565306,
        "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
        "duration": {
          "amount": 365.0,
          "unit": "days"
        },
        "expiry_date": "2026-02-14",
        "external_customer_id": "your-reference-123",
        "fee_percentage": 5.0,
        "interest_only_repayments": 0,
        "interest_rates": [
          {
            "as_of": 0,
            "rate": 0.0375
          }
        ],
        "is_closed": false,
        "max_amount": 100000,
        "offer_id": "d5a7a5b7-a4a3-49e7-9c69-b44d2cbe15cf",
        "payment_interval": "1m",
        "personal_guarantee_proportion": 100.0,
        "product_type": "flexi_loan",
        "promotions": [],
        "revoked_at": null
      }
    }
    ```

  </Accordion>

  <Accordion title="application_declined">
    Fired when an application is declined.
    The customer has been credit assessed and no offers will be available for this application.

    **Payload fields:** `customer_id`, `application_id`, `is_closed`

    ```json
    {
      "event_type": "application_declined",
      "timestamp": "2026-01-15T10:30:00Z",
      "data": {
        "application_id": "48ac72d0-a829-4896-a067-dcb1c2b0f30c",
        "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
        "is_closed": true
      }
    }
    ```

  </Accordion>

  <Accordion title="application_deferred">
    Fired when an application is closed without making an approve or decline decision.

    **Payload fields:** `customer_id`, `application_id`, `is_closed`, `reason`

    ```json
    {
      "event_type": "application_deferred",
      "timestamp": "2026-01-15T10:30:00Z",
      "data": {
        "application_id": "48ac72d0-a829-4896-a067-dcb1c2b0f30c",
        "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
        "is_closed": true,
        "reason": "timeout"
      }
    }
    ```

    **Possible reasons:**

    | Reason | Description |
    |---|---|
    | `iwoca` | Closed by iwoca (for example, after speaking to the customer). |
    | `timeout` | Closed automatically due to inactivity. |
    | `partner` | Unused. |

  </Accordion>

  <Accordion title="application_attributed">
    Fired when an application is attributed to an introducer.
    `application_attributed` is an event only, not an application status, so you will not see it in the `status` field.
    This happens when:
    - A customer or staff creates an application and it's attributed to you (previous IDs will be `null`).
    - An application is moved from one customer to another (for example, customer already has an iwoca account) – previous IDs show the old references.

    **Payload fields:** `current_customer_id`, `previous_customer_id`, `current_application_id`, `previous_application_id`

    ```json
    {
      "event_type": "application_attributed",
      "timestamp": "2026-01-15T10:30:00Z",
      "data": {
        "current_customer_id": "c9f4f988-a98e-446e-a121-ff3d631e3246",
        "previous_customer_id": null,
        "current_application_id": "f200bd36-5257-41d6-a11e-51a1d3a23336",
        "previous_application_id": null
      }
    }
    ```

    When previous IDs are populated, update your records to use the new `current_` IDs and stop tracking the previous ones.

  </Accordion>

  <Accordion title="indicative_offer_created">
    Fired when an indicative offer is available.

    **Payload fields:** `customer_id`, `application_id`, `external_customer_id`, `offer_id`, `max_amount`, `interest_rate`, `duration`, `probability_of_offer`, `data_requirements`, `is_suggested`, `product_type`, `timeout`

    ```json
    {
      "event_type": "indicative_offer_created",
      "timestamp": "2026-01-15T10:30:00Z",
      "data": {
        "application_id": "48ac72d0-a829-4896-a067-dcb1c2b0f30c",
        "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
        "data_requirements": [],
        "duration": {
          "amount": 365,
          "unit": "days"
        },
        "external_customer_id": "your-reference-123",
        "interest_rate": 0.0265,
        "is_suggested": true,
        "max_amount": 50000,
        "offer_id": "d5a7a5b7-a4a3-49e7-9c69-b44d2cbe15cf",
        "probability_of_offer": "low_probability_of_offer",
        "product_type": "flexi_loan",
        "timeout": "2026-02-15T10:30:00Z"
      }
    }
    ```

  </Accordion>

  <Accordion title="customer_funded">
    Fired when the customer draws down their loan.

    **Payload fields:** `customer_id`

    ```json
    {
      "event_type": "customer_funded",
      "timestamp": "2026-01-15T10:30:00Z",
      "data": {
        "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e"
      }
    }
    ```

  </Accordion>

  <Accordion title="prequalification_202505">
    Fired when a prequalification data file has been processed.
    Contains a quote for each unique `external_customer_id` in the uploaded file.

    **Payload fields:** Array of `quote_id`, `external_customer_id`, `is_prequalified`, `prequalified_amount`, `marketing_type`

    ```json
    {
      "event_type": "prequalification_202505",
      "timestamp": "2026-01-15T10:30:00Z",
      "data": [
        {
          "quote_id": "1c6e2a6f-41ed-490e-8d05-87e34e756f7a",
          "external_customer_id": "16aa735d-9890-479d-8cce-89d5c1c1df3d",
          "is_prequalified": true,
          "prequalified_amount": 10000,
          "marketing_type": "prequalified_marketing"
        },
        {
          "quote_id": "97976169-e0ff-4b60-afd0-869133a49828",
          "external_customer_id": "c21a167f-7aef-47f1-aeb6-c4d2c3d7799d",
          "is_prequalified": false,
          "prequalified_amount": null,
          "marketing_type": "generic_marketing"
        },
        {
          "quote_id": "8cccd62c-1a50-4ae1-854b-a6a021a2ac32",
          "external_customer_id": "1af8db98-bfff-4e5d-ad88-66dae61882ed",
          "is_prequalified": false,
          "prequalified_amount": null,
          "marketing_type": "no_marketing"
        }
      ]
    }
    ```

    **Marketing types:**

    | Type | Description |
    |---|---|
    | `prequalified_marketing` | Eligible with a predicted offer amount – show amount in marketing. |
    | `generic_marketing` | Could be eligible but no amount available – use generic marketing. |
    | `no_marketing` | Not eligible due to failing eligibility criteria – do not market. |

  </Accordion>

  <Accordion title="prequalification_data_file_processed_202510">
    Lighter version of `prequalification_202505`. Fired when a prequalification data file has been processed, but only contains the file identifier.
    Use this ID with `GET /prequalification_data` to retrieve the quotes.

    **Payload fields:** `prequalification_data_id`

    ```json
    {
      "event_type": "prequalification_data_file_processed_202510",
      "timestamp": "2026-01-15T10:30:00Z",
      "data": {
        "prequalification_data_id": "file-uploaded-for-prequalification.csv"
      }
    }
    ```

  </Accordion>
</AccordionGroup>

---

## Payload structure

Every webhook shares the same envelope:

```json
{
  "event_type": "application_status_changed",
  "timestamp": "2026-01-15T10:30:00Z",
  "data": {
    "customer_id": "894ff74b-b8fb-46ab-97d6-f9ff3428b779",
    ...
  }
}
```

## Event headers

Each webhook includes these headers:

| Header | Purpose |
|---|---|
| `X-IW-Event-ID` | Unique identifier for the webhook |
| `X-IW-Event-Type` | The event type that triggered the webhook |
| `X-IW-Signature` | Hash-based Message Authentication Code (HMAC) signature for verification – see [Security](/guides/webhooks/security) |
| `X-IW-Timestamp` | Unix timestamp when the webhook was sent |

---

<!-- llms-section: guides/webhooks/overview -->
### How webhooks work
_Receive real-time notifications when application statuses change_

iwoca sends webhooks to your endpoint when key events occur – application approvals, declines, offers, and funding.
No polling required.

<CardGroup cols={2}>
  <Card title="Event types" icon="list" href="/guides/webhooks/event-types">
    Available events and example payloads
  </Card>
  <Card title="Security" icon="shield" href="/guides/webhooks/security">
    Signature verification and retry behaviour
  </Card>
</CardGroup>

## Getting started

<Steps>
  <Step title="Get your webhook secret token">
    Retrieve your token via `GET /webhooks/configuration/` or from the Developer Portal (sandbox only).
  </Step>
  <Step title="Configure your webhook URL">
    Set the URL where iwoca should send events using `PUT /webhooks/configuration/` or the Developer Portal.
  </Step>
  <Step title="Subscribe to events">
    Choose which events you want to receive using `POST /webhooks/subscriptions/` or the Developer Portal.
  </Step>
  <Step title="Implement signature verification">
    Verify the `X-IW-Signature` header on incoming webhooks to confirm they're from iwoca.
    See [Security](/guides/webhooks/security) for code examples.
  </Step>
  <Step title="Test in sandbox">
    Trigger test events in the sandbox environment before going live.
  </Step>
</Steps>

<Warning>
Your webhook endpoint should respond with a `2xx` status code to confirm receipt.
Failed deliveries are retried up to 10 times over roughly 16 hours – see [retry behaviour](/guides/webhooks/security#retry-behaviour).
</Warning>

## Base URL

Webhook configuration and subscription endpoints use the same base URL as the rest of the lending API:

<Tabs>
  <Tab title="Production">
    | API | Base URL |
    |---|---|
    | Lending | `https://www.iwoca.co.uk/api/lending/v2.2` |
  </Tab>
  <Tab title="Sandbox">
    | API | Base URL |
    |---|---|
    | Lending | `https://stage.iwoca-dev.co.uk/api/lending/v2.2` |
  </Tab>
</Tabs>

Authenticate with your Bearer token, the same as any other lending API request.

---

<!-- llms-section: guides/webhooks/security -->
### Security
_Verify webhook signatures and handle retries_

Every webhook from iwoca includes a cryptographic signature so you can verify it's genuine before processing.
Signatures use a Hash-based Message Authentication Code (HMAC), which proves both that the payload is unchanged and that it came from someone holding your secret token.

## Signature verification

Each webhook includes two headers:

| Header | Purpose |
|---|---|
| `X-IW-Signature` | HMAC-SHA256 signature of the request |
| `X-IW-Timestamp` | Unix timestamp when the webhook was sent |

The signature is computed as:

```text
HMAC-SHA256(secret_token, timestamp + "." + request_body)
```

The result is base64-encoded and prefixed with `sha256=`, so the header looks like `sha256=YoSHTwbVZnuLY8kPusTeHoqcyQ9g1IeVHKpIFLJjp4k=`.

<Note>
A small number of older integrations are still on SHA-1, where the signature is `sha1=` + base64 of `HMAC-SHA1(secret_token, request_body)` – over the body alone, with no timestamp. `GET /webhooks/configuration/` returns an `encryption_method` of `sha256` or `sha1` so you can check which applies to you.
Everything below assumes `sha256`; if you are on `sha1`, talk to your Partnership Manager about moving across.
</Note>

## Code examples

<Tabs>
  <Tab title="Python">
    ```python
    import base64
    import hmac
    import hashlib
    import time

    def verify_webhook(request_body: bytes, signature: str, timestamp: str, secret: str) -> bool:
        # Reject old webhooks (replay protection)
        if abs(time.time() - int(timestamp)) > 300:
            return False

        digest = hmac.new(
            secret.encode(),
            f"{timestamp}.".encode() + request_body,
            hashlib.sha256
        ).digest()

        # The header is base64-encoded and prefixed with "sha256=" —
        # not a hex digest.
        expected = "sha256=" + base64.b64encode(digest).decode()

        return hmac.compare_digest(expected, signature)
    ```
  </Tab>
  <Tab title="Node.js">
    ```javascript
    const crypto = require('crypto');

    function verifyWebhook(body, signature, timestamp, secret) {
      // Reject old webhooks (replay protection)
      if (Math.abs(Date.now() / 1000 - parseInt(timestamp)) > 300) {
        return false;
      }

      // The header is base64-encoded and prefixed with "sha256=" —
      // not a hex digest.
      const expected =
        'sha256=' +
        crypto
          .createHmac('sha256', secret)
          .update(`${timestamp}.${body}`)
          .digest('base64');

      const a = Buffer.from(expected);
      const b = Buffer.from(signature);
      // timingSafeEqual throws if the lengths differ.
      return a.length === b.length && crypto.timingSafeEqual(a, b);
    }
    ```
  </Tab>
</Tabs>

## Replay protection

Use `X-IW-Timestamp` to reject stale webhooks.
We recommend rejecting any webhook where the timestamp is more than five minutes old.
This prevents replay attacks where a captured webhook is resent later.

## Retry behaviour

A delivery counts as successful when your endpoint responds with a status below 400. Anything else – a 4xx, a 5xx, a connection error, or a timeout – is a failed attempt and is retried.

By default iwoca retries up to **10 times after the first attempt, so 11 attempts in all**, spread over roughly **16 hours**:

| Attempt | Sent after the previous attempt |
|---|---|
| 1 | – (immediately after the event) |
| 2 | 10 seconds |
| 3 | 1 minute |
| 4 | 2 minutes |
| 5 | 5 minutes |
| 6 | 15 minutes |
| 7 | 30 minutes |
| 8 | 1 hour |
| 9 | 2 hours |
| 10 | 4 hours |
| 11 | 8 hours |

A few seconds of random jitter is added to each gap, so treat the times as approximate.
Each attempt waits up to **10 seconds** for your response before being treated as a timeout.

<Note>
These are the default timings.
The schedule is configurable per partner.
A custom one changes both the intervals **and the number of attempts**, so confirm yours with your Partnership Manager if your integration depends on either.
</Note>

### What each retry looks like

- `X-IW-Event-ID` stays the **same** across every attempt of the same event – use it as your idempotency key.
- `X-IW-Timestamp` and `X-IW-Signature` are **regenerated on every attempt**, because the timestamp is part of the signed payload.

<Warning>
Because each attempt carries a fresh timestamp, your signature verification must use the timestamp from the request in hand – never a cached value from an earlier attempt.
</Warning>

<Warning>
**Point your subscription at the final URL, not a redirect.**
Redirects are followed, but a `301`, `302` or `303` is followed as a bodyless `GET`.
Your handler still receives the `X-IW-*` headers, but the event payload is gone.
The redirect target's `2xx` makes the delivery look successful to iwoca, so it is never retried.
`307` and `308` do replay the full `POST`.
If the redirect crosses to another host, the signature headers are forwarded to that host as well.
Register the exact HTTPS URL you want to receive events on.
</Warning>

### After the last attempt

If all attempts fail, iwoca raises an internal alert and the delivery stops. **Your subscription stays active** – it is not disabled automatically, and events after that point are still delivered normally.
Nothing is re-sent to you automatically.
If your endpoint has been down, reconcile by calling the relevant `GET` endpoints — your Partnership Manager can arrange a manual redelivery if you need one.

<Note>
A manual redelivery arrives as a **separate event with its own `X-IW-Event-ID`**, so it will not match the ID of the original attempt.
If you need to detect that specific case, compare the payload fields as well as the event ID.
</Note>

<Note>
Test webhooks sent from the Developer Portal are attempted **once** and never retried, so you will not see retry behaviour while debugging there.
</Note>

## Idempotency

The same event may be delivered more than once.
Your webhook handler should be idempotent – processing the same event twice should not cause issues.
Use the `X-IW-Event-ID` header (a unique ID per webhook) as your idempotency key; fall back to the combination of `event_type`, `timestamp`, and the data fields if needed.

## IP allowlisting

If you need IP-based filtering, contact your Partnership Manager for iwoca's webhook IP addresses.

---


## API reference overviews

<!-- llms-section: api-reference/application/overview -->
### Application overview
_Application statuses, update rules, and key constraints_

Create and manage a loan application for a customer.
An application specifies how much the customer wants to borrow and progresses through various statuses as iwoca assesses it.

<CardGroup cols={3}>
  <Card title="Create application" icon="code" href="/api-reference/application/post-customers-applications">
    `POST` /customers/\{customer_id\}/applications/
  </Card>
  <Card title="Get latest application" icon="code" href="/api-reference/application/get-customers-applications-latest">
    `GET` /customers/\{customer_id\}/applications/latest/
  </Card>
  <Card title="Update application" icon="code" href="/api-reference/application/patch-customers-applications-latest">
    `PATCH` /customers/\{customer_id\}/applications/latest/
  </Card>
</CardGroup>

## Essentials

<Steps>
  <Step title="Set the amount">
    Required field, in GBP.
    The API accepts amounts up to £10,000,000, but iwoca's product ceiling is £1,000,000 — validate to £1,000,000 on your front end.
    If the customer has an existing loan, `amount` represents the additional funds requested (response includes `is_topup: true`).
  </Step>
  <Step title="Check the status">
    Poll `GET /applications/latest/` or use webhooks (`application_status_changed`) to track progress.
    The `is_closed` field tells you whether the application can still be modified.
  </Step>
  <Step title="Update if needed">
    Use `PATCH /applications/latest/` to change amount, duration, or purpose.
    Only works while the application is still open (`open`, `action_required`, `awaiting_underwriter`, or `in_underwriting`).
  </Step>
</Steps>

<Info>
- Wait three months before opening a new application for a declined customer.
</Info>

## Reference

<AccordionGroup>
  <Accordion title="Application statuses">
    | Status | Definition |
    |---|---|
    | `open` | No decision yet, possibly missing information |
    | `action_required` | Uploaded documents may not meet requirements |
    | `awaiting_underwriter` | Documents meet requirements, awaiting Credit Analyst |
    | `in_underwriting` | A Credit Analyst is assessing the application |
    | `offered` | Confirmed offer issued |
    | `funded` | Customer has drawn down |
    | `expired` | Offer expired |
    | `deferred` | Application deferred or timed out |
    | `declined` | iwoca could not make an offer |
    | `talking_to_customer` | Offer given, contact entity switched to customer |
    | `conditional_offer` | Offer subject to special conditions (rare) |
    | `offer_revoked` | Offer revoked (for example, identity verification issue) |
  </Accordion>
  <Accordion title="Open vs closed applications">
    A closed application is one where:
    - iwoca made a decision and returned an offer (`offered`).
    - iwoca declined the customer (`declined`).
    - The application timed out (`deferred`).

    The `is_closed` field indicates whether the application can still be modified.
  </Accordion>
  <Accordion title="Purpose values">
    `stock_purchase`, `bridging_loan`, `marketing`, `equipment_purchase`, `pay_bill`, `pay_staff`, `refinancing_debt`, `financing_client_order`, `pay_tax_bill`, `other`
  </Accordion>
  <Accordion title="Optional fields">
    - `duration` – Object with `amount` (integer) and `unit`.
      Requests use `months`; offer and webhook payloads may return the duration in `days`.
      Valid units: `days`, `months`, `years`.
    - `purpose` – Enum, see values above
  </Accordion>
</AccordionGroup>

---

<!-- llms-section: api-reference/customer/overview -->
### Customer overview
_Key requirements and best practices for creating customers_

Create an iwoca account for a business customer.
You provide company and director details, and receive a `customer_id` used in all subsequent requests.

<CardGroup cols={1}>
  <Card title="Create customer" icon="code" href="/api-reference/customer/post-customers">
    `POST` /customers/
  </Card>
</CardGroup>

## Essentials

<Steps>
  <Step title="Include minimum data">
    The following data is the minimum needed to make a decision and the complete set needed for an automated decision.
    Missing data means no automated decisions or indicative offers.

    | Category | Fields |
    |----------|--------|
    | **Personal information** | First name, Last name, Role within business (director), Email(s), Phone number(s), Date of birth, Residential address, Privacy policy agreement |
    | **Business information** | Company name, Company number, Company type, Trading from date, Last 12 months turnover |
    | **Request information** | Amount |
  </Step>
  <Step title="Set the applicant role">
    Exactly one person must have `"roles": ["applicant", "director", "guarantor"]`.
    The applicant must be a director who can provide a personal guarantee.
  </Step>
</Steps>

<Warning>
The `privacy_policy.agreed: true` field is required.
It confirms your privacy policy covers sharing data with iwoca, and that soft credit checks and fraud prevention agency sharing are disclosed.
</Warning>

## Avoiding duplicate customers

Duplicate customers cause delays because our team often needs to review them manually.
Avoid submitting multiple duplicate requests to iwoca for the same customer.

Handle this on your end by preventing the same customer submitting a `POST` request to `/customers/` multiple times.
As a safeguard, you can also pass your own unique identifier (for example, your internal user or company ID) in the `external_customer_id` field.
If you send a second `POST /customers/` with the same `external_customer_id`, iwoca returns a `409 Conflict` response containing the original `customer_id` rather than creating a duplicate:

```json
{
  "errors": [{
    "code": "ConflictError",
    "detail": "external_customer_id already exists",
    "meta": {"customer_id": "894ff74b-b8fb-46ab-97d6-f9ff3428b779"}
  }]
}
```

<Tip>
Use the returned `customer_id` from the `409` response to continue working with the existing customer rather than retrying the creation.
</Tip>

## Reference

<AccordionGroup>
  <Accordion title="Minimum company fields">
    - `company_number` (string)
    - `registered_company_name` (string)
    - `type` (string enum)
    - `trading_from_date` (date)
    - `last_12_months_turnover` – Object with `amount` (number) and `valid_from` (datetime)
    - `vat_status` – Object with `is_vat_registered` (bool), optionally `registered_over_3_months`, `vat_number`
  </Accordion>
  <Accordion title="Minimum person fields">
    - `uid` (v4 UUID)
    - `title` (string enum)
    - `first_name`, `last_name` (string)
    - `date_of_birth` (date)
    - `emails` – Array with `email` and `type: "primary"`
    - `phones` – Array with `number` and `type: "primary"`
    - `residential_addresses` – Array with `country`, `house_number`, `house_name`, `street_line_1`, `town`, `postcode`
    - `privacy_policy` – Object with `agreed` (bool) and `valid_from` (datetime)
    - `roles` (string enum array)
  </Accordion>
  <Accordion title="Address formatting">
    Send `house_name` or `house_number` in their own fields – do not include them in `street_line_1`.
    This improves credit report matching.

    ```json
    {
      "residential_addresses": [{
        "country": "GB",
        "house_number": "123",
        "street_line_1": "Main Street",
        "town": "London",
        "postcode": "N5 1JK"
      }]
    }
    ```
  </Accordion>
  <Accordion title="Equifax PTC-Abs token">
    If you have access to the Equifax PTC-Abs address token, send it in the `equifax_token` field within `residential_addresses`.
    This improves automated decision rates.
  </Accordion>
</AccordionGroup>

---

<!-- llms-section: api-reference/developer-portal/overview -->
### Developer Portal overview
_Invite team members to your partner developer account_

Manage access to your Partner Developer Portal by inviting team members.
Invited developers can view API tokens, configure webhooks, and access sandbox environments.

<CardGroup cols={1}>
  <Card title="Invite developer" icon="code" href="/api-reference/developer-portal/post-partner-developer-invite">
    `POST` /partner_developer_invite/
  </Card>
</CardGroup>

## Essentials

<Steps>
  <Step title="Invite by email">
    Send the developer's email address.
    They'll receive an invitation to join the portal.
  </Step>
  <Step title="Manage access centrally">
    All invited developers share access to your partner's API tokens and webhook configuration.
  </Step>
</Steps>

## Reference

<AccordionGroup>
  <Accordion title="What invited developers can access">
    - API tokens (sandbox and production)
    - Webhook configuration
    - Sandbox testing environments
    - Integration documentation
  </Accordion>
  <Accordion title="Managing team members">
    iwoca sends invitations by email.
    To revoke access, manage team members directly in the Partner Developer Portal UI.
  </Accordion>
</AccordionGroup>

---

<!-- llms-section: api-reference/documents/overview -->
### Documents overview
_Upload formats, timing, and JSON bank statement structure_

Upload supporting documents – bank statements, VAT returns, and company accounts – to support a customer's application.
Uploading documents helps your customers get faster decisions and larger offers.

<CardGroup cols={3}>
  <Card title="List documents" icon="code" href="/api-reference/documents/get-document-upload">
    `GET` /document_upload/\{customer_id\}/
  </Card>
  <Card title="Upload document" icon="code" href="/api-reference/documents/post-document-upload">
    `POST` /document_upload/\{customer_id\}/
  </Card>
  <Card title="Upload bank statement" icon="code" href="/api-reference/documents/post-bank-statements">
    `POST` /bank_statements/\{customer_id\}/
  </Card>
</CardGroup>

## Essentials

<Steps>
  <Step title="Upload before requesting offers">
    Upload all available documents **before** calling `GET /offers/` or `GET /login_link/`.
    This enables faster automated decisions, more instant approvals, and larger offers.
  </Step>
  <Step title="Use the right format">
    PDFs for most documents (bank statements, accounts, VAT returns).
    JSON only for Open Banking bank statement data.
    Non-PDF files take longer to process.
  </Step>
  <Step title="Check upload status">
    `GET /document_upload/{customer_id}/` returns document status and any `reject_reason` if a document wasn't accepted.
  </Step>
</Steps>

<Warning>
Only send one bank account per request/file.
Uploading the same file twice returns an error.
</Warning>

## Reference

<AccordionGroup>
  <Accordion title="Request format">
    Documents are uploaded as `multipart/form-data` with two parts:
    - The document file
    - The document type (`bank_statement`, `vat_returns`, `company_accounts`)
  </Accordion>
  <Accordion title="JSON bank statement format">
    For Open Banking data, the JSON must include:

    **Mandatory `accountInfo` fields:**
    - `accountNumber`, `sortCode`, `accountHolder`
    - `currency`, `bankName`

    **Mandatory transaction fields:**
    - `transactionDate`, `description`, `amount`, `runningBalance`

    For each transaction you can provide `startingBalance` and `closingBalance` (the account balance immediately before and after that transaction) instead of `runningBalance`.

    **Preferred fields:**
    - Account type (business or personal)
    - Period (earliest and latest transaction dates)
  </Accordion>
  <Accordion title="Checking upload status response">
    `GET /document_upload/{customer_id}/` returns two arrays:

    - **`data`** – List of documents with `type`, `id`, and `attributes` (may include `status` and `reject_reason`).
    - **`included`** – Additional info for bank statements (bank name, account number).
      Match using `relationships` field in `data`.
  </Accordion>
</AccordionGroup>

---

<!-- llms-section: api-reference/funding-account-details/overview -->
### Funding account details overview
_Specify where iwoca should send funds_

Provide the bank account where iwoca should deposit funds when a customer draws down.
This must be a UK business bank account belonging to the customer.

<CardGroup cols={1}>
  <Card title="Add funding account details" icon="code" href="/api-reference/funding-account-details/post-funding-account-details">
    `POST` /funding_account_details/\{customer_id\}/
  </Card>
</CardGroup>

## Essentials

<Steps>
  <Step title="Submit before draw down">
    Share account details before the customer completes draw down so iwoca can send funds immediately.
  </Step>
  <Step title="Must be a business account">
    The account must belong to the business customer – personal accounts are not accepted.
  </Step>
</Steps>

## Reference

<AccordionGroup>
  <Accordion title="Required fields">
    - `sort_code` – six digits, no hyphens.
    - `account_number` – eight digits.
    - `account_holder_name` – Must match the business name.
  </Accordion>
  <Accordion title="When to submit">
    You can submit funding account details at any time after customer creation.
    However, draw down cannot complete until valid account details are on file.
  </Accordion>
</AccordionGroup>

---

<!-- llms-section: api-reference/fundings/overview -->
### Fundings overview
_Retrieve draw down history for a customer_

Retrieve a customer's funding history – the loans they've drawn down.

<CardGroup cols={1}>
  <Card title="List fundings" icon="code" href="/api-reference/fundings/get-customers-fundings">
    `GET` /customers/\{customer_id\}/fundings/
  </Card>
</CardGroup>

## Essentials

<Steps>
  <Step title="Check after offer selection">
    Fundings appear after a customer has selected a confirmed offer and completed draw down on iwoca's platform.
  </Step>
  <Step title="Use for reconciliation">
    Use this endpoint to confirm draw down has occurred and track funding amounts for your records.
  </Step>
</Steps>

## Pagination

This endpoint is paginated, and the `limit` and `offset` query parameters are **required**.

| Parameter | Required | Range | Description |
| --- | --- | --- | --- |
| `limit` | Yes | 1–50 | The maximum number of funding records to return in one response. |
| `offset` | Yes | 0 or greater | The number of records to skip before returning results. |

`data.count` always reports the total number of fundings for the customer, which may be more than the number of records returned in `data.items` for a given page.

To page through results, increase `offset` by `limit` on each request.
For example, `limit=5&offset=0` returns the first five records, and `limit=5&offset=5` returns the next five.

Keep requesting pages until `offset` reaches `data.count`.

## Reference

<AccordionGroup>
  <Accordion title="When fundings appear">
    iwoca creates a funding record after the customer completes draw down.
    This happens after offer selection and any remaining compliance steps.
  </Accordion>
</AccordionGroup>

---

<!-- llms-section: api-reference/introducers/overview -->
### Introducers overview
_Manage introducer records associated with your partner account_

Manage introducers (brokers, agents, or sub-partners) associated with your partner account.
Introducers can be linked to customers to track referral sources.

<CardGroup cols={2}>
  <Card title="List introducers" icon="code" href="/api-reference/introducers/get-introducers">
    `GET` /introducers/
  </Card>
  <Card title="Create introducer" icon="code" href="/api-reference/introducers/post-introducers">
    `POST` /introducers/
  </Card>
</CardGroup>

## Essentials

<Steps>
  <Step title="Create introducers before referrals">
    Register your introducers so they can be linked to customers at creation time.
  </Step>
  <Step title="Link to customers">
    Pass the `introducer_id` when creating a customer to associate the referral source.
  </Step>
</Steps>

## Reference

<AccordionGroup>
  <Accordion title="Introducer fields">
    - `name` – Display name for the introducer
    - `email` – Contact email address
    - `introducer_id` – Returned on creation, used when linking to customers
  </Accordion>
  <Accordion title="Linking to customers">
    When calling `POST /customers/`, include the `introducer_id` in the request body to track which introducer referred the customer.
  </Accordion>
</AccordionGroup>

---

<!-- llms-section: api-reference/login-link/overview -->
### Login link overview
_Generate single-use magic links for customer access_

Generate a single-use magic link that takes the customer directly into iwoca's platform – to select an offer, send documents, or draw down funds.

<CardGroup cols={1}>
  <Card title="Get login link" icon="code" href="/api-reference/login-link/get-customers-login-link">
    `GET` /customers/\{customer_id\}/login_link/
  </Card>
</CardGroup>

## Essentials

<Steps>
  <Step title="You must be the customer's most recent introducer">
    You can only generate a link for a customer you introduced most recently.
    If another partner – or iwoca directly – has picked the customer up since, you'll get `403 Forbidden`.
  </Step>
  <Step title="Link is single-use">
    Each generated URL can only be used once.
    Generate a fresh link each time you need to redirect the customer.
  </Step>
  <Step title="Tell us which offer you're linking to">
    Pass the customer's chosen offer as `offer_id` – for example `GET /customers/{customer_id}/login_link/?offer_id=550e8400-e29b-41d4-a716-446655440000`.
    It's optional, and the link is always returned whether you include it or not.
  </Step>
  <Step title="Destination depends on state">
    Where the customer lands depends on their application progress – they may be selecting an offer, providing documents, or drawing down immediately.
  </Step>
</Steps>

## Reference

<AccordionGroup>
  <Accordion title="Destination by application state">
    | State | Customer experience |
    |---|---|
    | No offers selected | Lands in offer selection process |
    | Confirmed offer selected | Can immediately draw down |
    | Sample/indicative offer selected | Asked to provide documentation |
  </Accordion>
</AccordionGroup>

---

<!-- llms-section: api-reference/offers/overview -->
### Offers overview
_Offer types, data requirements, and retrieval strategies_

Generate and retrieve loan offers for a customer's application.
Offers range from sample estimates to fully confirmed terms the customer can draw down on.

<CardGroup cols={1}>
  <Card title="Generate offers" icon="code" href="/api-reference/offers/get-applications-offers">
    `GET` /applications/\{application_id\}/offers/
  </Card>
</CardGroup>

## Essentials

<Steps>
  <Step title="Call and wait">
    This endpoint can take up to 30 seconds on the first call.
    Show a loading indicator.
    Subsequent calls are faster.
  </Step>
  <Step title="Check offer type">
    Offers progress from `sample` to `indicative` to `confirmed`.
    Only `confirmed` offers can be drawn down.
    Check `data_requirements` on non-confirmed offers to see what's needed to upgrade.
  </Step>
  <Step title="Use webhooks for updates">
    Rather than polling, listen for `application_status_changed` and `application_offered` webhooks.
    If polling, check `GET /applications/latest/` for `offered` status before calling this endpoint.
  </Step>
</Steps>

<Info>
New fields may be added at any time.
Code defensively and ignore unrecognised fields.
</Info>

## Displaying offers

How you present an offer to the customer depends on its type.

### Confirmed offers

Confirmed offers have fixed terms – the amount, monthly interest rate, and repayment schedule are set and will not change.
The customer can draw down instantly.

- Display the amount, monthly interest rate, duration, and total repayable as firm figures.
- The CTA should allow the customer to draw down straight away (for example, 'Accept offer' or 'Draw down').

### Indicative and sample offers

Indicative and sample offers are estimates based on the information available so far.
The monthly interest rate, amount, and other terms are approximate and may change once iwoca completes a full assessment.

- Clearly communicate that the figures shown are indicative and subject to change.
- Do not present these as guaranteed terms.
- The CTA should read **'Continue to iwoca'** – directing the customer to complete any outstanding requirements and receive a confirmed offer.

<Warning>
Displaying indicative or sample offers as confirmed terms is misleading to customers.
Always make it clear that these figures may change.
</Warning>

## Reference

<AccordionGroup>
  <Accordion title="Offer types">
    | Type | Description | Extra fields |
    |---|---|---|
    | `confirmed` | Fully credit assessed, can draw down | `total_repayable`, `normal_repayment_amount`, `average_interest_only_repayment_amount` |
    | `indicative` | Partially assessed, more info needed | `probability_of_offer` |
    | `sample` | Not yet assessed, customer likely eligible | None |
  </Accordion>
  <Accordion title="Probability of offer (indicative only)">
    - `high` – Approximately 80% or greater probability of confirmed offer
    - `medium` – Approximately 55% or greater probability
    - `low` – Approximately 12% probability
  </Accordion>
  <Accordion title="How offers evolve">
    - An offer can be superseded as the application progresses (sample -> indicative -> confirmed).
    - When the `offer_type` upgrades, the `offer_id` changes.
    - `max_amount` and `interest_rate` for indicative/sample offers are approximate.
    - Maximum 3–4 offers typically returned.
    - `is_suggested` marks the recommended offer.
  </Accordion>
  <Accordion title="Data requirements">
    `sample` and `indicative` offers include a `data_requirements` array:

    | Requirement | Category | Action |
    |---|---|---|
    | `upload_bank_statement` | Documents | Upload to `/document_upload/` |
    | `upload_vat_returns` | Documents | Upload to `/document_upload/` |
    | `upload_company_accounts` | Documents | Upload to `/document_upload/` |
    | `complete_business_credit_check` | Company data | Contact iwoca if unresolved |
    | `complete_personal_credit_check` | Personal data | Contact iwoca if unresolved |
    | `check_customer_is_not_linked_to_existing_user_by_features` | Know your customer | Contact iwoca if unresolved |
    | `check_director_as_guarantor` | Personal data | Contact iwoca if unresolved |
    | `check_director_as_applicant` | Personal data | Contact iwoca if unresolved |
    | `check_directors_match_companies_house` | Personal data | Contact iwoca if unresolved |
  </Accordion>
  <Accordion title="Decline response">
    If `offer_creation_status` returns `decline`, the offers array will be empty and the customer has been declined.

    If `offer_creation_status` returns `other` with a `decline_reasons` entry of `{"reason": "Other", "reason_detail": "No available funds"}`, the customer has an existing loan and isn't currently eligible for additional funding.
  </Accordion>
</AccordionGroup>

---

<!-- llms-section: api-reference/openapi/overview -->
### OpenAPI schema
_Download the machine-readable OpenAPI 3.1 schema for the Lending API_

The full Lending API schema is published as a single OpenAPI 3.1 document.
Point your tooling or your AI coding assistant at it directly.

<CardGroup cols={2}>
  <Card title="Download openapi.json" icon="code" href="/openapi.json">
    OpenAPI 3.1, version `v2.2`
  </Card>
  <Card title="Download full documentation as .txt" icon="file-lines" href="/llms-full.txt">
    Every page in one file, for AI tools
  </Card>
</CardGroup>

<Prompt description="Fetch it from your terminal" actions={["copy"]}>
curl -O https://lending-api-docs.iwoca.co.uk/openapi.json
</Prompt>

## What's inside

| | |
|---|---|
| Specification | OpenAPI 3.1 |
| API version | `v2.2` |
| Endpoints | 18 paths, 26 operations |
| Webhook events | 10, under the top-level `webhooks` map |
| Authentication | Bearer token — see [Access the API](/guides/getting-started/authentication) |

## Webhook payload schemas

Every webhook event carries its full payload schema in the same document, under the
top-level `webhooks` map — the OpenAPI 3.1 feature designed for exactly this.

<Note>
If you have previously had to reverse-engineer webhook payloads from example JSON, this is
the structured description you were missing. `application_offered` alone documents 17 fields.
</Note>

## Using it with tooling

<Tabs>
  <Tab title="Postman">
    **Import → Link**, then paste `https://lending-api-docs.iwoca.co.uk/openapi.json`. Postman
    generates a collection covering every endpoint.
  </Tab>
  <Tab title="Insomnia">
    **Import From → URL**, then paste the same link.
  </Tab>
  <Tab title="Code generation">
    The schema works with `openapi-generator`, `oapi-codegen` and similar tools:

    ```bash
    openapi-generator generate \
      -i https://lending-api-docs.iwoca.co.uk/openapi.json \
      -g typescript-fetch \
      -o ./iwoca-client
    ```
  </Tab>
</Tabs>

<Warning>
The schema is **fully dereferenced** — every `$ref` is expanded in place, so there is no `components/schemas` section.
Generated clients will therefore produce inline anonymous types rather than named, reusable models.
If that causes you a problem, tell us.
</Warning>

---

<!-- llms-section: api-reference/overview -->
### Overview
_Authentication, base URLs, and endpoint flows by integration type_

The iwoca Lending API lets you refer customers for business finance, track their application, and surface offers.
The endpoints you call depend on your integration type.

<CardGroup cols={3}>
  <Card title="Customers" icon="user" href="/api-reference/customer/overview">
    Create and manage customers
  </Card>
  <Card title="Applications" icon="rectangle-list" href="/api-reference/application/overview">
    Submit loan applications
  </Card>
  <Card title="Offers" icon="hand-holding-dollar" href="/api-reference/offers/overview">
    Retrieve and select offers
  </Card>
  <Card title="Documents" icon="folder-open" href="/api-reference/documents/overview">
    Upload supporting documents
  </Card>
  <Card title="Prequalification" icon="filter" href="/api-reference/prequalification/overview">
    Check eligibility before applying
  </Card>
  <Card title="Webhooks" icon="bell" href="/api-reference/webhooks/overview">
    Real-time status notifications
  </Card>
</CardGroup>

## Endpoint flow by integration type

<Tabs>
  <Tab title="API Lite">
    Create a customer and hand off to iwoca.

    <Steps>
      <Step title="POST /customers/">
        Create the customer with company and director details.
      </Step>
      <Step title="POST /customers/{customer_id}/applications/">
        Submit a loan application with the requested amount.
      </Step>
      <Step title="GET /customers/{customer_id}/login_link/">
        Redirect the customer to iwoca to complete the process.
      </Step>
    </Steps>
  </Tab>
  <Tab title="API Plus">
    Surface offers and handle selection in your UI before handing off.

    <Steps>
      <Step title="POST /customers/">
        Create the customer with full details for automated decisions.
      </Step>
      <Step title="POST /customers/{customer_id}/applications/">
        Submit a loan application with the requested amount.
      </Step>
      <Step title="GET /applications/{application_id}/offers/">
        Retrieve offers (may take up to 30s on first call).
      </Step>
      <Step title="GET /customers/{customer_id}/login_link/">
        Customer selects an offer – get a login link, passing their chosen offer as `offer_id`, and redirect them to iwoca.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Additional endpoints

Beyond the core flow, you can use additional endpoints for document uploads, repayment schedules, funding account details, prequalification, and more.
Browse the sidebar to explore all endpoints.

---

## Authentication

<CardGroup cols={1}>
  <Card title="Check authentication" icon="code" href="/api-reference/authentication-check/get-authentication-check">
    `GET` /authentication_check/
  </Card>
</CardGroup>

```bash
curl -X GET https://stage.iwoca-dev.co.uk/api/lending/v2.2/authentication_check/ \
  -H "Authorization: Bearer {your_api_token}" \
  -H "Accept: application/json"
```

```json Response
{
  "data": {
    "api_version": "2.2.0"
  }
}
```

<Steps>
  <Step title="Get your API token">
    Retrieve your token from the [Partner Developer Portal](https://stage.iwoca-dev.co.uk/login/).
    You'll have separate tokens for sandbox and production.
  </Step>
  <Step title="Set required headers">
    Every request needs `Authorization` and `Accept`.
    POST/PATCH requests also need `Content-Type`.
  </Step>
  <Step title="Verify your connection">
    Call `GET /authentication_check/` to confirm everything is working before building your integration.
  </Step>
</Steps>

## Reference

<AccordionGroup>
  <Accordion title="Base URLs">
    | Environment | URL |
    |---|---|
    | Sandbox | `https://stage.iwoca-dev.co.uk/api/lending/v2.2` |
    | Production | `https://www.iwoca.co.uk/api/lending/v2.2` |
  </Accordion>
  <Accordion title="Required headers">
    | Header | Value | When |
    |---|---|---|
    | `Authorization` | `Bearer {token}` | Every request |
    | `Accept` | `application/json` | Every request |
    | `Content-Type` | `application/json` | POST/PATCH requests |
  </Accordion>
</AccordionGroup>

---

<!-- llms-section: api-reference/prequalification/overview -->
### Prequalification overview
_Upload customer data for pre-screening before a full application_

Pre-screen customers before they apply.
Upload basic business data to get an indication of eligibility without running credit checks or creating a full application.

<Info>
**Not enabled by default.** The prequalification endpoint must be switched on for your account before you can use it.
To get started, contact your iwoca Partnership Manager or email [partners@iwoca.co.uk](mailto:partners@iwoca.co.uk).
</Info>

<CardGroup cols={2}>
  <Card title="List quotes" icon="code" href="/api-reference/prequalification/get-prequalification-data">
    `GET` /prequalification_data/
  </Card>
  <Card title="Upload data" icon="code" href="/api-reference/prequalification/post-prequalification-data">
    `POST` /prequalification_data/
  </Card>
</CardGroup>

## Essentials

<Steps>
  <Step title="Upload minimal data">
    Only basic company information is needed – no personal details or credit checks are involved.
  </Step>
  <Step title="Use the result to qualify leads">
    Filter your customer base to those likely eligible before starting the full application flow.
  </Step>
  <Step title="Retrieve quotes later">
    Use `GET /prequalification_data/` to list all quotes generated for your account.
  </Step>
</Steps>

## Reference

<AccordionGroup>
  <Accordion title="What data is needed">
    Minimum required fields:
    - `company_number` – Companies House registration number
    - `company_name` – Registered company name

    Include average monthly turnover wherever you have it: without a revenue indication we can only return `generic_marketing`, not a specific prequalified amount.
  </Accordion>
  <Accordion title="Prequalification vs full application">
    Prequalification is a lightweight check – no credit searches, no customer account created, no personal data needed.
    Use it to filter leads before investing in the full application flow.
  </Accordion>
</AccordionGroup>

---

<!-- llms-section: api-reference/repayment-schedule/overview -->
### Repayment schedule overview
_Month-by-month repayment breakdowns for offers_

Get a detailed month-by-month repayment breakdown for a specific offer, showing the customer exactly what they'll pay and when.

<CardGroup cols={1}>
  <Card title="Get repayment schedule" icon="code" href="/api-reference/repayment-schedule/get-offers-repayment-schedule">
    `GET` /offers/\{offer_id\}/repayment_schedule/
  </Card>
</CardGroup>

## Essentials

<Steps>
  <Step title="Get offers first">
    You need a confirmed `offer_id` from `GET /applications/{application_id}/offers/` before you can request a schedule.
  </Step>
  <Step title="Use for display purposes">
    Show the schedule to your customer so they understand the repayment structure before selecting an offer.
  </Step>
</Steps>

## Reference

<AccordionGroup>
  <Accordion title="Response fields">
    Each repayment entry includes:
    - `date` – The repayment due date
    - `principal` – Amount going towards the loan balance
    - `interest` – Interest charged for the period
    - `total` – Total payment due (principal + interest)
  </Accordion>
  <Accordion title="Schedule vs actual repayments">
    The repayment schedule is indicative and based on the offer terms.
    Actual repayments may differ if the customer draws down a different amount or repays early.
  </Accordion>
</AccordionGroup>

---

<!-- llms-section: api-reference/select/overview -->
### Offer selection overview
_Selecting offers for customer draw down_

<Warning>
**BROKER ONLY INTEGRATIONS.** This endpoint is for broker and hybrid integrations, where iwoca contacts the broker rather than the customer.
If you're building a decision-relayed integration, don't call it – redirect the customer with [`GET /customers/{customer_id}/login_link/`](/api-reference/login-link/overview) instead, passing their chosen offer as `offer_id`.
</Warning>

Confirm which offer a customer wants to go ahead with.
This tells iwoca to prepare for draw down on the selected terms.
You can only select one offer per application.

<CardGroup cols={1}>
  <Card title="Select offer" icon="code" href="/api-reference/select/post-offers-select">
    `POST` /offers/\{offer_id\}/select/
  </Card>
</CardGroup>

## Essentials

<Steps>
  <Step title="Select the offer">
    Call `POST /offers/{offer_id}/select/` with the customer's chosen offer.
    This tells iwoca to go ahead.
  </Step>
  <Step title="Hand the customer over">
    Pass `"entity_to_contact": "customer"` in the request body when you want iwoca to take over contact with the customer from here.
  </Step>
  <Step title="Redirect the customer">
    When contact entity is set to `customer`, the response includes a `login_url`.
    Redirect the customer there to complete draw down.
  </Step>
</Steps>

## Reference

<AccordionGroup>
  <Accordion title="Contact entity behaviour">
    When `entity_to_contact` is updated to `customer`:
    - The response includes a `login_url`.
    - iwoca may contact the customer directly.
  </Accordion>
</AccordionGroup>

---

<!-- llms-section: api-reference/webhooks/overview -->
### Webhooks overview
_How to receive real-time events from iwoca, and the endpoints that manage them_

Webhooks let iwoca notify your system the moment something happens — an application is offered or declined, or a customer is funded.
You never have to poll.
There are two sides to webhooks in this API:

- **Endpoints you call** to configure your webhook URL and manage which events you receive.
- **Events iwoca sends** to your endpoint as `POST` requests when something happens.

<CardGroup cols={2}>
  <Card title="How webhooks work (guide)" icon="book" href="/guides/webhooks/overview">
    Concepts, base URL and end-to-end setup
  </Card>
  <Card title="Security" icon="shield" href="/guides/webhooks/security">
    Verify the `X-IW-Signature` header and handle retries
  </Card>
</CardGroup>

## Setting up

<Steps>
  <Step title="Configure your webhook URL and token">
    Set the endpoint iwoca should call using [`PUT /webhooks/configuration/`](/api-reference/webhook-management/put-webhooks-configuration). Read the current config with [`GET /webhooks/configuration/`](/api-reference/webhook-management/get-webhooks-configuration).
  </Step>
  <Step title="Subscribe to the events you want">
    Choose which events to receive with [`POST /webhooks/subscriptions/`](/api-reference/webhook-management/post-webhooks-subscriptions). Review your subscriptions with [`GET /webhooks/subscriptions/`](/api-reference/webhook-management/get-webhooks-subscriptions), and remove them with [`DELETE /webhooks/subscriptions/`](/api-reference/webhook-management/delete-webhooks-subscriptions).
  </Step>
  <Step title="Check available event types">
    See every event you can subscribe to with [`GET /webhooks/event_types/`](/api-reference/webhook-management/get-webhooks-event-types).
  </Step>
  <Step title="Verify signatures">
    Confirm each incoming webhook is from iwoca by checking the `X-IW-Signature` header — see [Security](/guides/webhooks/security).
  </Step>
</Steps>

<Warning>
Your webhook endpoint should respond with a `2xx` status code to confirm receipt.
Failed deliveries are retried up to 10 times over roughly 16 hours – see [retry behaviour](/guides/webhooks/security#retry-behaviour). Your subscription stays active either way; it is never disabled automatically.
</Warning>

## Events iwoca sends

Each event below is delivered as a `POST` to your configured URL. Follow the link for the exact payload schema.

| Event | When it fires |
| --- | --- |
| [`application_attributed`](/api-reference/webhooks/post-application-attributed) | An application is created for a customer and attributed to you. |
| [`application_offered`](/api-reference/webhooks/post-application-offered) | The customer receives a confirmed offer. |
| [`application_declined`](/api-reference/webhooks/post-application-declined) | A customer's application is declined. |
| [`application_deferred`](/api-reference/webhooks/post-application-deferred) | An application is deferred (closed without an approve/decline decision). |
| [`application_status_changed`](/api-reference/webhooks/post-application-status-changed) | The status of an application changes. |
| [`indicative_offer_created`](/api-reference/webhooks/post-indicative-offer-created) | An indicative offer is created. |
| [`customer_funded`](/api-reference/webhooks/post-customer-funded) | A customer draws down funds from an offer originating from your application. |
| [`funding_created_202607`](/api-reference/webhooks/post-funding-created-202607) | Funds are sent to a customer. |
| [`prequalification_202505`](/api-reference/webhooks/post-prequalification-202505) | Sent when a prequalification data file has been processed. Contains a prequalification quote for each unique `external_customer_id` in the uploaded file. |
| [`prequalification_data_file_processed_202510`](/api-reference/webhooks/post-prequalification-data-file-processed-202510) | Lighter version of `prequalification_202505`. Sent when a data file has been processed, but contains only the `prequalification_data_id` — pass it to `GET /prequalification_data` to retrieve the quotes. |

---


## API reference

<!-- llms-section: api-reference/authentication-check/get-authentication-check -->
### GET /authentication_check/
_Tag: Authentication Check_

**Authentication check for partners**

Use this endpoint to check that the authorisation header is being set correctly, and that you can successfully hit the iwoca Lending API.

You should receive a `200: Status OK` response if everything is setup correctly.

<!-- llms-section: api-reference/customer/post-customers -->
### POST /customers/
_Tag: Customer_

**Create an iwoca account for a new customer**

This `POST` request should be used to create an iwoca account for the customer. We'll return a `customer_id` that can be used to identify the customer in all future requests. For more information, see 'Create a customer' in the documentation.

<!-- llms-section: api-reference/application/post-customers-applications -->
### POST /customers/{customer_id}/applications/
_Tag: Application_

**Create user application**

Creates an Application for the customer. If a valid `introducer_id` (a UUID) is provided, the Application will be assigned to that introducer. For more information, see 'Make an application' in the documentation.

<!-- llms-section: api-reference/application/put-customers-applications -->
### PUT /customers/{customer_id}/applications/
_Tag: Application_

**Create or update user application**

Creates or updates an Application for the customer. If an open application exists, it will be updated. Otherwise, a new application will be created.

<!-- llms-section: api-reference/application/get-customers-applications-latest -->
### GET /customers/{customer_id}/applications/latest/
_Tag: Application_

**Get user latest application**

Returns user's latest application information

<!-- llms-section: api-reference/application/patch-customers-applications-latest -->
### PATCH /customers/{customer_id}/applications/latest/
_Tag: Application_

**Update user application**

<!-- llms-section: api-reference/login-link/get-customers-login-link -->
### GET /customers/{customer_id}/login_link/
_Tag: Login Link_

**Get a login link for a customer**

Returns a link which the customer can follow to log in to their iwoca account and progress their application. Before you can generate a login link, you must have created an application for the customer (using the applications endpoint) and the contact entity must be set to customer. For more information, see 'Retrieve a login link' in the documentation. If you are testing your integration in our sandbox and want to follow the login link yourself, we recommend opening it in an 'Incognito' tab as you may already be signed in to our website via our Developer Portal.

<!-- llms-section: api-reference/offers/get-applications-offers -->
### GET /applications/{application_id}/offers/
_Tag: Offers_

**Generate offers**

Generates offers for an application.

<!-- llms-section: api-reference/repayment-schedule/get-offers-repayment-schedule -->
### GET /offers/{offer_id}/repayment_schedule/
_Tag: Repayment Schedule_

**Get repayment schedule for an offer**

Generates a repayment schedule for a given confirmed offer id. Will return a PDF if the Content-Type header is set to application/pdf.

<!-- llms-section: api-reference/documents/get-document-upload -->
### GET /document_upload/{customer_id}/
_Tag: Documents_

**Get list of documents uploaded**

Returns information about supporting documents previously uploaded for this customer. For some types of document this may include the document's acceptance status or certain information extracted from it. For more information, see 'Upload customer documents' in the documentation.

<!-- llms-section: api-reference/documents/post-document-upload -->
### POST /document_upload/{customer_id}/
_Tag: Documents_

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

```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()
```


<!-- llms-section: api-reference/documents/post-bank-statements -->
### POST /bank_statements/{customer_id}/
_Tag: Documents_

**Upload a JSON bank statement**


Upload a business or personal bank statement in JSON format.
If you collect bank statement data for the customer via Open Banking,
you can use this endpoint as instead of uploading their statements as a PDF.

The format of the JSON statement is your choice, but must contain certain information.
Please inform your Partnership Manager of your desired format in advance.

For each statement, the following information is required:
- Account number
- Sort code
- Account holder name
- Currency
- Bank name
The following data points are not required, but are recommended:
- Account type (business or personal)
- Period (date of earliest and latest transaction)

For each transaction in a statement, the following information is required:
- Date
- Reference
- Amount
- Running balance*
*or you can provide a starting balance and closing balance for
the statement instead of a running balance on each transaction.

You can only send one statement at a time, so to send multiple statements you must make multiple requests.


<!-- llms-section: api-reference/select/post-offers-select -->
### POST /offers/{offer_id}/select/
_Tag: Select_

**Select user offer and update entity to contact**

Select an offer that the customer would like to proceed with. For more information, see 'Select an offer' in the documentation.

<!-- llms-section: api-reference/fundings/get-customers-fundings -->
### GET /customers/{customer_id}/fundings/
_Tag: Fundings_

**List funds the customer has taken**

<!-- llms-section: api-reference/funding-account-details/post-funding-account-details -->
### POST /funding_account_details/{customer_id}/
_Tag: Funding Account Details_

**Create funding account details for user**

Creates a record of bank account details for funding a customer. Before you can set their funding details, you must have created an application for the customer (using the applications endpoint).

<!-- llms-section: api-reference/introducers/get-introducers -->
### GET /introducers/
_Tag: Introducers_

**Get introducers associated with a partner**

Returns a list of all introducers, including default one, associated with a partner. The introducer will show up in this list if they have registered under your company at our introducer portal at https://www.iwoca.co.uk/introducer/.

<!-- llms-section: api-reference/introducers/post-introducers -->
### POST /introducers/
_Tag: Introducers_

**Create introducer associated with a partner**

For more information, see 'Create an introducer' in the documentation.

<!-- llms-section: api-reference/developer-portal/post-partner-developer-invite -->
### POST /partner_developer_invite/
_Tag: Developer Portal_

**Invite partner developer**

Grant your developers access to the developer portal. Sends an email to the provided address, containing a link inviting the recipient to create an account under your organisation on the iwoca developer portal, where they can manage your API integration. They will be able to see your API token, so you must not invite untrusted email addresses.

<!-- llms-section: api-reference/prequalification/get-prequalification-data -->
### GET /prequalification_data/
_Tag: Prequalification_

**List prequalification quotes generated for a partner.**

<!-- llms-section: api-reference/prequalification/post-prequalification-data -->
### POST /prequalification_data/
_Tag: Prequalification_

**Pre-qualify customers**

Endpoint for uploading prequalification data as a .csv file

<!-- llms-section: api-reference/webhook-management/get-webhooks-configuration -->
### GET /webhooks/configuration/
_Tag: Webhook Management_

**Get current webhook configuration**

<!-- llms-section: api-reference/webhook-management/put-webhooks-configuration -->
### PUT /webhooks/configuration/
_Tag: Webhook Management_

**Configure webhook url and token**

<!-- llms-section: api-reference/webhook-management/get-webhooks-subscriptions -->
### GET /webhooks/subscriptions/
_Tag: Webhook Management_

**Get webhook subscriptions**

<!-- llms-section: api-reference/webhook-management/post-webhooks-subscriptions -->
### POST /webhooks/subscriptions/
_Tag: Webhook Management_

**Subscribe to webhooks**

<!-- llms-section: api-reference/webhook-management/delete-webhooks-subscriptions -->
### DELETE /webhooks/subscriptions/
_Tag: Webhook Management_

**Unsubscribe from webhooks**

<!-- llms-section: api-reference/webhook-management/get-webhooks-event-types -->
### GET /webhooks/event_types/
_Tag: Webhook Management_

**Get available webhook event types**

<!-- llms-section: api-reference/webhooks/post-application-attributed -->
### Webhook event: application_attributed
_Tag: Webhooks_

**application_attributed**

Sent when an application is created for a customer and attributed to you. This covers applications created:

1. By you, over the API.
2. By your team, via the iwoca Introducer Portal.
3. By iwoca staff, and attributed to you.
4. By the customer themselves — for example through your affiliate signup flow — and attributed to you.

### When an application is moved to another customer

If you submit an application for a customer who already exists in iwoca's system under a different `customer_id`, iwoca staff close your application and create a replacement on the existing customer. Your original application ends up with the status `deferred`.

You will receive this webhook with:

1. `previous_customer_id` and `previous_application_id` — the IDs you originally submitted.
2. `current_customer_id` — the customer the replacement application was created on.
3. `current_application_id` — the replacement application itself.

**Use `current_customer_id` and `current_application_id` from then on.** The previous pair no longer points at a live application.

<!-- llms-section: api-reference/webhooks/post-application-declined -->
### Webhook event: application_declined
_Tag: Webhooks_

**application_declined**

Sent when a customer's application is declined

<!-- llms-section: api-reference/webhooks/post-application-deferred -->
### Webhook event: application_deferred
_Tag: Webhooks_

**application_deferred**

Sent when a customer's application is deferred (closed without reaching an approval or decline decision)

<!-- llms-section: api-reference/webhooks/post-application-offered -->
### Webhook event: application_offered
_Tag: Webhooks_

**application_offered**

Sent when the customer receives a confirmed offer

<!-- llms-section: api-reference/webhooks/post-application-status-changed -->
### Webhook event: application_status_changed
_Tag: Webhooks_

**application_status_changed**

Sent when the status of an application changes

<!-- llms-section: api-reference/webhooks/post-customer-funded -->
### Webhook event: customer_funded
_Tag: Webhooks_

**customer_funded**

Sent when a customer draws down funds from an offer which originated from an application you introduced.
This can happen multiple times. For example, if the customer initially draws down part of the offer amount, and later draws down the rest.

<!-- llms-section: api-reference/webhooks/post-funding-created-202607 -->
### Webhook event: funding_created_202607
_Tag: Webhooks_

**funding_created_202607**

Sent when funds are sent to a customer. If the funding originated from an application, `application_id` is populated.

<!-- llms-section: api-reference/webhooks/post-indicative-offer-created -->
### Webhook event: indicative_offer_created
_Tag: Webhooks_

**indicative_offer_created**

Sent when an indicative offer is created

<!-- llms-section: api-reference/webhooks/post-prequalification-202505 -->
### Webhook event: prequalification_202505
_Tag: Webhooks_

**prequalification_202505**

Sent when a file uploaded to the POST /prequalification_data endpoint has been processed.
Contains a quote for each business in the input file.
You can also retrieve the quotes from the GET /prequalification_data endpoint.
Instead of using this webhook, we recommend listening for the prequalification_data_file_processed_202510
webhook and calling the GET endpoint when you receive it.

<!-- llms-section: api-reference/webhooks/post-prequalification-data-file-processed-202510 -->
### Webhook event: prequalification_data_file_processed_202510
_Tag: Webhooks_

**prequalification_data_file_processed_202510**

Sent when a file that was uploaded to the POST /prequalification_data endpoint has finished processing
and the results are ready to fetch from the GET /prequalification_data endpoint