> For the complete documentation index, see [llms.txt](https://docs.delphi.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.delphi.ai/advanced/actions/api-immortal-only/audience.md).

# Audience

### List Users

Retrieve a paginated list of all users in your audience.

**Endpoint:** `GET /v3/users`

**Query parameters:**

| Parameter | Type    | Required | Description                                           |
| --------- | ------- | -------- | ----------------------------------------------------- |
| `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:**

```bash
curl "https://api.delphi.ai/v3/users?limit=20" \
  -H "x-api-key: YOUR_API_KEY"
```

**Example response:**

```json
{
  "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:**

| Field         | Type    | Description                                                           |
| ------------- | ------- | --------------------------------------------------------------------- |
| `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:**

| Field          | Type      | Description                                     |
| -------------- | --------- | ----------------------------------------------- |
| `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:**

| Field          | Type   | Required | Description                  |
| -------------- | ------ | -------- | ---------------------------- |
| `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):**

```bash
curl -X POST "https://api.delphi.ai/v3/users/lookup" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "fan@example.com"}'
```

**Example request (by phone):**

```bash
curl -X POST "https://api.delphi.ai/v3/users/lookup" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "+14155552671"}'
```

**Example response:**

```json
{
  "user_id": "u-123",
  "email": "fan@example.com",
  "phone_number": "+14155552671"
}
```

**Response fields:**

| Field          | Type   | Description                         |
| -------------- | ------ | ----------------------------------- |
| `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:**

| Field     | Type   | Description      |
| --------- | ------ | ---------------- |
| `user_id` | string | UUID of the user |

**Request body:**

| Field       | Type   | Required | Description                            |
| ----------- | ------ | -------- | -------------------------------------- |
| `info`      | string | Yes      | The information text                   |
| `info_type` | string | Yes      | Category of the info (see table below) |

**Info types:**

| Value                 | Description                               |
| --------------------- | ----------------------------------------- |
| `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:**

```bash
curl -X POST "https://api.delphi.ai/v3/users/u-123/info" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "info": "Wants to improve their public speaking skills",
    "info_type": "GOAL"
  }'
```

**Example response:**

```json
{
  "id": "info-001",
  "text": "Wants to improve their public speaking skills",
  "created_at": "2025-06-15T10:30:00.000Z",
  "updated_at": "2025-06-15T10:30:00.000Z",
  "message_id": null,
  "source": "API",
  "info_type": "GOAL"
}
```

***

### 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:**

| Field     | Type   | Description      |
| --------- | ------ | ---------------- |
| `user_id` | string | UUID of the user |

**Example request:**

```bash
curl "https://api.delphi.ai/v3/users/u-123/info" \
  -H "x-api-key: YOUR_API_KEY"
```

**Example response:**

```json
{
  "user_id": "u-123",
  "info_items": [
    {
      "id": "info-001",
      "text": "Wants to improve their public speaking skills",
      "created_at": "2025-06-15T10:30:00.000Z",
      "updated_at": "2025-06-15T10:30:00.000Z",
      "message_id": null,
      "source": "API",
      "info_type": "GOAL"
    },
    {
      "id": "info-002",
      "text": "Prefers short, actionable advice",
      "created_at": "2025-06-14T08:00:00.000Z",
      "updated_at": "2025-06-14T08:00:00.000Z",
      "message_id": null,
      "source": "API",
      "info_type": "PREFERENCES"
    }
  ],
  "total_count": 2
}
```

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

| Field     | Type   | Description                   |
| --------- | ------ | ----------------------------- |
| `user_id` | string | UUID of the user              |
| `info_id` | string | ID of the info item to update |

**Request body:**

| Field       | Type   | Required | Description                                           |
| ----------- | ------ | -------- | ----------------------------------------------------- |
| `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:**

```bash
curl -X PATCH "https://api.delphi.ai/v3/users/u-123/info/info-001" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "info": "Wants to improve their public speaking and storytelling skills",
    "info_type": "GOAL"
  }'
```

**Example response:**

```json
{
  "id": "info-001",
  "text": "Wants to improve their public speaking and storytelling skills",
  "created_at": "2025-06-15T10:30:00.000Z",
  "updated_at": "2025-06-16T14:22:00.000Z",
  "message_id": null,
  "source": "API",
  "info_type": "GOAL"
}
```

**Response fields:**

| Field        | Type   | Description                                     |
| ------------ | ------ | ----------------------------------------------- |
| `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:**

| Field     | Type   | Description                   |
| --------- | ------ | ----------------------------- |
| `user_id` | string | UUID of the user              |
| `info_id` | string | ID of the info item to delete |

**Example request:**

```bash
curl -X DELETE "https://api.delphi.ai/v3/users/u-123/info/info-001" \
  -H "x-api-key: YOUR_API_KEY"
```

**Example response:**

```json
{
  "success": true,
  "message": "User info deleted successfully",
  "deleted_info_id": "info-001"
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.delphi.ai/advanced/actions/api-immortal-only/audience.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.