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