(GET) Get customers

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

Endpoint

GET /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 /customers

Authentication

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

Query Parameters

ParameterTypeRequiredDescription
id (query)string (ULID)NoFilter by specific customer ID. Returns a single customer if found.
externalId (query)stringNoFilter by external ID. Useful for syncing with external systems.
take (query)numberNoNumber of results to return (default: 50, min: 1, max: 5,000).
skip (query)numberNoNumber of results to skip for pagination (default: 0, min: 0).
sort (query)stringNoSort order by createdAt: "asc" for oldest first, "desc" for newest first (default: "desc").

Request Limits

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

Examples

Request cURL 
curl -X GET "https://api.hoko.to/customers?take=50&sort=desc" \
  -H "Authorization: Bearer <API_KEY>"
Request JavaScript 
const response = await fetch('https://api.hoko.to/customers?take=50&sort=desc', {
	method: 'GET',
	headers: {
		Authorization: 'Bearer <API_KEY>'
	}
});
const customers = await response.json();
Response json 
[
	{
		"id": "<customer_id>",
		"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"
	}
]