# Create a customer for a company API Reference

Creates a new customer under this company.

- **`Idempotency-Key`:** it identifies the same operation on the deprecated flat route, so a
  retry that switches route replays instead of creating twice.


## POST /v1/companies/{company_id}/customers

**Create a customer for a company**

Creates a new customer under this company.

- **`Idempotency-Key`:** it identifies the same operation on the deprecated flat route, so a
  retry that switches route replays instead of creating twice.

### Authentication

Accepts any of:

- `ApiKeyAuth` (HTTP bearer, token format `beel_sk_*`)

### Parameters

- **company_id** (required) in path `string`: Unique identifier (UUID) of the company the operation acts on — its identifier, not its NIF. It is the only source of context: the account that owns it is derived from it, and the `BeeL-Active-Company` header plays no part. A company you do not reach answers `403`, and so does a company that does not exist, so the existence of a company in another account is never disclosed.
- **Idempotency-Key** (optional) in header `string`: Idempotency key to prevent duplicates in sensitive operations. - Any unique client-generated string (e.g. an order id). A UUID also works but is not required - Allowed characters: letters, digits, `_` and `-` (max 255 chars) - Retrying with the same key replays the first response when it was a success (2xx) or a server error (5xx): same status and body, plus the header `Idempotency-Replay: true`. After a 5xx, check whether the operation took effect before retrying with a **new** key - A 4xx is not stored: the key is released, so the corrected request can reuse it - Stored responses expire 24 hours after processing The key is scoped per user and environment, and bound to the request body, so retrying after a network timeout replays the stored response instead of repeating the operation. | Status | Code | When | |---|---|---| | `400` | `INVALID_IDEMPOTENCY_KEY` | The key breaks the format rules above. | | `409` | `IDEMPOTENCY_KEY_PROCESSING` | The first request is still in flight. Wait for the `Retry-After` seconds (2) and retry with the same key. | | `409` | `IDEMPOTENCY_KEY_MISMATCH` | The key was already used with a **different** body. Use a new key. |

### Request Body

Required.

**Content `application/json`:**

- **legal_name** (required) `string`: Customer legal name (required). When you also send a Spanish `nif`, how it is used depends on the customer: for an **individual** the AEAT census matches NIF and name together, so a name it does not recognise makes the customer invalid; for a **company** the name is **not verified** and only the CIF decides.
- **trade_name** `string`: Customer trade name. Optional, but **not empty by default**: leave it out on creation and it is filled with `legal_name`, which is what then shows as the recipient's trade name on the invoice PDF. Send it explicitly if the two differ. The default applies **on creation only**. A `PUT` replaces the customer whole, so omitting `trade_name` there **clears** it instead of refilling it from `legal_name`.
- **nif**: Spanish Tax ID (required if id_otro is not provided)
- **alternative_id** `AlternativeIdentifier`: Alternative identifier for customers without Spanish Tax ID. ### VeriFactu rules (checked when you send it, `422` on violation) - `country_code` is required, except for `PASSPORT` (03) and `NOT_REGISTERED` (07), the two types AEAT accepts with `ES`: omitted, `ES` applies. Missing for any other type, the identifier is rejected with `ALTERNATIVE_ID_COUNTRY_REQUIRED`, and `error.details` names the field where it was sent: `alternative_id.country_code` on a customer, `recipient.alternative_id.country_code` on an invoice recipient. Same code in both. - If `country_code = ES`, then `type` **must** be `PASSPORT` (03) or `NOT_REGISTERED` (07) (`ALTERNATIVE_ID_SPAIN_INVALID_TYPE`). - If `type = NOT_REGISTERED` (07), then `country_code` **must** be `ES` (`ALTERNATIVE_ID_REQUIRES_SPAIN`), and `number` **must** be a Spanish DNI or NIE: a Spanish company is always registered (`RECIPIENT_UNREGISTERED_ID_MUST_BE_DNI_OR_NIE`). That DNI or NIE must not be one the AEAT census identifies: if it is, the identifier is rejected with `ALTERNATIVE_ID_ACTUALLY_IN_CENSUS` and has to be sent as `nif`. A customer is checked when it is saved; an invoice recipient, when the invoice is issued with VeriFactu. If the census does not answer, the identifier is not rejected. - If `type = NIF_IVA` (02), `country_code` **must** be an EU member state other than Spain (`ALTERNATIVE_ID_VAT_REQUIRES_EU_COUNTRY`), and `number` **must** have that country's EU VAT number structure as AEAT defines it: the country prefix (`EL` for Greece) followed by the national number, e.g. `FR40303265045`, `DE123456789`, `EL094014201` (`ALTERNATIVE_ID_VAT_INVALID_FORMAT`). Lowercase letters are accepted and stored in uppercase. A customer from outside the EU is identified with another type, such as `OTHER_DOCUMENT` or `COUNTRY_ID`. A `number` that is blank once trimmed is rejected with `ALTERNATIVE_ID_INVALID`. Well-formed is not the same as registered: an EU VAT number that is not in the VIES census is still rejected by VeriFactu after the invoice is issued. An identifier returned in a response is the one stored. A customer saved before a rule existed keeps its identifier and can still be read; issuing an invoice to it with an identifier that breaks these rules is rejected with the same code, before a number is used. ### Matrix of allowed combinations | `type`                 | `country_code = ES` | `country_code ≠ ES` | |------------------------|:-------------------:|:-------------------:| | `NIF_IVA` (02)         | ✗                   | EU member states only | | `PASSPORT` (03)        | ✓                   | ✓                   | | `COUNTRY_ID` (04)      | ✗                   | ✓                   | | `RESIDENCE_CERTIFICATE` (05) | ✗             | ✓                   | | `OTHER_DOCUMENT` (06)  | ✗                   | ✓                   | | `NOT_REGISTERED` (07)  | ✓                   | ✗                   |
- **address** (required) `Address`: Address you send when you create or update a company, a customer or an onboarding. A required field made only of whitespace passes the length checks below but leaves the address without that part, so it is rejected with `422`: `STREET_EMPTY`, `POSTAL_CODE_EMPTY`, `CITY_EMPTY` or `PROVINCE_EMPTY`. Addresses you read back are described by their own schema.
- **phone** `PhoneInput`: A phone number as this API accepts it: 9 to 20 characters, and only digits, spaces, dashes, parentheses and an optional leading `+`. Every request that takes a phone number uses this schema. It is `Phone` plus the rules enforced on input. A value this schema accepts always satisfies `Phone`, so anything you send here is something a response can return.
- **email** `string` (email): Main contact address (minimum valid email is 5 chars, e.g. a@b.co). Invoice emails go here only when the customer has no `billing_emails`.
- **website** `string`: Website URL
- **billing_emails** `array[Email]`: Addresses that receive the customer's invoice emails. When the send request names no `recipients` and the invoice has no `email_config` recipients, invoices go to these addresses, and not to `email`; `email` is used only when `billing_emails` is empty.
- **contact_person** `string`: Contact person name (optional)
- **notes** `string`: Additional notes about the customer (optional)
- **preferred_payment_method** `PaymentInfo`
- **general_discount** `number`: General discount percentage (optional)

**Example `cliente_empresa`** — Spanish company (SL/SA):

```json
{
  "legal_name": "Tech Solutions SL",
  "nif": "B12345674",
  "email": "admin@techsolutions.com",
  "phone": "+34912345678",
  "address": {
    "street": "Calle Mayor",
    "number": "123",
    "floor": "2º B",
    "postal_code": "28013",
    "city": "Madrid",
    "province": "Madrid",
    "country": "España"
  },
  "notes": "Cliente prioritario - Pago puntual"
}
```

**Example `cliente_autonomo`** — Self-employed individual:

```json
{
  "legal_name": "María García López",
  "nif": "12345678Z",
  "email": "maria.garcia@email.com",
  "phone": "+34654321987",
  "address": {
    "street": "Avenida de la Constitución",
    "number": "45",
    "floor": "3º A",
    "postal_code": "41001",
    "city": "Sevilla",
    "province": "Sevilla",
    "country": "España"
  },
  "notes": "Diseñadora gráfica freelance"
}
```

**Example `cliente_extranjero_ue`** — EU Customer with VAT:

```json
{
  "legal_name": "Tech Europe GmbH",
  "alternative_id": {
    "type": "02",
    "number": "DE123456789",
    "country_code": "DE"
  },
  "email": "invoices@techeurope.de",
  "phone": "+49301234567",
  "address": {
    "street": "Hauptstraße",
    "number": "456",
    "postal_code": "10115",
    "city": "Berlin",
    "province": "Berlin",
    "country": "Alemania"
  },
  "notes": "Cliente intracomunitario - Aplicar inversión del sujeto pasivo"
}
```

**Example `cliente_extranjero_usa`** — US Customer with EIN:

```json
{
  "legal_name": "American Tech Corp",
  "alternative_id": {
    "type": "06",
    "number": "12-3456789",
    "country_code": "US"
  },
  "email": "billing@americantech.com",
  "phone": "+14155551234",
  "address": {
    "street": "Main Street",
    "number": "123",
    "floor": "Suite 500",
    "postal_code": "94102",
    "city": "San Francisco",
    "province": "California",
    "country": "Estados Unidos"
  },
  "notes": "Cliente extracomunitario - Factura de exportación"
}
```

**Example `cliente_spanish_business`** — Spanish business customer (ACCIONA):

```json
{
  "legal_name": "ACCIONA SA",
  "nif": "A08001851",
  "address": {
    "street": "Avenida de Europa",
    "number": "18",
    "postal_code": "28108",
    "city": "Alcobendas",
    "province": "Madrid",
    "country": "España",
    "country_code": "ES"
  }
}
```

### Responses

#### 201: Customer created successfully

**Headers:**

- `Location` `string`: URI of the created resource — its canonical GET (`/v1/companies/{company_id}/...` or `/v1/accounts/{account_id}/...`).

**Content `application/json`:**

- **success** (required) `boolean`: No description (example: true)
- **data** (required): The payload. An object for a single resource; an object holding the named collection (and its `pagination`) for a listing. Never a bare array at this level in v1.
- **meta** `ResponseMeta`
- **data** `Customer`

**Example `created_success`** — Customer created (201):

```json
{
  "success": true,
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "legal_name": "Tech Solutions SL",
    "nif": "B12345674",
    "email": "admin@techsolutions.com",
    "phone": "+34912345678",
    "address": {
      "street": "Calle Mayor",
      "number": "123",
      "floor": "2º B",
      "postal_code": "28013",
      "city": "Madrid",
      "province": "Madrid",
      "country": "España"
    },
    "notes": "Cliente prioritario - Pago puntual",
    "active": true,
    "created_at": "2025-01-20T10:00:00Z",
    "updated_at": "2025-01-20T10:00:00Z"
  },
  "meta": {
    "timestamp": "2025-01-20T10:00:00Z",
    "request_id": "c1c1c1c1-0001-4000-a000-000000000001"
  }
}
```

#### 400: `INVALID_JSON_FORMAT` — the body is not valid JSON, or a property has the wrong type or format
(a string where a number is expected, a date that does not parse, a malformed UUID, a boolean
that is not `true`/`false`). The `details` object follows `FieldDeserializationError`:
`field`, `invalid_value` and, where there is one, `expected_format` (or `allowed_values`, for a
boolean). A property the operation does not declare is not a format error: it is ignored.

A value outside an **enum**'s vocabulary is not answered here. The property is a well-formed
string that names nothing the operation knows, so it is judged as content: `422`
(`VALIDATION_ERROR`), with the same `FieldDeserializationError` shape in `details`
(`field`, `invalid_value`, `allowed_values`).


**Content `application/json`:**

- **success** (required) `boolean`: No description (example: false)
- **error** (required) `ErrorDetail`
- **meta** `ResponseMeta`
- **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES")
- **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES")
- **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line")
- **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123")
- **error**: No description

**Example:**

```json
{
  "success": false,
  "error": {
    "code": "INVALID_JSON_FORMAT",
    "message": "The field 'due_date' has an invalid date format: '2026-03-04fds'. Expected format: YYYY-MM-DD.",
    "details": {
      "field": "due_date",
      "invalid_value": "2026-03-04fds",
      "expected_format": "YYYY-MM-DD"
    }
  },
  "meta": {
    "timestamp": "2026-03-05T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
```

#### 401: Missing or invalid authentication. Like every other error, `message`/`detail` is
localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English when the
header is missing or asks for none of those.


**Content `application/json`:**

- **success** (required) `boolean`: No description (example: false)
- **error** (required) `ErrorDetail`
- **meta** `ResponseMeta`
- **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES")
- **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES")
- **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line")
- **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123")

**Example:**

```json
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication is required to access this resource"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
```

#### 403: Your account does not own or manage this company, or does not hold the required
access over it. A NIF that does not exist answers the same way.
That case answers `error.code` `ACTIVE_COMPANY_NOT_ACCESSIBLE`.


**Content `application/json`:**

- **success** (required) `boolean`: No description (example: false)
- **error** (required) `ErrorDetail`
- **meta** `ResponseMeta`
- **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES")
- **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES")
- **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line")
- **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123")

#### 409: `CLIENT_DUPLICATE` — a customer of this company already carries that NIF or alternative identifier. `details` is an empty object; the identifier is not echoed back.

**Content `application/json`:**

- **success** (required) `boolean`: No description (example: false)
- **error** (required) `ErrorDetail`
- **meta** `ResponseMeta`
- **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES")
- **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES")
- **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line")
- **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123")

**Example `conflict`** — Conflict (409):

```json
{
  "success": false,
  "error": {
    "code": "CLIENT_DUPLICATE",
    "message": "A client with this NIF already exists",
    "details": {}
  },
  "meta": {
    "timestamp": "2025-01-20T10:00:00Z",
    "request_id": "d4d4d4d4-0004-4000-a000-000000000004"
  }
}
```

#### 422: The body parses but is not acceptable. `VALIDATION_ERROR` when a property breaks a
constraint (`details` maps each offending property to a message). A Spanish NIF is also
checked against the AEAT census: `NIF_NOT_IN_CENSUS` when the NIF does not exist there or,
for a natural person, `legal_name` does not match the name the census holds (no `details`).
For a company the census identifies the holder by its CIF alone, so the name is not verified.
A NIF that is malformed answers `NIF_INVALID_FORMAT` or `NIF_INVALID_CONTROL_DIGIT`.
Sending both `nif` and `alternative_id` answers `ALTERNATIVE_ID_AND_NIF_EXCLUSIVE`: a
customer is identified by exactly one of them.

Other `error.code` values with this status:

- `ALTERNATIVE_ID_ACTUALLY_IN_CENSUS` — the census identifies that Spanish `NOT_REGISTERED` (07) DNI or NIE with the given `legal_name`; send it in `nif` instead of `alternative_id`.
- `RECIPIENT_UNREGISTERED_ID_MUST_BE_DNI_OR_NIE` — an `alternative_id` of type `NOT_REGISTERED` with country `ES` must be a DNI or NIE; a company (CIF) is always registered, send it as `nif`.


**Content `application/json`:**

- **success** (required) `boolean`: No description (example: false)
- **error** (required) `ErrorDetail`
- **meta** `ResponseMeta`
- **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES")
- **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES")
- **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line")
- **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123")

**Example `validation_error`** — Validation error (422):

```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The provided data is not valid.",
    "details": {
      "nif": "The field 'nif' cannot be empty",
      "lines": "The field 'lines' cannot be empty",
      "recipient.address.postal_code": "Contains invalid characters."
    }
  },
  "meta": {
    "timestamp": "2025-01-20T10:00:00Z",
    "request_id": "c3c3c3c3-0003-4000-a000-000000000003"
  }
}
```

#### 429: Rate limit exceeded. `RATE_LIMIT_EXCEEDED` when the request rate of your credential is
over its limit; `TOO_MANY_REQUESTS` when an email the operation sends is held back because
too many went out to that recipient in a short time. Either way, retry after the
`Retry-After` seconds.

`QUOTA_EXCEEDED` is the other `429`: the operation would go over a quota of your plan
for the current period (issued invoices, for instance). Retrying does not help until the
quota resets or the plan changes. `error.details` carries `feature_code`,
`current_usage`, `quota_limit` and `reset_date`, and `RateLimit-Reset` the seconds until
the reset when it is known.


**Headers:**

- `Retry-After` `integer`: Seconds until the rate limit resets
- `RateLimit-Limit` `integer`: Maximum requests allowed in the window
- `RateLimit-Remaining` `integer`: Remaining requests in the current window
- `RateLimit-Reset` `integer`: Seconds until the current window resets

**Content `application/json`:**

- **success** (required) `boolean`: No description (example: false)
- **error** (required) `ErrorDetail`
- **meta** `ResponseMeta`
- **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES")
- **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES")
- **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line")
- **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123")

**Example:**

```json
{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again in 60 seconds."
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
```

#### 500: Internal server error

**Content `application/json`:**

- **success** (required) `boolean`: No description (example: false)
- **error** (required) `ErrorDetail`
- **meta** `ResponseMeta`
- **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES")
- **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES")
- **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line")
- **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123")

**Example:**

```json
{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
```

#### default: Any status code the operation does not list above. Every operation declares it, so a
generated client always has a branch to fall into and never loses the cause of a failure
it did not anticipate.

This is where the transport-level answers land — `405`, `406`, `415` and `429` — together
with any status a future version of the API starts returning. All of them carry the same
error envelope as the codes listed explicitly, so `error.code` is what tells them apart:
switching on the status code alone is not enough. See «Transport-level errors» in the
API description for when each one is produced.

A `402` carrying `SUBSCRIPTION_REQUIRED` lands here when the account has no active
subscription. `error.details` says why and what to do: `current_status` (absent if it
never had one), `required_permission` and `action`.

A `503` carrying `SERVICE_UNAVAILABLE` lands here too, with a `Retry-After` header: a
dependency of BeeL itself (the database, the email provider) was momentarily
unavailable and nothing was done. Retry after those seconds.

A `502` carrying `EXTERNAL_SERVICE_ERROR` also lands here: an outbound integration the
operation depends on failed or did not answer in time. It is a transient condition — retry
with the same `Idempotency-Key` where the operation accepts one.

One exception to the envelope: a failure of the network edge that never reaches the
application (`502`, `503`, `504`, `524`) is generated by Cloudflare and its body is not
BeeL's — it may not even be JSON. Treat those as "no answer", and retry.


**Content `application/json`:**

- **success** (required) `boolean`: No description (example: false)
- **error** (required) `ErrorDetail`
- **meta** `ResponseMeta`
- **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES")
- **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES")
- **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line")
- **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123")

**Example:**

```json
{
  "success": false,
  "error": {
    "code": "UNSUPPORTED_MEDIA_TYPE",
    "message": "Unsupported media type: text/plain. Supported: application/json"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
```

---

# Related Schema Definitions

## CreateCustomerRequest

- **legal_name** (required) `string`: Customer legal name (required). When you also send a Spanish `nif`, how it is used depends on the customer: for an **individual** the AEAT census matches NIF and name together, so a name it does not recognise makes the customer invalid; for a **company** the name is **not verified** and only the CIF decides.
- **trade_name** `string`: Customer trade name. Optional, but **not empty by default**: leave it out on creation and it is filled with `legal_name`, which is what then shows as the recipient's trade name on the invoice PDF. Send it explicitly if the two differ. The default applies **on creation only**. A `PUT` replaces the customer whole, so omitting `trade_name` there **clears** it instead of refilling it from `legal_name`.
- **nif**: Spanish Tax ID (required if id_otro is not provided)
- **alternative_id** `AlternativeIdentifier`: Alternative identifier for customers without Spanish Tax ID. ### VeriFactu rules (checked when you send it, `422` on violation) - `country_code` is required, except for `PASSPORT` (03) and `NOT_REGISTERED` (07), the two types AEAT accepts with `ES`: omitted, `ES` applies. Missing for any other type, the identifier is rejected with `ALTERNATIVE_ID_COUNTRY_REQUIRED`, and `error.details` names the field where it was sent: `alternative_id.country_code` on a customer, `recipient.alternative_id.country_code` on an invoice recipient. Same code in both. - If `country_code = ES`, then `type` **must** be `PASSPORT` (03) or `NOT_REGISTERED` (07) (`ALTERNATIVE_ID_SPAIN_INVALID_TYPE`). - If `type = NOT_REGISTERED` (07), then `country_code` **must** be `ES` (`ALTERNATIVE_ID_REQUIRES_SPAIN`), and `number` **must** be a Spanish DNI or NIE: a Spanish company is always registered (`RECIPIENT_UNREGISTERED_ID_MUST_BE_DNI_OR_NIE`). That DNI or NIE must not be one the AEAT census identifies: if it is, the identifier is rejected with `ALTERNATIVE_ID_ACTUALLY_IN_CENSUS` and has to be sent as `nif`. A customer is checked when it is saved; an invoice recipient, when the invoice is issued with VeriFactu. If the census does not answer, the identifier is not rejected. - If `type = NIF_IVA` (02), `country_code` **must** be an EU member state other than Spain (`ALTERNATIVE_ID_VAT_REQUIRES_EU_COUNTRY`), and `number` **must** have that country's EU VAT number structure as AEAT defines it: the country prefix (`EL` for Greece) followed by the national number, e.g. `FR40303265045`, `DE123456789`, `EL094014201` (`ALTERNATIVE_ID_VAT_INVALID_FORMAT`). Lowercase letters are accepted and stored in uppercase. A customer from outside the EU is identified with another type, such as `OTHER_DOCUMENT` or `COUNTRY_ID`. A `number` that is blank once trimmed is rejected with `ALTERNATIVE_ID_INVALID`. Well-formed is not the same as registered: an EU VAT number that is not in the VIES census is still rejected by VeriFactu after the invoice is issued. An identifier returned in a response is the one stored. A customer saved before a rule existed keeps its identifier and can still be read; issuing an invoice to it with an identifier that breaks these rules is rejected with the same code, before a number is used. ### Matrix of allowed combinations | `type`                 | `country_code = ES` | `country_code ≠ ES` | |------------------------|:-------------------:|:-------------------:| | `NIF_IVA` (02)         | ✗                   | EU member states only | | `PASSPORT` (03)        | ✓                   | ✓                   | | `COUNTRY_ID` (04)      | ✗                   | ✓                   | | `RESIDENCE_CERTIFICATE` (05) | ✗             | ✓                   | | `OTHER_DOCUMENT` (06)  | ✗                   | ✓                   | | `NOT_REGISTERED` (07)  | ✓                   | ✗                   |
- **address** (required) `Address`: Address you send when you create or update a company, a customer or an onboarding. A required field made only of whitespace passes the length checks below but leaves the address without that part, so it is rejected with `422`: `STREET_EMPTY`, `POSTAL_CODE_EMPTY`, `CITY_EMPTY` or `PROVINCE_EMPTY`. Addresses you read back are described by their own schema.
- **phone** `PhoneInput`: A phone number as this API accepts it: 9 to 20 characters, and only digits, spaces, dashes, parentheses and an optional leading `+`. Every request that takes a phone number uses this schema. It is `Phone` plus the rules enforced on input. A value this schema accepts always satisfies `Phone`, so anything you send here is something a response can return.
- **email** `string` (email): Main contact address (minimum valid email is 5 chars, e.g. a@b.co). Invoice emails go here only when the customer has no `billing_emails`.
- **website** `string`: Website URL
- **billing_emails** `array[Email]`: Addresses that receive the customer's invoice emails. When the send request names no `recipients` and the invoice has no `email_config` recipients, invoices go to these addresses, and not to `email`; `email` is used only when `billing_emails` is empty.
- **contact_person** `string`: Contact person name (optional)
- **notes** `string`: Additional notes about the customer (optional)
- **preferred_payment_method** `PaymentInfo`
- **general_discount** `number`: General discount percentage (optional)

## AlternativeIdentifier

Alternative identifier for customers without Spanish Tax ID.

### VeriFactu rules (checked when you send it, `422` on violation)
- `country_code` is required, except for `PASSPORT` (03) and `NOT_REGISTERED` (07), the two
  types AEAT accepts with `ES`: omitted, `ES` applies. Missing for any other type, the
  identifier is rejected with `ALTERNATIVE_ID_COUNTRY_REQUIRED`, and `error.details` names
  the field where it was sent: `alternative_id.country_code` on a customer,
  `recipient.alternative_id.country_code` on an invoice recipient. Same code in both.
- If `country_code = ES`, then `type` **must** be `PASSPORT` (03) or `NOT_REGISTERED` (07)
  (`ALTERNATIVE_ID_SPAIN_INVALID_TYPE`).
- If `type = NOT_REGISTERED` (07), then `country_code` **must** be `ES`
  (`ALTERNATIVE_ID_REQUIRES_SPAIN`), and `number` **must** be a Spanish DNI or NIE: a
  Spanish company is always registered (`RECIPIENT_UNREGISTERED_ID_MUST_BE_DNI_OR_NIE`).
  That DNI or NIE must not be one the AEAT census identifies: if it is, the identifier is
  rejected with `ALTERNATIVE_ID_ACTUALLY_IN_CENSUS` and has to be sent as `nif`. A customer
  is checked when it is saved; an invoice recipient, when the invoice is issued with
  VeriFactu. If the census does not answer, the identifier is not rejected.
- If `type = NIF_IVA` (02), `country_code` **must** be an EU member state other than Spain
  (`ALTERNATIVE_ID_VAT_REQUIRES_EU_COUNTRY`), and `number` **must** have that country's
  EU VAT number structure as AEAT defines it: the country prefix (`EL` for Greece) followed
  by the national number, e.g. `FR40303265045`, `DE123456789`, `EL094014201`
  (`ALTERNATIVE_ID_VAT_INVALID_FORMAT`). Lowercase letters are accepted and stored in
  uppercase. A customer from outside the EU is identified with another type, such as
  `OTHER_DOCUMENT` or `COUNTRY_ID`.

A `number` that is blank once trimmed is rejected with `ALTERNATIVE_ID_INVALID`.

Well-formed is not the same as registered: an EU VAT number that is not in the VIES
census is still rejected by VeriFactu after the invoice is issued.

An identifier returned in a response is the one stored. A customer saved before a rule
existed keeps its identifier and can still be read; issuing an invoice to it with an
identifier that breaks these rules is rejected with the same code, before a number is used.

### Matrix of allowed combinations
| `type`                 | `country_code = ES` | `country_code ≠ ES` |
|------------------------|:-------------------:|:-------------------:|
| `NIF_IVA` (02)         | ✗                   | EU member states only |
| `PASSPORT` (03)        | ✓                   | ✓                   |
| `COUNTRY_ID` (04)      | ✗                   | ✓                   |
| `RESIDENCE_CERTIFICATE` (05) | ✗             | ✓                   |
| `OTHER_DOCUMENT` (06)  | ✗                   | ✓                   |
| `NOT_REGISTERED` (07)  | ✓                   | ✗                   |

- **type** (required) `string`: Identifier type. Use descriptive names: - **NIF_IVA**: EU VAT number (intra-community) — *only for an EU member state other than Spain, with that country's VAT number structure* - **PASSPORT**: Passport — *allowed for any country* - **COUNTRY_ID**: Country of residence ID — *not allowed when `country_code = ES`* - **RESIDENCE_CERTIFICATE**: Residence certificate — *not allowed when `country_code = ES`* - **OTHER_DOCUMENT**: Other supporting document — *not allowed when `country_code = ES`* - **NOT_REGISTERED**: Not registered in AEAT — *requires `country_code = ES`* **⚠️ DEPRECATED numeric codes** (will be removed in v2): 02, 03, 04, 05, 06, 07 — use the descriptive names above instead. — one of: NIF_IVA, PASSPORT, COUNTRY_ID, RESIDENCE_CERTIFICATE, OTHER_DOCUMENT, NOT_REGISTERED, 02, 03, 04, 05, 06, 07
- **number** (required) `string`: Identifier number. For `NIF_IVA`, the full EU VAT number with its country prefix (e.g. `FR40303265045`); see the VeriFactu rules on the parent schema.
- **country_code** `string`: ISO 3166-1 alpha-2 code of the country that issued the document. Required except for `PASSPORT` and `NOT_REGISTERED`, where omitting it means `ES`. Constrains the allowed `type` values; see the VeriFactu rules on the parent schema.

## Address

Address you send when you create or update a company, a customer or an onboarding.

A required field made only of whitespace passes the length checks below but leaves the
address without that part, so it is rejected with `422`: `STREET_EMPTY`,
`POSTAL_CODE_EMPTY`, `CITY_EMPTY` or `PROVINCE_EMPTY`.

Addresses you read back are described by their own schema.

- **street** (required) `string`: Full address (street, number, floor, etc.) - Latin characters only (example: "Calle Mayor, 123")
- **number** `string`: Street number. Optional: omit it when the address has none, or when `street` already carries the address in full. (example: "123")
- **floor** `string`: Floor or level (example: "2º A")
- **door** `string`: Door or apartment (example: "A")
- **postal_code** (required) `string`: Postal code (5 digits for Spain, free format for other countries) (example: "28001")
- **city** (required) `string`: City or town - Latin characters only (example: "Madrid")
- **province** `string`: Province or state - Latin characters only. Required for an address in Spain (`country_code` `ES`, or no country at all); optional elsewhere, where many addresses have none. A Spanish address without it is rejected with a `422`. (example: "Madrid")
- **country** `string`: Country of the address, as its ISO 3166-1 alpha-2 code (`GB`) or its official name in Spanish, English or Catalan (`Reino Unido`, `United Kingdom`, `Regne Unit`; case and accents are ignored). Anything else, such as `UK`, is rejected with `422 COUNTRY_CODE_REQUIRED`: send `country_code` instead. If it names a different country than `country_code`, `422 COUNTRY_CODE_MISMATCH` (`España` alone yields to a foreign `country_code`: it was the old default). What is stored and returned is always the Spanish name derived from the resulting code, never the text sent. With neither field present, the address is Spanish (`España`). (example: "España")
- **country_code** `string`: ISO 3166-1 alpha-2 country code: the canonical field that decides the country of the address. It must be a real country code (`GB`, not `UK`); otherwise `422 COUNTRY_CODE_REQUIRED`. When it is omitted, the code comes from `country` (see there). With neither field present, the address is stored as `ES`. (example: "ES")

## PhoneInput

A phone number as this API accepts it: 9 to 20 characters, and only digits, spaces,
dashes, parentheses and an optional leading `+`. Every request that takes a phone number
uses this schema.

It is `Phone` plus the rules enforced on input. A value this schema accepts always
satisfies `Phone`, so anything you send here is something a response can return.

Type: `string`

## Email

Email address (minimum valid email is 5 chars, e.g. a@b.co)

Type: `string` (email)

## PaymentInfo

- **method**: Preferred payment method. Omitted, `BANK_TRANSFER` applies. If NONE is selected, no payment information will be shown on the invoice.
- **iban** `IBAN`: IBAN (International Bank Account Number). Required when payment method is BANK_TRANSFER.
- **swift** `SWIFT`: SWIFT/BIC code
- **payment_term_days** `integer`: Payment term in days. When marking an invoice as paid, every field of this object that travels replaces the stored one and every omitted field keeps its current value. (example: 30)

## SuccessResponse

The envelope every successful JSON response of the BeeL. API is wrapped in. There are no
bare resources in v1 and none are planned: the payload always hangs off `data`.

- A **single resource** is an object in `data`.
- A **collection** hangs off a named key inside `data`, together with its `pagination`,
  also inside `data` — `data: {invoices: [...], pagination: {...}}`.
- A collection carries `pagination` unless its operation declares itself a **closed
  catalogue**: a fixed, bounded list with nothing to page through. The declaration is
  explicit in the operation; a missing `pagination` is never something to infer.
- `GET /v1/accounts` pages by cursor (`data: {accounts: [...], next_cursor}`). It is a
  documented variant of pagination, not another envelope.

Putting the array straight into `data` with `pagination` as its sibling is the shape a v2
would adopt; v1 is not being flipped to it.

- **success** (required) `boolean`: No description (example: true)
- **data** (required): The payload. An object for a single resource; an object holding the named collection (and its `pagination`) for a listing. Never a bare array at this level in v1.
- **meta** `ResponseMeta`

## ResponseMeta

- **timestamp** `string` (date-time): No description (example: "2025-01-15T10:30:00Z")
- **request_id** `string`: No description (example: "4bf92f3577b34da6a3ce929d0e0e4736")

## Customer

- **id** (required) `string` (uuid): No description (example: "123e4567-e89b-12d3-a456-426614174000")
- **legal_name** (required) `string`: No description (example: "Empresa Cliente SL")
- **trade_name** `string`: No description (example: "EmpresaCliente")
- **nif** `NIF`: Spanish Tax ID (9 characters, uppercase only). Structural validation: - DNI: 8 digits + 1 letter (e.g., 12345678A) - NIE: X/Y/Z + 7 digits + 1 letter (e.g., X1234567A) - CIF: Organization letter + 7 digits + 1 control digit/letter (e.g., B12345674)
- **address** (required): Customer address as stored. Read shape: records registered before the street number was collected have none, so no field is guaranteed.
- **phone** `Phone`: A phone number, as the record holds it: digits, spaces, dashes, parentheses and an optional leading `+`, up to 20 characters. This is the schema a **response** carries, and the length above is the only rule it states. It deliberately does not repeat the character rule, because a number can reach a record through a path that predates that rule or never passed through this API at all — a payment provider's customer data, a bulk import. Read the field defensively and do not assume it parses. What a **request** has to satisfy is `PhoneInput`, which adds the rules this API enforces on the way in.
- **email** `string` (email): Main contact address (minimum valid email is 5 chars, e.g. a@b.co). Invoice emails go here only when the customer has no `billing_emails`.
- **website** `string`: Website URL
- **billing_emails** `array[Email]`: Addresses that receive the customer's invoice emails. When the send request names no `recipients` and the invoice has no `email_config` recipients, invoices go to these addresses, and not to `email`; `email` is used only when `billing_emails` is empty.
- **contact_person** `string`: No description (example: "María García")
- **notes** `string`: No description
- **preferred_payment_method** `PaymentInfo`
- **general_discount** `number`: No description
- **active** `boolean`: No description
- **created_at** (required) `string` (date-time): No description
- **updated_at** `string` (date-time): No description
- **alternative_id** `AlternativeIdentifier`: Alternative identifier for customers without Spanish Tax ID. ### VeriFactu rules (checked when you send it, `422` on violation) - `country_code` is required, except for `PASSPORT` (03) and `NOT_REGISTERED` (07), the two types AEAT accepts with `ES`: omitted, `ES` applies. Missing for any other type, the identifier is rejected with `ALTERNATIVE_ID_COUNTRY_REQUIRED`, and `error.details` names the field where it was sent: `alternative_id.country_code` on a customer, `recipient.alternative_id.country_code` on an invoice recipient. Same code in both. - If `country_code = ES`, then `type` **must** be `PASSPORT` (03) or `NOT_REGISTERED` (07) (`ALTERNATIVE_ID_SPAIN_INVALID_TYPE`). - If `type = NOT_REGISTERED` (07), then `country_code` **must** be `ES` (`ALTERNATIVE_ID_REQUIRES_SPAIN`), and `number` **must** be a Spanish DNI or NIE: a Spanish company is always registered (`RECIPIENT_UNREGISTERED_ID_MUST_BE_DNI_OR_NIE`). That DNI or NIE must not be one the AEAT census identifies: if it is, the identifier is rejected with `ALTERNATIVE_ID_ACTUALLY_IN_CENSUS` and has to be sent as `nif`. A customer is checked when it is saved; an invoice recipient, when the invoice is issued with VeriFactu. If the census does not answer, the identifier is not rejected. - If `type = NIF_IVA` (02), `country_code` **must** be an EU member state other than Spain (`ALTERNATIVE_ID_VAT_REQUIRES_EU_COUNTRY`), and `number` **must** have that country's EU VAT number structure as AEAT defines it: the country prefix (`EL` for Greece) followed by the national number, e.g. `FR40303265045`, `DE123456789`, `EL094014201` (`ALTERNATIVE_ID_VAT_INVALID_FORMAT`). Lowercase letters are accepted and stored in uppercase. A customer from outside the EU is identified with another type, such as `OTHER_DOCUMENT` or `COUNTRY_ID`. A `number` that is blank once trimmed is rejected with `ALTERNATIVE_ID_INVALID`. Well-formed is not the same as registered: an EU VAT number that is not in the VIES census is still rejected by VeriFactu after the invoice is issued. An identifier returned in a response is the one stored. A customer saved before a rule existed keeps its identifier and can still be read; issuing an invoice to it with an identifier that breaks these rules is rejected with the same code, before a number is used. ### Matrix of allowed combinations | `type`                 | `country_code = ES` | `country_code ≠ ES` | |------------------------|:-------------------:|:-------------------:| | `NIF_IVA` (02)         | ✗                   | EU member states only | | `PASSPORT` (03)        | ✓                   | ✓                   | | `COUNTRY_ID` (04)      | ✗                   | ✓                   | | `RESIDENCE_CERTIFICATE` (05) | ✗             | ✓                   | | `OTHER_DOCUMENT` (06)  | ✗                   | ✓                   | | `NOT_REGISTERED` (07)  | ✓                   | ✗                   |

## ErrorResponse

Error response shared by all BeeL. APIs.

The payload carries **two contracts at once** (additive, non-breaking):

- **Legacy** (`success`, `error.{code,message,details}`, `meta`) — kept
  intact for existing consumers.
- **RFC 9457** (`type`, `title`, `detail`, `instance`) — new fields
  for integrators following Problem Details for HTTP APIs. The
  `type` URI is the stable, shareable link to the error's
  documentation page (e.g. `https://docs.beel.es/errors/{code}`).

Future migration: the legacy fields will be deprecated via
`Deprecation`/`Sunset` headers after a sufficient adoption window,
and the response Content-Type will move to
`application/problem+json`.

- **success** (required) `boolean`: No description (example: false)
- **error** (required) `ErrorDetail`
- **meta** `ResponseMeta`
- **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES")
- **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES")
- **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line")
- **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123")

## ErrorDetail

- **code** (required) `string`: No description (example: "VALIDATION_ERROR")
- **message** (required) `string`: No description (example: "The provided data is not valid")
- **details** `object`: No description (example: {"field":"specific error message"})

## IBAN

IBAN (International Bank Account Number).
Required when payment method is BANK_TRANSFER.

Type: `string`

## SWIFT

SWIFT/BIC code

Type: `string`

## NIF

Spanish Tax ID (9 characters, uppercase only). Structural validation:
- DNI: 8 digits + 1 letter (e.g., 12345678A)
- NIE: X/Y/Z + 7 digits + 1 letter (e.g., X1234567A)
- CIF: Organization letter + 7 digits + 1 control digit/letter (e.g., B12345674)

Type: `string`

## Phone

A phone number, as the record holds it: digits, spaces, dashes, parentheses and an
optional leading `+`, up to 20 characters.

This is the schema a **response** carries, and the length above is the only rule it
states. It deliberately does not repeat the character rule, because a number can reach a
record through a path that predates that rule or never passed through this API at all —
a payment provider's customer data, a bulk import. Read the field defensively and do not
assume it parses.

What a **request** has to satisfy is `PhoneInput`, which adds the rules this API enforces
on the way in.

Type: `string`


---

Full OpenAPI spec: https://docs.beel.es/api/openapi