Consumers — AVCodex Docs

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#

code

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#

code

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.*