---
title: "Customer overview"
icon: "file-lines"
description: "Key requirements and best practices for creating customers"
---

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

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>