---
**📚 Main Documentation:** [Hoko API Documentation (llms.txt)](https://hoko.to/docs/llms.txt)
This is an individual endpoint documentation file. For the complete API reference, see the main documentation above.
---
# (GET) Get customers
Retrieve customers by ID or external ID. Supports pagination and sorting.
**Category:** Customers
## Endpoint

GET /api/customers

Retrieve customers by id or externalId. Supports pagination with take, skip, and sorting by createdAt.

Use this endpoint to list your customers, verify customer existence, or build customer management interfaces.

**Endpoint**

```text
GET /api/customers
```

## Authentication

Requires authentication with an API key that has the customersRead scope.

## Query Parameters

| Parameter | Type | Required | Location | Description |
|---|---|---|---|---|
| id | string (UUID) | No | query | Filter by specific customer ID. Returns a single customer if found. |
| externalId | string | No | query | Filter by external ID. Useful for syncing with external systems. |
| take | number | No | query | Number of results to return (default: 50, min: 1, max: 10,000). |
| skip | number | No | query | Number of results to skip for pagination (default: 0, min: 0). |
| sort | string | No | query | Sort order by createdAt: "asc" for oldest first, "desc" for newest first (default: "desc"). |

> **Warning: Request Limits**
> The `take` parameter supports values from 1 to 10,000. Requests above 10,000 are rejected.

## Status Codes

### 200

Successfully retrieved customers.

**Request**

```bash
curl -X GET "https://hoko.to/api/customers?take=50&sort=desc" \
  -H "Authorization: Bearer <API_KEY>"
```

**Request**

```javascript
const response = await fetch("https://hoko.to/api/customers?take=50&sort=desc", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <API_KEY>"
  }
});
const customers = await response.json();
```

**Response**

```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "externalId": "customer_123",
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+1234567890",
    "avatar": "https://example.com/avatar.jpg",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
]
```

### 401

Invalid or missing API key.

**Request**

```bash
curl -X GET "https://hoko.to/api/customers" \
  -H "Authorization: Bearer invalid_key"
```

**Request**

```javascript
const response = await fetch("https://hoko.to/api/customers", {
  method: "GET",
  headers: {
    "Authorization": "Bearer invalid_key"
  }
});
```

**Response**

```json
{
  "error": {
    "en": "Invalid API key",
    "ar": "مفتاح API غير صالح"
  }
}
```

### 403

API key does not have the required customersRead scope.

**Request**

```bash
curl -X GET "https://hoko.to/api/customers" \
  -H "Authorization: Bearer <API_KEY>"
```

**Request**

```javascript
const response = await fetch("https://hoko.to/api/customers", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <API_KEY>"
  }
});
```

**Response**

```json
{
  "error": {
    "en": "Missing required scopes",
    "ar": "الصلاحيات المطلوبة مفقودة"
  },
  "missingScopes": ["customersRead"]
}
```

### 429

Rate limit exceeded. Check X-RateLimit-* headers for details.

**Request**

```bash
curl -X GET "https://hoko.to/api/customers" \
  -H "Authorization: Bearer <API_KEY>"
```

**Request**

```javascript
const response = await fetch("https://hoko.to/api/customers", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <API_KEY>"
  }
});
```

**Response**

```json
{
  "error": {
    "en": "Rate limit exceeded",
    "ar": "تم تجاوز حد المعدل"
  },
  "retryAfter": 60
}
```

## Examples

**Request**

```bash
curl -X GET "https://hoko.to/api/customers?take=50&sort=desc" \
  -H "Authorization: Bearer <API_KEY>"
```

**Request**

```javascript
const response = await fetch("https://hoko.to/api/customers?take=50&sort=desc", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <API_KEY>"
  }
});
const customers = await response.json();
```

**Response**

```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "externalId": "customer_123",
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+1234567890",
    "avatar": "https://example.com/avatar.jpg",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
]
```

---

**Back to main documentation:** [Hoko API Documentation (llms.txt)](https://hoko.to/docs/llms.txt)