List customers — API

GET/api/v1/customers

Scope: customers:read

The customer register. Internal staff notes and AI briefs are never returned. Requires the "customers:read" scope.

Query parameters#

Field	Type	Description
`limit`	integermin 1 · max 100 · default 25	How many results to return, 1-100. Defaults to 25.
`order`	stringdefault "desc"	Sort by creation time: "desc" (newest first, default) or "asc". `"asc""desc"`
`starting_after`	string≥ 1 chars	The next_cursor from a previous page. Opaque — pass it back verbatim.
`email`	string	Exact email match. Emails are unique within an organization.

Example request#

bash

curl -X GET "https://your-site.awrora.app/api/v1/customers" \
  -H "Authorization: Bearer $AWRORA_API_KEY"

Responses#

200A page of customers.
400Invalid request — codes "validation_failed" or, on an endpoint that requires one, "idempotency_key_required".
401Missing, invalid, revoked or expired API key — codes "api_key_missing", "api_key_invalid", "api_key_revoked", "api_key_expired".
403The API app is off, the plan does not include the API, or the key lacks the required scope — codes "app_not_enabled", "plan_upgrade_required", "insufficient_scope" (the last carries "required_scope").
429Rate limit exceeded — code "rate_limited". See the x-ratelimit-* headers.
500Something went wrong on our side — code "internal_error".

Response 200

Field Type Description

datarequired

object[]

The page of results, in the requested order.

Field	Type	Description
`id`required	string	Awrora id (UUID) for the customer record.
`name`required	string	Customer name.
`email`required	string	Customer email. Unique within the organization.
`phone`required	string \| null	Phone number, or null.
`tags`required	string[]	Merchant-defined tags. May be empty.
`email_subscription`required	boolean	True when the customer has opted in to marketing email.
`created_at`required	string	ISO 8601 timestamp with offset.

has_morerequired

boolean

True when more results exist after this page. Fetch them with next_cursor.

next_cursorrequired

string | null

Pass this back as ?starting_after= to fetch the next page. Null when has_more is false. Opaque — do not parse it.

200 response

{
  "data": [
    {
      "id": "res_8f2k3n",
      "name": "string",
      "email": "anna@example.com",
      "phone": "string",
      "tags": [
        "string"
      ],
      "email_subscription": true,
      "created_at": "string"
    }
  ],
  "has_more": true,
  "next_cursor": "string"
}