# Import customers from a Holded contacts export (deprecated) API Reference

Parses a contacts export from Holded (`.xlsx`) as Holded produces it, maps each contact
to a customer and returns every row with its validation outcome, as the CSV import does.

- **Deprecated:** use `POST /v1/companies/{company_id}/customers/imports` with
  `source: holded`, which imports the same file. It answers `201` and requires the
  `Idempotency-Key` header.
- **Mapping:** the contact name becomes `legal_name`, the Holded ID becomes the tax
  identifier, and mobile takes precedence over landline for the phone.
- **File:** limited to 10 MB and 5,000 contacts. A file over either limit is rejected as a
  whole with `400` (`CSV_FILE_TOO_LARGE` or `TOO_MANY_RECORDS`) and nothing is imported.
- **`preview`:** at its default `true` nothing is persisted; `false` also imports the
  mapped customers.

**Retires on 9 December 2026.** See the [migration guide](https://docs.beel.es/changelog/resources-under-the-nif) for what moved where and what changes when you switch.


## POST /v1/customers/import-holded-contacts

**Import customers from a Holded contacts export**

Parses a contacts export from Holded (`.xlsx`) as Holded produces it, maps each contact
to a customer and returns every row with its validation outcome, as the CSV import does.

- **Deprecated:** use `POST /v1/companies/{company_id}/customers/imports` with
  `source: holded`, which imports the same file. It answers `201` and requires the
  `Idempotency-Key` header.
- **Mapping:** the contact name becomes `legal_name`, the Holded ID becomes the tax
  identifier, and mobile takes precedence over landline for the phone.
- **File:** limited to 10 MB and 5,000 contacts. A file over either limit is rejected as a
  whole with `400` (`CSV_FILE_TOO_LARGE` or `TOO_MANY_RECORDS`) and nothing is imported.
- **`preview`:** at its default `true` nothing is persisted; `false` also imports the
  mapped customers.

**Retires on 9 December 2026.** See the [migration guide](https://docs.beel.es/changelog/resources-under-the-nif) for what moved where and what changes when you switch.

**Deprecated.**

### Authentication

Accepts any of:

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

### Parameters

- **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 `multipart/form-data`:**

- **file** (required) `string` (binary): Excel file (.xlsx) of contacts exported from Holded
- **preview** `boolean`: If true: parsing and mapping only without importing to DB. If false: parsing + mapping + actual import.

### Responses

#### 200: Holded Excel processing completed with unified format.
Returns parsed, validated and mapped customers using the same format as CSV import.


**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** `CustomerValidationUnifiedResult`: Unified format for customer validation results. Used for bulk validation (JSON), CSV import and Holded Excel import. One shape for every bulk and import outcome, so a caller reads a batch creation, a CSV import and a Holded import the same way.

#### 400: Bad request. From a dashboard session, a `BeeL-Environment` header whose value is not a
known environment answers `ENVIRONMENT_HEADER_INVALID`, with the header named in
`error.details` (`{"BeeL-Environment": "invalid"}`); it is never read as production.

`BUSINESS_RULE_VIOLATION` is the generic answer to an operation the resource does not
admit in its current state when that state has no code of its own. It carries no
`details`; read the resource again before retrying.


**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": "BAD_REQUEST",
    "message": "Invalid request"
  },
  "meta": {
    "timestamp": "2025-01-15T10: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: Authenticated but not allowed. Fourteen causes shared by every operation, told apart by
`error.code`; an operation that adds a cause of its own names it in its `403`. You can
branch on them exhaustively.

- `INSUFFICIENT_SCOPE` — the credential lacks a scope the operation requires;
  `error.details.missing_scopes` names them as a single comma-separated string (for
  example `"invoices:write,customers:read"`), not as an array; `required_scopes` has the
  same shape and lists every scope the operation needs. Retrying will not help: mint a key
  that holds them.
- `COMPANY_READ_ONLY` — the scope is there, but your access level over that NIF only
  lets you read it.
- `ACCOUNT_MANAGEMENT_FORBIDDEN` — the scope is there, but your role over the account,
  or the management relationship you hold over it, does not cover this operation.
- `ACCOUNT_NOT_ACCESSIBLE` — the account is not yours to reach, which is also the answer
  when it does not exist, so existence is never disclosed.
- `ACTIVE_COMPANY_NOT_ACCESSIBLE` — the same, for a NIF: the company in the path, or the
  one named by `BeeL-Active-Company`, is not one this credential may reach — and again,
  this is also the answer when it does not exist.
- `COMPANY_ACCESS_REVOKED` — your access to the NIF was withdrawn while the request was
  already in flight, so the write was rejected and nothing was recorded. Retrying will
  not help until the access is granted again.
- `LIVE_CREDENTIAL_REQUIRED` — the operation changes the real account and the call came
  from a test API key (`beel_sk_test_…`). Use your live key or the dashboard.
- `FEATURE_NOT_AVAILABLE` — your subscription does not include the entitlement the
  operation needs; `error.details.feature_code` names it. This gate runs **before** the
  scope gate, so for such an operation you never see `INSUFFICIENT_SCOPE` first.
- `NO_ACTIVE_ACCOUNT` — the credential does not resolve to an account, so no scope can be
  evaluated against one. Fail-closed, not a permission that can be granted to you.
- `OPERATION_REQUIRES_SESSION` — the operation is available only from the web session; no
  API key and no OAuth2 token can perform it, whatever scopes it holds.
- `OPERATION_REQUIRES_API_KEY` — the reverse: the operation needs a scope that only an API
  key can hold (such as `accounts:write`), so a dashboard session never satisfies it.
- `API_KEY_LIVE_NOT_AVAILABLE` — the call came with a live API key (`beel_sk_live_…`) and
  the account has no Live mode yet. It is never degraded to Test: use your test key, or
  activate Live first.
- `ACCOUNT_REQUIRES_FOCUS_SWITCH` — dashboard session only: you are a member of the account
  in the path, but it is not the account in focus. Switch focus to it and retry.
- `REQUEST_BLOCKED` — the edge security filter stopped the request before the API saw its
  body, usually because a text field carries something that looks like markup or a
  script (HTML tags, `<script>`). Review the body 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": "FORBIDDEN",
    "message": "You do not have permission to access this resource"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
```

#### 413: The uploaded file is over 12 MB (`FILE_TOO_LARGE`) and is rejected before it is read; a
file over its own 10 MB limit answers `400` instead.


**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")

#### 422: `VALIDATION_ERROR` — the body parses but a value is not acceptable. `details` is a flat map from
the offending property's name (in the contract's `snake_case`, nested paths joined with a dot,
e.g. `recipient.address.postal_code`) to a message describing what is wrong with it, one entry
per property. When the rejected value is one outside an enum's vocabulary, `details` instead
follows `FieldDeserializationError` (`field`, `invalid_value`, `allowed_values`).

Two more codes share this status for a value that passes the contract but does not fit
where it is stored: `VALUE_TOO_LONG` (a text longer than its column holds) and
`VALUE_OUT_OF_RANGE` (a number outside what its column holds). Nothing was written.


**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": "VALIDATION_ERROR",
    "message": "The provided data is not valid.",
    "details": {
      "legal_name": "The field 'legal_name' cannot be empty",
      "recipient.address.postal_code": "Contains invalid characters."
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
```

#### 429: Rate limit exceeded

**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")

#### 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

## 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")

## CustomerValidationUnifiedResult

Unified format for customer validation results.
Used for bulk validation (JSON), CSV import and Holded Excel import.

One shape for every bulk and import outcome, so a caller reads a batch creation, a CSV
import and a Holded import the same way.

- **metadata** (required) `CustomerValidationMetadata`: Metadata about the validation operation. Compatible with bulk JSON, CSV import and Holded Excel import.
- **customers_validation** (required) `array[CustomerValidationItem]`: List of processed customers with their validation status
- **statistics** (required) `CustomerValidationStatistics`: Aggregated validation statistics. Compatible with all source types (bulk JSON, CSV and Holded Excel). Every field except `imported` counts rows of the submitted file/payload, classified by outcome: each row falls into exactly one of `valid`, `with_warnings`, `with_errors`, `duplicates` and `invalid_nifs`, so those five add up to `total_processed`. `imported` is the only field that counts writes to the database, so it is the field to read to know whether an import worked.

## 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"})

## CustomerValidationMetadata

Metadata about the validation operation.
Compatible with bulk JSON, CSV import and Holded Excel import.

- **total_customers** (required) `integer`: Total number of customers submitted (example: 10)
- **is_dry_run** (required) `boolean`: Whether it was validation (true) or import (false) (example: true)
- **processing_time_ms** (required) `integer`: Processing time in milliseconds (example: 450)
- **source_type** (required) `string`: Data source type: - BULK_JSON: Data sent as JSON to bulk endpoint - CSV_IMPORT: Data parsed from CSV file - HOLDED_EXCEL: Data parsed from Holded Excel file — one of: BULK_JSON, CSV_IMPORT, HOLDED_EXCEL (example: "CSV_IMPORT")
- **filename** `string`: File name (CSV or Excel depending on source_type) (example: "clientes_enero.csv")
- **file_size_bytes** `integer`: File size in bytes (example: 1048576)
- **total_rows** `integer`: Total file rows excluding headers (example: 250)

## CustomerValidationItem

Individual customer validation result.
Works for bulk JSON, CSV import and Holded Excel import.

- **index** (required) `integer`: Customer index in the submitted list (0-based for bulk, 1-based for files). For CSV/Excel, represents the row number in the file. (example: 0)
- **customer**: **Echo of what was submitted**, parsed and validated. Absent when the row could not be parsed at all. It is deliberately NOT a `Customer`: the same operation also runs as a rehearsal (`dry_run=true`), where nothing is written and there is no `id` nor `created_at` to report. Typing it as `Customer` — which requires both — made the contract impossible to honour in one of its two modes, and it was in fact honoured in neither. **The identifier of what was created travels in `customer_id`**, at row level, and only when the row actually created something.
- **customer_id**: Identifier of the customer this row created. **Present only when the row actually created something**: absent in a rehearsal (`dry_run=true`), absent on a row that was rejected, and absent on a batch that was rejected as a whole. After a `201`, every row carries it, and `GET /v1/companies/{company_id}/customers/{customer_id}` answers `200`.
- **status** (required) `string`: Customer validation status: - VALID: Completely valid customer - WARNING: Valid customer but with non-critical warnings - ERROR: Invalid customer, cannot be processed - DUPLICATE: Duplicate customer (in batch/CSV or database) - NIF_INVALID: the identifier does not match the AEAT census: a NIF the census does not identify, or a type 07 (not registered) whose DNI or NIE the census does identify — one of: VALID, WARNING, ERROR, DUPLICATE, NIF_INVALID (example: "VALID")
- **errors** (required) `array[CustomerValidationError]`: List of errors found (block import)
- **warnings** (required) `array[CustomerValidationWarning]`: List of warnings (do not block import)
- **row_number** `integer`: Row number in the file (CSV or Excel depending on source_type) (example: 15)

## CustomerValidationStatistics

Aggregated validation statistics.
Compatible with all source types (bulk JSON, CSV and Holded Excel).

Every field except `imported` counts rows of the submitted file/payload, classified by
outcome: each row falls into exactly one of `valid`, `with_warnings`, `with_errors`,
`duplicates` and `invalid_nifs`, so those five add up to `total_processed`.
`imported` is the only field that counts writes to the database, so it is the field to
read to know whether an import worked.

- **total_processed** (required) `integer`: Total customers processed (example: 10)
- **valid** (required) `integer`: Completely valid customers (no warnings or errors) (example: 6)
- **with_warnings** (required) `integer`: Valid customers but with warnings (example: 2)
- **with_errors** (required) `integer`: Customers with errors (not importable) (example: 2)
- **duplicates** (required) `integer`: Customers with duplicate NIFs (example: 1)
- **invalid_nifs** (required) `integer`: Customers with NIFs not valid in AEAT (example: 1)
- **imported** (required) `integer`: Customers actually created in the database by this request. Always `0` when `is_dry_run=true` (a preview writes nothing). On a real import it is the number of rows that reached the database — normally `importable`, and lower when a row was rejected on write (it is then reported under `duplicates` or `with_errors`). (example: 8)
- **success_rate** (required) `number` (float): Success rate (valid + with_warnings) / total_processed (example: 0.8)
- **importable** `integer`: Total customers that can be imported (valid + with_warnings) (example: 8)
- **not_importable** `integer`: Total customers that CANNOT be imported (with_errors + duplicates + invalid_nifs) (example: 2)

## CustomerValidationError

Field-specific validation error

- **field** (required) `string`: Field that failed validation (example: "nif")
- **value** (required) `string`: Value that caused the error (example: "12345678X")
- **message** (required) `string`: Human-readable text, already resolved to the language of the request. It is never a raw i18n key — a key neither reads nor is stable against a rename. (example: "NIF not found in AEAT census")
- **code** (required) `string`: Stable, uppercase, never translated — this is what an integration compares. Present on every row error. When the same failure exists on the single `POST /v1/companies/{company_id}/customers`, it is the SAME code, so the single and the bulk route never disagree about the same customer (`CLIENT_DUPLICATE`, `NIF_NOT_IN_CENSUS`, `NIF_REVOCADO`, `CUSTOMER_IDENTIFIER_REQUIRED`, `NIF_INVALID_FORMAT`, …). Failures that only an import has carry their own: `CUSTOMER_DUPLICATED_IN_BATCH`, `CUSTOMER_DUPLICATED_IN_FILE`, `CUSTOMER_FIELD_REQUIRED`, `CUSTOMER_FIELD_INVALID_FORMAT`, `CUSTOMER_FIELD_INVALID_CHARACTERS`, `CUSTOMER_ADDRESS_INVALID`, `CUSTOMER_NOT_SAVED`, `CUSTOMER_ROW_NOT_PROCESSED`. An address field of a file row that the JSON contract would have capped carries the address code, blank after trimming or over its length: `STREET_EMPTY`, `POSTAL_CODE_EMPTY`, `CITY_EMPTY`, `PROVINCE_EMPTY`, `STREET_MAX_LENGTH` (255), `NUMBER_MAX_LENGTH` (20), `CITY_MAX_LENGTH` (100), `PROVINCE_MAX_LENGTH` (100). A reason with no specific code yet answers `VALIDATION_ERROR`. (example: "CUSTOMER_IDENTIFIER_REQUIRED")

## CustomerValidationWarning

Validation warning (does not block import)

- **field** (required) `string`: Field with warning (example: "email")
- **message** (required) `string`: Warning message (example: "Email not provided, NIF will be used for invoicing")


---

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