> For the complete documentation index, see [llms.txt](https://docs.cuoral.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cuoral.com/api-reference/customers/contact/get-all-contacts.md).

# Get all contacts

### **Endpoint**

```http
GET /external/v1/customers
```

### **Query Parameters**

| Name         | Type          | Description                     | Default        | Constraints      |
| ------------ | ------------- | ------------------------------- | -------------- | ---------------- |
| `page`       | integer       | Page number                     | `1`            | min: 1           |
| `page_size`  | integer       | Items per page                  | `20`           | min: 1, max: 100 |
| `search`     | string        | Search in name, email, or phone | —              | optional         |
| `source`     | string        | Filter by customer source       | —              | optional         |
| `company_id` | string (UUID) | Filter by company ID            | —              | optional         |
| `is_active`  | boolean       | Filter by active status         | —              | optional         |
| `sort_by`    | string        | Field to sort by                | `time_created` | optional         |
| `sort_order` | string        | Sort order (`asc`, `desc`)      | `desc`         | optional         |

***

### **Response — 200 OK**

```json
{
  "data": [
    {
      "name": "string",
      "email": "user@example.com",
      "whatsapp_number": "string",
      "source": "string",
      "ip": "string",
      "city": "string",
      "country": "string",
      "location": "string",
      "latitude": "string",
      "longitude": "string",
      "is_active": true,
      "id": 0,
      "customer_id": "string",
      "time_created": "2025-11-27T09:32:08.249Z",
      "time_updated": "2025-11-27T09:32:08.249Z",
      "organization_id": 0,
      "company_id": 0,
      "company_name": "string"
    }
  ],
  "total": 0,
  "page": 0,
  "page_size": 0,
  "total_pages": 0,
  "has_next": true,
  "has_previous": true
}
```

***

### **Response Fields**

| Field          | Type    | Description                        |
| -------------- | ------- | ---------------------------------- |
| `data`         | array   | List of customers                  |
| `total`        | integer | Total number of matching customers |
| `page`         | integer | Current page                       |
| `page_size`    | integer | Number of items per page           |
| `total_pages`  | integer | Total number of pages              |
| `has_next`     | boolean | Whether a next page exists         |
| `has_previous` | boolean | Whether a previous page exists     |

#### **Customer Object**

| Field             | Type                  | Description                    |
| ----------------- | --------------------- | ------------------------------ |
| `id`              | integer               | Internal ID                    |
| `customer_id`     | string                | Public customer ID             |
| `name`            | string                | Customer name                  |
| `email`           | string                | Email address                  |
| `whatsapp_number` | string                | WhatsApp number                |
| `source`          | string                | Customer source                |
| `ip`              | string                | IP address                     |
| `city`            | string                | City                           |
| `country`         | string                | Country                        |
| `location`        | string                | Full location                  |
| `latitude`        | string                | Latitude                       |
| `longitude`       | string                | Longitude                      |
| `is_active`       | boolean               | Whether the customer is active |
| `organization_id` | integer               | Organization ID                |
| `company_id`      | integer               | Company ID                     |
| `company_name`    | string                | Company name                   |
| `time_created`    | string (ISO datetime) | Creation timestamp             |
| `time_updated`    | string (ISO datetime) | Update timestamp               |

***

### **Response — 422 Validation Error**

```json
{
  "detail": [
    {
      "loc": ["string", 0],
      "msg": "string",
      "type": "string"
    }
  ]
}
```