(GET) Get customers

Retrieve customers by ID or external ID. Supports pagination and sorting.

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

Request Limits

The `take` parameter supports values from 1 to 10,000. Requests above 10,000 are rejected.

Examples

Request cURL

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"
  }
]