# Consumers

List and look up consumers who have interacted with your AVCodex agent.

---

Consumers are the people who interact with your AVCodex agent: techs, programmers, dispatchers, end-clients in a hospitality property, dealer partners. 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 AVCodex 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://app.avcodex.com/api/v1/apps/YOUR_APP_ID/consumers?limit=20&has_email=true" \
  -H "Authorization: Bearer avcodex_YOUR_API_KEY"
```

### Response

```json
{
  "data": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "identifier": "jane@integrator.com",
      "email": "jane@integrator.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://app.avcodex.com/api/v1/apps/YOUR_APP_ID/consumers?limit=25&offset=0" \
  -H "Authorization: Bearer avcodex_YOUR_API_KEY"

# Page 2
curl "https://app.avcodex.com/api/v1/apps/YOUR_APP_ID/consumers?limit=25&offset=25" \
  -H "Authorization: Bearer avcodex_YOUR_API_KEY"
```

### Filtering for leads (consumers with email)

A common use case: sync identified consumers (often dealers or end-clients) to your CRM:

```bash
curl "https://app.avcodex.com/api/v1/apps/YOUR_APP_ID/consumers?has_email=true&created_after=2025-06-01T00:00:00Z" \
  -H "Authorization: Bearer avcodex_YOUR_API_KEY"
```

---

## Get consumer

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

Returns a single consumer by ID.

### Example

```bash
curl "https://app.avcodex.com/api/v1/apps/YOUR_APP_ID/consumers/7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -H "Authorization: Bearer avcodex_YOUR_API_KEY"
```

### Response

```json
{
  "data": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "identifier": "jane@integrator.com",
    "email": "jane@integrator.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"
  }
}
```

*AVCodex · Your AV expertise. Amplified by AI.*