# Create customer

POST `https://app.iteras.dk/api/customers/createcustomer/`

The API key must allow "Change subscriber data".

Creates a customer and returns its ID.

For situations where a customer is actually putting in an order, you can also use the [place order API](/api/docs/server/placeorder.md) instead to get an order registered in Iteras and let that create both the customer and the subscription.

## Parameters

- `id` (string): Optional ID to force the customer to be created with. The ID must be numeric, e.g. `12345`. If a customer with that ID already exists, an error is returned.

  If you instead want the customer updated, use the [update customer](/api/docs/server/updatecustomer.md) endpoint with `create` set.
- `data` (object): The customer attributes, e.g. `{"name": "Customer Name", "email": "john@example.com", "country": "NO"}`. Valid attributes are the built-in ones and the customer fields set up inside Iteras for the account.

  You should usually include a country. Otherwise it may not be possible to invoice the customer because tax rules depend on knowing the country.
- `use_external_lookup` (bool, Defaults to `true`): Passed as a query parameter, e.g. `?use_external_lookup=0`. Set to `false` or 0 if you do not want e-invoice recipients, VAT organization IDs and similar to be validated via external services.
- `exclude_from_webhooks` (bool, Defaults to `false`): Set to `true` to keep every event the request causes from being sent to webhooks, invoice and payment events included, e.g. `"exclude_from_webhooks": true`. The events are still added to the history.

You can set these built-in customer fields in `data`:

- `name`, `company`, `address` and `country`
- `email`
- `billing_name`, `billing_company`, `billing_address`, `billing_country` and `billing_email`
- `password` - you can't retrieve it in clear text afterwards as it goes through a hash
- `created`

Note that a few of these fields have a different name in the [retrieval API](/api/docs/server/retrievingcustomers.md) for backwards compatibility.

You can set any custom customer field, using its field id (the field name with a colon prepended, or its external identifier).

[Log in](/login/?next=/api/docs/server/createcustomer.md), or send your API key as a bearer token, to see the custom customer fields set up for your account.

A yes/no field (type `bool`) is `true` or `false`, and has no value when it isn't set. Set it with `true` or `false`, and clear it with `null`.

A date and time field (type `datetime`) can be set up to follow other fields, so it is set to the time one of them changes. If the same update changes the date and time field itself, that value is kept.

## Examples

Create a customer with an ID chosen by Iteras:

```http
POST /api/customers/createcustomer/ HTTP/1.1
Content-Type: application/json
```

```json
{
  "data": {
    "name": "Customer Name",
    "email": "foo@example.com",
    "country": "DK",
    "password": "secret",
    "created": "2025-11-22T13:56:56",
    "tax_registration_id": "DK35681558",
    ":Custom field": "Example text",
    ":Custom date field": "2026-10-23"
  }
}
```

To create the customer with a specific ID, pass `id`:

```http
POST /api/customers/createcustomer/ HTTP/1.1
Content-Type: application/json
```

```json
{
  "id": "12345",
  "data": {
    "name": "Customer Name",
    "email": "foo@example.com",
    "country": "DK"
  }
}
```

## Return value

On success the endpoint returns the ID of the new customer:

```json
{ "id": "6493264" }
```

## Errors

Invalid requests due to programming error, e.g. invalid JSON, returns 400.

A well-formed operation where a supplied value is invalid is not executed and returns an HTTP 422 error. The response is a JSON object with the errors keyed by the field they concern, e.g. a custom date field:

```json
{
  ":Custom date field": ["Enter a valid date."]
}
```

Errors that are not specific to a field are returned with the empty string as key:

```json
{
  "": ["Customer already exists."]
}
```