Audience
Store and retrieve contextual information about users in your audience. This data is embedded into your clone's memory, allowing it to personalize responses based on what you know about each user.
List Users
Retrieve a paginated list of all users in your audience.
Endpoint: GET /v3/users
Query parameters:
limit
integer
No
Page size (1–1000, default 50)
cursor
string
No
Cursor from previous response's next_cursor
active
boolean
No
Filter by active (true) or revoked (false) status
Example request:
curl "https://api.delphi.ai/v3/users?limit=20" \
-H "x-api-key: YOUR_API_KEY"Example response:
{
"users": [
{
"user_id": "u-123",
"email": "fan@example.com",
"name": "Jane Fan",
"phone_number": "+14155552671",
"tags": ["VIP", "newsletter"],
"tier": "PUBLIC",
"active": true,
"date_joined": "2025-06-15T10:30:00.000Z"
},
{
"user_id": "u-456",
"email": "subscriber@example.com",
"name": "Alex Sub",
"phone_number": null,
"tags": [],
"tier": "INTERNAL",
"active": true,
"date_joined": "2025-06-10T08:00:00.000Z"
}
],
"next_cursor": "2025-06-10T08:00:00.000000+00:00|u-456",
"has_more": true
}Response fields:
users
array
List of user objects
next_cursor
string
Pass as cursor to fetch the next page (null when no more results)
has_more
boolean
Whether additional pages exist
User object fields:
user_id
string
UUID of the user
email
string
User's email (may be null)
name
string
Display name (may be null)
phone_number
string
Phone in E.164 format (may be null)
tags
string[]
Tag names applied to this user
tier
string
Access tier: PUBLIC, INTERNAL, or PRIVATE
active
boolean
Whether the user currently has access
date_joined
string
When the user first interacted (ISO 8601)
To page through all results, pass next_cursor from each response as the cursor query parameter until has_more is false. The cursor is opaque — do not parse or construct it manually.
Lookup User
Find a user by email or phone number. Returns the user's ID, email and phone if they exist.
Endpoint: POST /v3/users/lookup
Request body:
email
string
No
Email address to look up
phone_number
string
No
Phone number in E.164 format
Exactly one of email or phone_number must be provided.
Example request (by email):
Example request (by phone):
Example response:
Response fields:
user_id
string
UUID of the matched user
email
string
User's email (may be null)
phone_number
string
User's phone number (may be null)
Create User Info
Add a piece of information about a user from your audience.
Endpoint: POST /v3/users/{user_id}/info
Path parameters:
user_id
string
UUID of the user
Request body:
info
string
Yes
The information text
info_type
string
Yes
Category of the info (see table below)
Info types:
GOAL
Something the user is trying to achieve
PREFERENCES
User preferences or likes/dislikes
INTERESTS
Topics or areas the user is interested in
PERSONAL_INFO
General personal details
EXPERTISE
Skills or areas of knowledge
SITUATION
Current context or circumstances
BELIEF
Values or beliefs
COMMUNICATION_STYLE
How the user prefers to communicate
EMOTIONAL_STATE
Current emotional context
RELATIONSHIP
How the user relates to you or your work
WHY_DELPHI
Why the user interacts with your clone
HOW_DELPHI
How the user uses your clone
JOURNAL
Freeform notes
Example request:
Example response:
Get User Info
Retrieve all stored information for a user who has interacted with your digital mind.
Endpoint: GET /v3/users/{user_id}/info
Path parameters:
user_id
string
UUID of the user
Example request:
Example response:
Items are sorted by newest first.
Update User Info
Update a specific piece of information about a user. You can change the text, the info type, or both.
Endpoint: PATCH /v3/users/{user_id}/info/{info_id}
Path parameters:
user_id
string
UUID of the user
info_id
string
ID of the info item to update
Request body:
info
string
No
Updated information text
info_type
string
No
Updated category (see info types in Create User Info)
At least one of info or info_type must be provided.
Example request:
Example response:
Response fields:
id
string
ID of the info item
text
string
The updated information text
created_at
string
When the info was originally created (ISO 8601)
updated_at
string
When the info was last updated (ISO 8601)
message_id
string
Associated message ID (may be null)
source
string
Origin of the info (API, MESSAGE, etc.)
info_type
string
Category of the info
The created_at timestamp is preserved from the original record. Only updated_at changes on update.
Delete User Info
Remove a specific piece of information about a user.
Endpoint: DELETE /v3/users/{user_id}/info/{info_id}
Path parameters:
user_id
string
UUID of the user
info_id
string
ID of the info item to delete
Example request:
Example response:
Last updated