> ## Documentation Index
> Fetch the complete documentation index at: https://docs.filexpress.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Customers

> Create and query customers

**Required permission:** `customers`

> [!NOTE]
>
> These endpoints use the legacy response format `{ success, data, message }`. See [Response format](https://docs.filexpress.app/en/docs/api/introduccion.md#response-format).

## List a branch's customers

```http theme={null}
GET /customers/branch/{branch_id}
```

Returns all active customers of the branch (not paginated).

## Get customer

```http theme={null}
GET /customers/{id}
```

## Create customer

```http theme={null}
POST /customers
```

```json theme={null}
{
  "customer_name": "Juan Pérez",
  "legal_name": "Juan Antonio Pérez García",
  "register_number": "12345-6",
  "tax_number": "0614-000101-000-0",
  "document_type": "13",
  "document_number": "00000000-0",
  "address": "Col. San Benito, Av. La Revolución #123",
  "country_id": "uuid",
  "state_id": "uuid",
  "city_id": "uuid",
  "activity_id": "uuid",
  "phone": "7777-1234",
  "email": "juan@example.com",
  "business_type": "natural",
  "branch_id": "uuid"
}
```

| Field | Required | Description |
| - | - | - |
| `customer_name` | Yes | Trade name or the person's name. |
| `address` | Yes | Address. |
| `country_id` | Yes | Country. See [Catalogs](https://docs.filexpress.app/en/docs/api/facturacion/catalogos.md). |
| `state_id`, `city_id` | Yes (El Salvador) | Department and municipality from the catalog. Optional if the country is not El Salvador. |
| `state_name`, `city_name` | If the country is not El Salvador | Department or state and city or municipality as free text (max. 120 characters). |
| `phone` | Yes | Phone number. |
| `email` | Yes | Email where the DTEs (electronic tax documents) are sent. |
| `business_type` | Yes | `non-business` (final consumer), `natural` (individual), or `legal` (legal entity). |
| `branch_id` | Yes | Branch the customer belongs to. |
| `legal_name` | No | Legal name. |
| `register_number` | No | NRC (required to issue a CCF). |
| `tax_number` | No | NIT. |
| `document_type` | No | Identity document type according to the Ministry of Finance (Hacienda) catalog (e.g. `13` DUI, `36` NIT). |
| `document_number` | No | Document number. |
| `activity_id` | No | Economic activity (line of business). See `GET /activities`. |

> [!NOTE]
>
> **Location outside El Salvador.** If `country_id` is a country other than El Salvador, `state_id` and `city_id` are optional and `state_name` and `city_name` become required (free text, max. 120 characters each). For El Salvador, `state_id` and `city_id` remain required.

Example of a customer from another country:

```json theme={null}
{
  "customer_name": "Comercial Maya",
  "legal_name": "Comercial Maya, S.A.",
  "address": "6a Avenida 10-25, Zona 1",
  "country_id": "uuid-guatemala",
  "state_name": "Guatemala",
  "city_name": "Ciudad de Guatemala",
  "phone": "+502 2222-3333",
  "email": "compras@comercialmaya.example",
  "business_type": "legal",
  "branch_id": "uuid"
}
```

The response includes the created customer with its `id`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.