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

# Create an iwoca account for a new customer

**POST** `https://www.iwoca.co.uk/api/lending/v2.2/customers/`

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.

## Body
```json
{
  "data": {
    "company": {
      "company_number": "01111112",
      "last_12_months_turnover": {
        "amount": 700000,
        "valid_from": "2016-10-12T14:05:51.666Z"
      },
      "registered_company_name": "COMPANY NAME",
      "trading_from_date": "2010-02-01",
      "type": "limited_liability_company",
      "vat_status": {
        "is_vat_registered": false
      }
    },
    "people": [
      {
        "date_of_birth": "1980-01-01",
        "emails": [
          {
            "email": "enorton1777+test@iwoca.co.uk",
            "type": "primary"
          }
        ],
        "first_name": "Ervin",
        "last_name": "Norton",
        "phones": [
          {
            "number": "07700900370",
            "type": "primary"
          }
        ],
        "privacy_policy": {
          "agreed": true,
          "valid_from": "2016-10-12T14:05:51.666Z"
        },
        "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"
          }
        ],
        "roles": [
          "applicant",
          "shareholder",
          "guarantor",
          "director"
        ],
        "title": "mr",
        "uid": "6cf7319e-f9ec-4038-ba4f-3561a6097484"
      }
    ]
  }
}
```

### Body fields
- `data` (object)
- `data.company` (object)
- `data.company.company_number` (string) — Company number as on Companies House.
- `data.company.has_card_based_transactions` (boolean)
- `data.company.industry` (string) — Recommended format is one of: Agriculture, Forestry & Fishing / Architecture & Engineering / Business Support Services (e.g. recruitment or security) / Car Dealers, Garages & Mechanics / Cleaning, Landscaping & Gardening / Construction (e.g. builders, civil engineer or electrician) / Education & Training / Finance & Insurance / Health & Care (e.g. day-care, doctors or care homes) / Hotels, Restaurants & Pubs / IT & Communications/ Leisure / Other Services (e.g. hairdressers or travel agents) / Manufacturing, Food Processing & Printing / Professional Services (e.g. accounting or consulting) / Property & Real Estate / Publishing, Film & Media Production / Retail (online or offline) / Transport & Logistics (e.g. taxis, couriers or storage) / Wholesale / Other.
- `data.company.last_12_months_profit` (object) — Estimated profit over the last 12 months. For a young business without a full year of trading, the profit to date should be given. A negative value denotes a loss.
- `data.company.last_12_months_profit.amount` (number) — Pre-tax amount submitted by customer in local currency. Note that this differs from monthly_non_business_income which is post-tax.
- `data.company.last_12_months_profit.valid_from` (string) — Datetime when user submitted data, with expected ISO 8601 format.
- `data.company.last_12_months_turnover` (object) — Estimated revenue over the last 12 months. For a young business without a full year of revenue, revenue to date should be given.
- `data.company.last_12_months_turnover.amount` (number) — Amount submitted by customer in local currency or other estimate.
- `data.company.last_12_months_turnover.valid_from` (string) — Datetime when user submitted data, with expected ISO 8601 format.
- `data.company.number_of_employees` (integer)
- `data.company.online_sales_percentage` (integer)
- `data.company.overdraft_status` (object)
- `data.company.overdraft_status.has_overdraft` (boolean) — Specifies whether the user claims their company has a business overdraft.
- `data.company.overdraft_status.total_overdraft_limit` (number) — User declaration for total overdraft limit available to the company. If the company has multiple overdrafts, the sum of the limits should be used.
- `data.company.registered_address` (object)
- `data.company.registered_address.building_number` (string) — Where possible, please put the building number in this field instead of including it in street_line_1
- `data.company.registered_address.country` (string)
- `data.company.registered_address.postcode` (string)
- `data.company.registered_address.street_line_1` (string) — The first line of the company's address. Where possible, please use the separate building_number field instead of including the building number in street_line_1.
- `data.company.registered_address.street_line_2` (string)
- `data.company.registered_address.town` (string)
- `data.company.registered_company_name` (string) — Registered company name for a registered business such as a limited company, as on Companies House.
- `data.company.third_party_providers` (array) — Details of third-party providers used by the business such as Xero, eBay, PayPal or others.
- `data.company.third_party_providers[].name` (string, required)
- `data.company.third_party_providers[].type` (string, required)
- `data.company.trading_address` (object)
- `data.company.trading_address.building_number` (string) — Where possible, please put the building number in this field instead of including it in street_line_1
- `data.company.trading_address.country` (string)
- `data.company.trading_address.postcode` (string)
- `data.company.trading_address.street_line_1` (string) — The first line of the company's address. Where possible, please use the separate building_number field instead of including the building number in street_line_1.
- `data.company.trading_address.street_line_2` (string)
- `data.company.trading_address.town` (string)
- `data.company.trading_from_date` (string) — Date when company started trading, with expected ISO 8601 format.
- `data.company.trading_name` (string)
- `data.company.type` (string)
- `data.company.vat_status` (object) — Information on the company's VAT registration status.
- `data.company.vat_status.is_vat_registered` (boolean)
- `data.company.vat_status.registered_over_3_months` (boolean)
- `data.company.vat_status.vat_number` (string)
- `data.company.website` (string) — Company website.
- `data.correlation_id` (string) — If you have previously pre-qualified this customer using the `/prequalification_data` endpoint, please submit the ID you used when prequalifying the customer in either the `external_customer_id` field (if it is unique), the `correlation_id` field (if it is a UUID) or both, so that iwoca can match up the prequalification result with the customer
- `data.external_customer_id` (string) — If you have a unique identifier for the customer in your system, you can send it in this field.
This field accepts any string, so it does not matter what format you use for customer IDs.
The `external_customer_id` value will be used in the following ways:
1. If you make a second `POST /customers` request with the same `external_customer_id`, you will get a HTTP 409 response and the response body will contain the iwoca `customer_id` of the customer you previously created for this `external_customer_id`. This is one way to avoid submitting the same customer twice if you are unable to track that on your side.
2. If you have previously pre-qualified this customer using the `/prequalification_data` endpoint, please submit the ID you used when prequalifying the customer in either the `external_customer_id` field (if it is unique), the `correlation_id` field (if it is a UUID) or both, so that iwoca can match up the prequalification result with the customer.
3. Some webhooks send the `external_customer_id` in addition to the iwoca `customer_id`, for convenience.
- `data.people` (array) — People associated with the company including the applicant and any other directors, shareholders or loan guarantors you wish to submit. For every customer there should be exactly one person with the role of 'applicant' that is also a 'director' and 'guarantor'.
- `data.people[].date_of_birth` (string) — Date with expected ISO 8601 format.
- `data.people[].emails` (array)
- `data.people[].emails[].email` (string, required) — Contact email address with format user@example.com (ideally not a generic address such as info@...).
- `data.people[].emails[].marketing_opt_in` (object)
- `data.people[].emails[].marketing_opt_in.agreed` (boolean) — Specify if user has opted in to receive marketing emails from iwoca.
- `data.people[].emails[].marketing_opt_in.valid_from` (string) — Datetime when they opted in or out of marketing emails, with expected ISO 8601 format.
- `data.people[].emails[].type` (string)
- `data.people[].first_name` (string) — Middle name is not required.
- `data.people[].how_did_you_find_us` (object)
- `data.people[].how_did_you_find_us.answer` (string) — Enum denoting where the customer heard about us.
- `data.people[].how_did_you_find_us.details` (string) — Additional Details.
- `data.people[].last_name` (string)
- `data.people[].monthly_business_income` (object) — The person's personal income or takings from the business per month.
- `data.people[].monthly_business_income.amount` (number) — Post-tax amount submitted by customer in local currency.
- `data.people[].monthly_business_income.valid_from` (string) — Datetime when user submitted data, with expected ISO 8601 format.
- `data.people[].monthly_non_business_income` (object) — No longer required
- `data.people[].monthly_non_business_income.amount` (number) — Post-tax amount submitted by customer in local currency.
- `data.people[].monthly_non_business_income.valid_from` (string) — Datetime when user submitted data, with expected ISO 8601 format.
- `data.people[].monthly_non_housing_expenses` (object) — No longer needed
- `data.people[].monthly_non_housing_expenses.amount` (number) — Amount submitted by customer in local currency.
- `data.people[].monthly_non_housing_expenses.valid_from` (string) — Datetime when user submitted data, with expected ISO 8601 format.
- `data.people[].monthly_other_household_income` (object) — Total income from other members of the applicant's household such as their wife or husband. Does not include their own income.
- `data.people[].monthly_other_household_income.amount` (number)
- `data.people[].monthly_other_household_income.valid_from` (string) — Datetime when user submitted data, with expected ISO 8601 format.
- `data.people[].number_of_dependents` (object) — Number of people that are financially dependent on the person (such as children or people in their care).
- `data.people[].number_of_dependents.count` (integer)
- `data.people[].number_of_dependents.valid_from` (string) — Datetime when user submitted data, with expected ISO 8601 format.
- `data.people[].phones` (array)
- `data.people[].phones[].number` (string, required) — Quite flexible, can handle with/without country code, e.g. +447778473883 / 07778473883.
- `data.people[].phones[].type` (any) — The applicant must have at least one primary number.
- `data.people[].privacy_policy` (object) — Required to retrieve an automated decision. This field denotes both that the customer agrees to the iwoca privacy policy AND that they have received reasonable, visible notice that iwoca will perform a soft credit check.
- `data.people[].privacy_policy.agreed` (boolean) — Specify whether the user has agreed to the iwoca privacy policy.
- `data.people[].privacy_policy.valid_from` (string) — Datetime when they agreed or disagreed with the iwoca privacy policy, with expected ISO 8601 format.
- `data.people[].residential_addresses` (array)
- `data.people[].residential_addresses[].country` (string)
- `data.people[].residential_addresses[].date_from` (string) — Optionally specify the date when they moved to this address. This date can be an estimate.
- `data.people[].residential_addresses[].equifax_token` (string) — Equifax's PTCABS token. If you have access to this, providing it here could help us retrieve credit information more consistently.
- `data.people[].residential_addresses[].flat_number` (string) — Where possible, please put the flat number in this field instead of including it in street_line_1
- `data.people[].residential_addresses[].house_name` (string) — Where possible, please put the house name in this field instead of including it in street_line_1
- `data.people[].residential_addresses[].house_number` (string) — Where possible, please put the house number in this field instead of including it in street_line_1
- `data.people[].residential_addresses[].monthly_housing_expenses` (object) — No longer needed
- `data.people[].residential_addresses[].monthly_housing_expenses.amount` (number)
- `data.people[].residential_addresses[].monthly_housing_expenses.valid_from` (string) — Datetime when user submitted data, with expected ISO 8601 format.
- `data.people[].residential_addresses[].postcode` (string)
- `data.people[].residential_addresses[].property_value` (object) — No longer needed
- `data.people[].residential_addresses[].property_value.amount` (number) — Amount in local currency.
- `data.people[].residential_addresses[].property_value.valid_from` (string) — Datetime when user submitted data, with expected ISO 8601 format.
- `data.people[].residential_addresses[].residential_status` (string) — No longer needed
- `data.people[].residential_addresses[].street_line_1` (string) — The first line of the customer's address. Usually the street name, but can include the building name or number. Where possible, please use the separate house_number, house_name and/or flat_number fields instead of including the house name/number in street_line_1.
- `data.people[].residential_addresses[].street_line_2` (string) — The second line of the customer's address, between street_line_1 and town.
- `data.people[].residential_addresses[].town` (string)
- `data.people[].roles` (array) — There should only be one applicant but there may be multiple people with the other roles.
- `data.people[].title` (string)
- `data.people[].uid` (string, required) — Unique identifier created and stored by the partner which will allow you to retrieve/update this data in the future.

## Responses
### 201 — Customer UID correctly received.
```json
{
  "data": {
    "customer_id": "00000000-0000-0000-0000-000000000000"
  }
}
```

### 400 — Bad Request
```json
{
  "errors": [
    {
      "code": "string",
      "detail": "string",
      "meta": {},
      "source": {
        "parameter": "string",
        "pointer": "string"
      }
    }
  ]
}
```

### 401 — Unauthorized
```json
{
  "errors": [
    {
      "code": "AuthenticationFailed",
      "detail": "string",
      "meta": {}
    }
  ]
}
```

### 403 — Permission Denied
```json
{
  "errors": [
    {
      "code": "PermissionDenied",
      "detail": "string",
      "meta": {}
    }
  ]
}
```

### 406 — Not Acceptable
```json
{
  "errors": [
    {
      "code": "string",
      "detail": "string",
      "meta": {}
    }
  ]
}
```

### 409 — Conflict
```json
{
  "errors": [
    {
      "code": "string",
      "detail": "string",
      "meta": {}
    }
  ]
}
```

### 500 — Unexpected Error
```json
{
  "errors": [
    {
      "code": "string",
      "detail": "string",
      "meta": {}
    }
  ]
}
```

## Example (curl)
```bash
curl https://www.iwoca.co.uk/api/lending/v2.2/customers/ \
  --request POST \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "data": {
    "company": {
      "company_number": "01111112",
      "last_12_months_turnover": {
        "amount": 700000,
        "valid_from": "2016-10-12T14:05:51.666Z"
      },
      "registered_company_name": "COMPANY NAME",
      "trading_from_date": "2010-02-01",
      "type": "limited_liability_company",
      "vat_status": {
        "is_vat_registered": false
      }
    },
    "people": [
      {
        "date_of_birth": "1980-01-01",
        "emails": [
          {
            "email": "enorton1777+test@iwoca.co.uk",
            "type": "primary"
          }
        ],
        "first_name": "Ervin",
        "last_name": "Norton",
        "phones": [
          {
            "number": "07700900370",
            "type": "primary"
          }
        ],
        "privacy_policy": {
          "agreed": true,
          "valid_from": "2016-10-12T14:05:51.666Z"
        },
        "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"
          }
        ],
        "roles": [
          "applicant",
          "shareholder",
          "guarantor",
          "director"
        ],
        "title": "mr",
        "uid": "6cf7319e-f9ec-4038-ba4f-3561a6097484"
      }
    ]
  }
}'
```