Skip to main content

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 for setup instructions.

Base path: /api/v1/audience-members

List audience members​

GET /api/v1/audience-members

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

Query parameters​

ParameterDescription
emailFilter 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_deletedPass true to include soft-deleted members in the results.
includeComma-separated list of related resources to embed. Supported values: entitlements, purchases.

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

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:

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:

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

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​

POST /api/v1/audience-members

Creates a new audience member.

Request body​

{
    "name": "Jane Smith",
    "email": "[email protected]",
    "meta": {
        "customer_id": "cust_001"
    }
}
FieldRequiredDescription
emailyesThe member's email address. Must be unique within the organization.
namenoThe member's display name.
metanoKey/value object of arbitrary metadata to store on the member.

Returns 201 Created with the new member resource.

Update an audience member​

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​

{
    "name": "Jane Smith",
    "email": "[email protected]",
    "meta": {
        "customer_id": "cust_001"
    }
}

Patch an audience member​

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​

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

Delete an audience member​

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​

Audience member​

{
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "Jane Smith",
    "email": "[email protected]",
    "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​

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

{
    "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​

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

{
    "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.