Product Documentation
  1. Build Audiences

Create a Persona and Use It in an Audience

Define who you target once, then include or exclude it in intent audiences

flowchart LR
    A[Create Persona] --> B[Poll Until Complete]
    B --> C[Create Audience with PERSONA rule]
    C --> D[Poll, Preview, Download]

    style A fill:#3b82f6,color:#fff
    style D fill:#22c55e,color:#fff

Use Case

  • Define a target profile ("Marketing VP+") once and reuse it across intent audiences
  • Suppress a group ("Existing Customers") from every audience you build
  • Change the profile in one place and have every audience that uses it rebuild

A persona is an audience with segmentation_type: "Persona". It holds who: job, demographic and location filters, with no intent. An audience refers to it with a PERSONA rule, and the persona's conditions are applied as part of the audience's query.

Prerequisites

Steps

1. Create the Persona

import time
import requests

API_KEY = "your_api_key"
API_SECRET = "your_api_secret"
ORG_ID = "your_organization_id"
PROJECT_ID = "your_project_id"

HEADERS = {
    "X-Api-Key": API_KEY,
    "X-Api-Secret": API_SECRET,
    "Content-Type": "application/json",
}
AUDIENCES = "https://api.delivr.ai/api/v1/audiences"

resp = requests.post(
    AUDIENCES,
    headers=HEADERS,
    params={"project_id": PROJECT_ID},
    json={
        "organization_id": ORG_ID,
        "project_id": PROJECT_ID,
        "audience_name": "Marketing VP+",
        "segmentation_type": "Persona",
        "type": "contact",
        "filter": {
            "condition": "and",
            "rules": [
                {"fieldName": "seniority_level", "conditionRules": {"operator": "in", "value": ["vp", "cxo"]}},
                {"fieldName": "department", "conditionRules": {"operator": "in", "value": ["marketing"]}},
            ],
        },
    },
)
resp.raise_for_status()
persona_id = resp.json()["id"]

Use type: "contact". A persona describes people, not intent, so it has no INTENT rule, and type: "intents" without one is rejected with 400. Picklist values match case-insensitively. See Understanding Segmentation Types for the fields a persona can use.

2. Poll Until Complete

def wait_for(audience_id):
    while True:
        body = requests.get(
            f"{AUDIENCES}/{audience_id}", headers=HEADERS, params={"project_id": PROJECT_ID}
        ).json()
        if body["status"] in ("Completed", "Validated"):
            return body
        if body["status"] == "Failed":
            raise RuntimeError(body.get("error"))
        time.sleep(15)

persona = wait_for(persona_id)
print(f"Persona {persona_id}: {persona['size']} people")

Treat any status other than Completed, Validated or Failed as still building. A persona over the full contact database typically takes a few minutes.

3. Include the Persona in an Audience

Add a PERSONA rule next to the intent rule. The value is a list of persona IDs as strings.

resp = requests.post(
    AUDIENCES,
    headers=HEADERS,
    params={"project_id": PROJECT_ID},
    json={
        "organization_id": ORG_ID,
        "project_id": PROJECT_ID,
        "audience_name": "Cloud Computing Intent - Marketing VP+",
        "segmentation_type": "Audience",
        "type": "intents",
        "filter": {
            "condition": "and",
            "rules": [
                {"fieldName": "INTENT", "conditionRules": {"operator": "in", "value": ["4eyes_119418"]}},
                {"fieldName": "PERSONA", "conditionRules": {"operator": "in", "value": [str(persona_id)]}},
            ],
        },
    },
)
resp.raise_for_status()
audience = wait_for(resp.json()["id"])
print(f"Audience: {audience['size']} people")

This returns people showing intent for the topic and matching the persona. Listing several persona IDs in one rule matches anyone in any of them.

4. Exclude a Persona Instead

Use notin to remove a persona's members, for example existing customers:

{"fieldName": "PERSONA", "conditionRules": {"operator": "notin", "value": [str(persona_id)]}}

The exclusion removes only people who match the persona. Someone whose seniority or department is unknown does not match it, so they stay in the audience. An in audience and a notin audience on the same persona and topic therefore add up to the topic on its own.

From here, preview and download the audience as in Create an Intent Audience, steps 4 and 5.

Notes

  • Same project only. A PERSONA rule can only name personas in the audience's project. An ID from another project, or one that does not exist, is rejected with 400 rather than ignored.
  • Edit once. Changing a persona's filter recompiles every audience that uses it and queues them to rebuild.
  • Accounts work the same way. An Account (segmentation_type: "Account", type: "contact", company_* fields) is referenced with fieldName: "ACCOUNT" and supports in and notin.

Next Steps

Updated about 2 hours ago

Did this page help you?