# Consumers

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

---

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.

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

## List Consumers

```
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

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