Consumers

List and look up consumers who have interacted with your Chipp app

1 min read

# api # builder-api # rest # consumers # users # leads # contacts

Consumers are the people who interact with your Chipp app. Each consumer has a unique ID and may have an email, name, or other identifying information depending on how they authenticated.

ℹ️

Sensitive authentication fields (password hashes, tokens) are never exposed through the Builder API.

List Consumers

plaintext

GET /api/v1/apps/{appId}/consumers

Returns a paginated list of consumers. Uses offset-based pagination.

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	25	Results per page (1-100)
`offset`	integer	0	Number of results to skip
`search`	string	—	Search by name, email, or identifier
`has_email`	string	—	Filter by email presence: `"true"` or `"false"`
`created_after`	ISO 8601	—	Consumers created after this date
`created_before`	ISO 8601	—	Consumers created before this date

Example

bash

curl "https://build.chipp.ai/api/v1/apps/YOUR_APP_ID/consumers?limit=20&has_email=true" \
  -H "Authorization: Bearer chipp_YOUR_API_KEY"

Response

json

{
  "data": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "identifier": "jane@example.com",
      "email": "jane@example.com",
      "name": "Jane Smith",
      "picture_url": null,
      "email_verified": true,
      "credits": 100,
      "subscription_active": false,
      "mode": "default",
      "is_anonymous": false,
      "created_at": "2025-05-20T10:00:00Z",
      "updated_at": "2025-06-15T10:00:00Z"
    },
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "identifier": "anon_x7k2m",
      "email": null,
      "name": null,
      "picture_url": null,
      "email_verified": false,
      "credits": 0,
      "subscription_active": false,
      "mode": "default",
      "is_anonymous": true,
      "created_at": "2025-06-10T15:30:00Z",
      "updated_at": "2025-06-10T15:30:00Z"
    }
  ],
  "pagination": {
    "has_more": true,
    "total": 142,
    "limit": 20,
    "offset": 0
  }
}

Response Fields

Field	Type	Description
`id`	UUID	Unique consumer identifier
`identifier`	string	Human-readable identifier (email or generated ID)
`email`	string or null	Consumer’s email address, if provided
`name`	string or null	Consumer’s display name, if provided
`picture_url`	string or null	URL to the consumer’s profile picture
`email_verified`	boolean	Whether the consumer’s email has been verified
`credits`	integer	Consumer’s current credit balance
`subscription_active`	boolean	Whether the consumer has an active subscription
`mode`	string	Consumer’s current mode
`is_anonymous`	boolean	Whether the consumer is anonymous
`created_at`	ISO 8601	When the consumer was first seen
`updated_at`	ISO 8601	When the consumer was last updated

Paginating with Offset

bash

# Page 1
curl "https://build.chipp.ai/api/v1/apps/YOUR_APP_ID/consumers?limit=25&offset=0" \
  -H "Authorization: Bearer chipp_YOUR_API_KEY"

# Page 2
curl "https://build.chipp.ai/api/v1/apps/YOUR_APP_ID/consumers?limit=25&offset=25" \
  -H "Authorization: Bearer chipp_YOUR_API_KEY"

Filtering for Leads (Consumers with Email)

A common use case is syncing identified consumers to your CRM:

bash

curl "https://build.chipp.ai/api/v1/apps/YOUR_APP_ID/consumers?has_email=true&created_after=2025-06-01T00:00:00Z" \
  -H "Authorization: Bearer chipp_YOUR_API_KEY"

Get Consumer

plaintext

GET /api/v1/apps/{appId}/consumers/{consumerId}

Returns a single consumer by ID.

Example

bash

curl "https://build.chipp.ai/api/v1/apps/YOUR_APP_ID/consumers/7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -H "Authorization: Bearer chipp_YOUR_API_KEY"

Response

json

{
  "data": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "identifier": "jane@example.com",
    "email": "jane@example.com",
    "name": "Jane Smith",
    "picture_url": null,
    "email_verified": true,
    "credits": 100,
    "subscription_active": false,
    "mode": "default",
    "is_anonymous": false,
    "created_at": "2025-05-20T10:00:00Z",
    "updated_at": "2025-06-15T10:00:00Z",
    "session_count": 8
  }
}

The single-consumer response includes all fields from the list response, plus session_count (integer) — the total number of chat sessions for this consumer.

Error: Consumer Not Found (404)

json

{
  "error": {
    "code": "not_found",
    "message": "Consumer not found"
  }
}