# Audience Members

The Audience Members API lets you read, create, update, and delete member records programmatically. All requests require a Bearer token — see [API Authentication](/developer/api/authentication.md) for setup instructions.

Base path: `/api/v1/audience-members`

***

## List audience members[​](#list-audience-members "Direct link to List audience members")

```http
GET /api/v1/audience-members

```

Returns a paginated list of audience members ordered by most recently created.

### Query parameters[​](#query-parameters "Direct link to Query parameters")

| Parameter            | Description                                                                                        |
| -------------------- | -------------------------------------------------------------------------------------------------- |
| `email`              | Filter to the member with this exact email address.                                                |
| `foreign_key[key]`   | Filter by a foreign key name (requires `foreign_key[value]`).                                      |
| `foreign_key[value]` | Filter by a foreign key value (requires `foreign_key[key]`).                                       |
| `include_deleted`    | Pass `true` to include soft-deleted members in the results.                                        |
| `include`            | Comma-separated list of related resources to embed. Supported values: `entitlements`, `purchases`. |

### Including related resources[​](#including-related-resources "Direct link to Including related resources")

Use `?include=entitlements` to embed each member's active entitlements:

```bash
curl https://your-instance.allegrocdp.com/api/v1/audience-members?include=entitlements \
  -H "Authorization: Bearer <your-token>" \
  -H "Accept: application/json"

```

Use `?include=purchases` to embed each member's completed purchases:

```bash
curl https://your-instance.allegrocdp.com/api/v1/audience-members?include=purchases \
  -H "Authorization: Bearer <your-token>" \
  -H "Accept: application/json"

```

You can combine both:

```bash
curl "https://your-instance.allegrocdp.com/api/v1/audience-members?include=entitlements,purchases" \
  -H "Authorization: Bearer <your-token>" \
  -H "Accept: application/json"

```

***

## Get a single audience member[​](#get-a-single-audience-member "Direct link to Get a single audience member")

```http
GET /api/v1/audience-members/{id}

```

Returns a single audience member by their UUID.

The `include` parameter works the same way as on the list endpoint — pass `?include=entitlements`, `?include=purchases`, or `?include=entitlements,purchases` to embed related resources.

```bash
curl "https://your-instance.allegrocdp.com/api/v1/audience-members/abc123?include=entitlements" \
  -H "Authorization: Bearer <your-token>" \
  -H "Accept: application/json"

```

***

## Create an audience member[​](#create-an-audience-member "Direct link to Create an audience member")

```http
POST /api/v1/audience-members

```

Creates a new audience member.

### Request body[​](#request-body "Direct link to Request body")

```json
{
    "name": "Jane Smith",
    "email": "jane@example.com",
    "meta": {
        "customer_id": "cust_001"
    }
}

```

| Field   | Required | Description                                                         |
| ------- | -------- | ------------------------------------------------------------------- |
| `email` | yes      | The member's email address. Must be unique within the organization. |
| `name`  | no       | The member's display name.                                          |
| `meta`  | no       | Key/value object of arbitrary metadata to store on the member.      |

Returns `201 Created` with the new member resource.

***

## Update an audience member[​](#update-an-audience-member "Direct link to Update an audience member")

```http
PUT /api/v1/audience-members/{id}

```

Fully replaces an audience member's attributes and metadata. If `meta` is included, all existing metadata is removed and replaced with the provided values. Omit `meta` entirely to leave it unchanged.

### Request body[​](#request-body-1 "Direct link to Request body")

```json
{
    "name": "Jane Smith",
    "email": "jane@example.com",
    "meta": {
        "customer_id": "cust_001"
    }
}

```

***

## Patch an audience member[​](#patch-an-audience-member "Direct link to Patch an audience member")

```http
PATCH /api/v1/audience-members/{id}

```

Partially updates an audience member. Only the fields you include are changed. For `meta`, values are merged: set a key to `null` to remove it, or provide a value to add or overwrite it.

### Request body[​](#request-body-2 "Direct link to Request body")

```json
{
    "meta": {
        "customer_id": "cust_002",
        "old_key": null
    }
}

```

***

## Delete an audience member[​](#delete-an-audience-member "Direct link to Delete an audience member")

```http
DELETE /api/v1/audience-members/{id}

```

Soft-deletes the audience member. Returns `204 No Content` on success.

Soft-deleted members are excluded from list results by default. Pass `?include_deleted=true` on the list endpoint to include them.

***

## Response shapes[​](#response-shapes "Direct link to Response shapes")

### Audience member[​](#audience-member "Direct link to Audience member")

```json
{
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "email_verified": true,
    "meta": {
        "customer_id": "cust_001"
    },
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-03-01T08:00:00Z"
}

```

### With `?include=entitlements`[​](#with-includeentitlements "Direct link to with-includeentitlements")

An `entitlements` array is added to the member object containing their currently active entitlements:

```json
{
    "id": "01234567-...",
    "entitlements": [
        {
            "id": "ent_abc",
            "product": {
                "id": "prod_xyz",
                "name": "Digital Access"
            },
            "started_at": "2026-01-01T00:00:00Z",
            "ended_at": null,
            "note": null,
            "is_active": true,
            "created_at": "2026-01-01T00:00:00Z",
            "updated_at": "2026-01-01T00:00:00Z"
        }
    ]
}

```

### With `?include=purchases`[​](#with-includepurchases "Direct link to with-includepurchases")

A `purchases` array is added containing the member's completed purchases:

```json
{
    "id": "01234567-...",
    "purchases": [
        {
            "id": "pur_def",
            "status": "completed",
            "status_label": "Completed",
            "amount": 999,
            "formatted_amount": "$9.99",
            "currency": "usd",
            "provider": "stripe",
            "has_active_entitlement": true,
            "plan": {
                "id": "plan_123",
                "name": "Monthly"
            },
            "created_at": "2026-01-01T00:00:00Z",
            "updated_at": "2026-01-01T00:00:00Z"
        }
    ]
}

```

note

`amount` is in the currency's smallest unit (e.g., cents for USD). `formatted_amount` is a human-readable string.