> ## Documentation Index
> Fetch the complete documentation index at: https://docs.extole.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Receive Audience Membership from a Partner

> Add the audience, credential, and setup instructions for a partner platform that manages audience membership in Extole.

Extole supports partner-managed audience membership over the API. Use it to sync groups such as segments, subscription states, or loyalty tiers to an Extole audience.

Add the following to the standard integration tree:

* An audience owned by the integration, with its identifier stored as a setting on the integration component.
* A server access token the partner authenticates with.
* Setup instructions carrying the audience identifier and the calls below.

If the partner has a maintained library source, install it first and add audience membership to the installed campaign. For other integration paths, see [Create an Integration with the Management API](/technical/building-custom-integrations/integration-lifecycle/management-api-integration).

## Create the Audience

```bash theme={null}
curl --request POST "$EXTOLE_API_HOST/v1/audiences" \
  --header "Authorization: Bearer $MANAGEMENT_API_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Example Eligible Offer Participants",
    "tags": ["example"]
  }'
```

Audiences are client-scoped and are created in the currently selected client, so confirm it is the client that owns the campaign before this call. Store the returned identifier as a setting on the integration component.

## Create the Credential

The partner sends server-side requests with a bearer token. The installer creates it in **Security Center** in My Extole, with permission to write audience membership, and stores it in the partner platform's secret storage.

Do not create this token during the build or write it into a component setting.

## Resolve the Person

Single-member calls take an Extole person ID. Resolve by email:

```bash theme={null}
curl "$EXTOLE_API_HOST/v5/persons?identity_key_value=customer@example.com" \
  --header "Authorization: Bearer $PARTNER_ACCESS_TOKEN"
```

Or by the partner's customer identifier, when the integration maps it to `partner_user_id`:

```bash theme={null}
curl "$EXTOLE_API_HOST/v5/persons?person_keys=partner_user_id:$PARTNER_USER_ID" \
  --header "Authorization: Bearer $PARTNER_ACCESS_TOKEN"
```

Both return an array. An empty array means Extole has no person for that identity; send those customers in a batch instead, which creates the people it does not find.

## Add or Remove One Member

```bash theme={null}
curl --request POST \
  "$EXTOLE_API_HOST/v5/persons/$PERSON_ID/memberships" \
  --header "Authorization: Bearer $PARTNER_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"audience_id": "'"$AUDIENCE_ID"'"}'
```

A successful call returns the membership:

```json theme={null}
{
  "audience_id": "abc123def456",
  "audience_name": "Example Eligible Offer Participants",
  "created_date": "2026-08-25T05:33:48.198-07:00",
  "updated_date": "2026-08-25T05:33:48.198-07:00"
}
```

To remove:

```bash theme={null}
curl --request DELETE \
  "$EXTOLE_API_HOST/v5/persons/$PERSON_ID/memberships/$AUDIENCE_ID" \
  --header "Authorization: Bearer $PARTNER_ACCESS_TOKEN"
```

## Send a Batch

Create an audience operation. Use `ADD` and `REMOVE` for incremental changes; use `REPLACE` when the partner sends a complete list and the audience must match it exactly.

```bash theme={null}
curl --request POST \
  "$EXTOLE_API_HOST/v1/audiences/$AUDIENCE_ID/operations" \
  --header "Authorization: Bearer $PARTNER_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "type": "ADD",
    "data_source": {
      "type": "PERSON_LIST",
      "audience_members": [
        {"identity_key_value": "first@example.com"},
        {"identity_key_value": "second@example.com"}
      ]
    }
  }'
```

A `PERSON_LIST` batch creates a person for any identity Extole does not already know. `data_source` is required; omitting it currently returns a 500 rather than a validation error.

Operations apply in the background. Poll the state until it reaches `READY`; a `FAILED` operation carries an `error_code`.

```bash theme={null}
curl "$EXTOLE_API_HOST/v1/audiences/$AUDIENCE_ID/operations/$OPERATION_ID/state" \
  --header "Authorization: Bearer $PARTNER_ACCESS_TOKEN"
```

## Read Current Members

```bash theme={null}
curl "$EXTOLE_API_HOST/v1/audiences/$AUDIENCE_ID/members/view/details" \
  --header "Authorization: Bearer $PARTNER_ACCESS_TOKEN"
```

## Report on What Arrives

Chart audience membership rather than webhook traffic in the activity view from [Add the Activity and Event Views](/technical/building-custom-integrations/integration-lifecycle/integration-activity-views), and scope the report runner to this integration's audience. Chart only columns the chosen report type returns.

## Write the Setup Instructions

The configuration view must give the installer:

* The audience identifier.
* Where to create the server access token and the permission it needs.
* The endpoints above with their request bodies, not a link to the API reference.
* That every call is server-side. The token must not reach a browser or a mobile app.

## Verify

In addition to [Validate and Publish an Integration](/technical/building-custom-integrations/integration-lifecycle/integration-validation):

* The audience exists in the client that owns the campaign, and the integration setting holds its identifier.
* A batch `ADD` reaches `READY` and the members appear in the audience.
* A `REMOVE` takes them out again.
* The report runner is scoped to this audience and its charted columns exist in the report type.
* The configuration view names the endpoints and the credential.