---
title: "UX guidance"
description: "Screen-by-screen guidance for building your customer-facing lending journey"
---

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

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>