Audiences & Contacts

Manage your contacts, audiences, segments, and custom fields via the API.

Audiences

Audiences are collections of contacts. Each audience can have custom field schemas and segments.

List Audiences

GET /api/audiences

Returns all audiences for the authenticated user.

{
  "audiences": [
    {
      "id": "clx1abc123",
      "name": "Newsletter Subscribers",
      "description": "Main newsletter list",
      "contactCount": 1250,
      "segmentCount": 3,
      "createdAt": "2024-01-15T10:00:00Z"
    }
  ]
}

Create Audience

POST /api/audiences
{
  "name": "Newsletter Subscribers",
  "description": "Main newsletter list"
}

Contacts

Contacts belong to audiences and can have custom fields for personalization.

List Contacts

GET /api/audiences/:audienceId/contacts

Query parameters: page, limit, search, subscribed

{
  "contacts": [
    {
      "id": "clx2def456",
      "email": "[email protected]",
      "firstName": "John",
      "lastName": "Doe",
      "subscribed": true,
      "customFields": {
        "company": "Acme Inc",
        "plan": "pro"
      },
      "createdAt": "2024-01-20T15:30:00Z"
    }
  ],
  "pagination": {
    "total": 1250,
    "page": 1,
    "limit": 50,
    "pages": 25
  }
}

Add Contact

POST /api/audiences/:audienceId/contacts
{
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "subscribed": true,
  "customFields": {
    "company": "Acme Inc",
    "plan": "pro",
    "signupSource": "website"
  }
}
FieldTypeDescription
emailstringContact email (required, unique per audience)
firstNamestringContact first name
lastNamestringContact last name
subscribedbooleanSubscription status (default: true)
customFieldsobjectCustom field key-value pairs

Update Contact

PATCH /api/audiences/:audienceId/contacts/:contactId
{
  "firstName": "Jonathan",
  "customFields": {
    "plan": "enterprise"
  }
}

Bulk Import Contacts

POST /api/audiences/:audienceId/contacts/bulk
{
  "contacts": [
    {
      "email": "[email protected]",
      "firstName": "User",
      "customFields": { "plan": "starter" }
    },
    {
      "email": "[email protected]",
      "firstName": "Another",
      "customFields": { "plan": "pro" }
    }
  ],
  "skipDuplicates": true
}

Custom Fields

Custom fields allow you to store additional data on contacts. You can define field schemas at the audience level for validation and better organization.

Get Custom Field Usage

GET /api/audiences/:audienceId/custom-fields

Returns all unique custom fields used in the audience with usage statistics.

{
  "customFields": [
    {
      "key": "company",
      "count": 850,
      "sampleValues": ["Acme Inc", "TechCorp", "StartupXYZ"],
      "valueCounts": [
        { "value": "Acme Inc", "count": 120 },
        { "value": "TechCorp", "count": 85 }
      ]
    }
  ],
  "totalContacts": 1250
}

Define Field Schema

POST /api/audiences/:audienceId/field-schemas

Define a field schema to add validation, set default values, and organize your data.

{
  "name": "plan",
  "label": "Subscription Plan",
  "type": "select",
  "required": false,
  "defaultValue": "free",
  "options": ["free", "starter", "pro", "enterprise"]
}
FieldTypeDescription
namestringField key (required, alphanumeric)
labelstringDisplay label for UI
typestringtext, number, date, select, boolean, url, email
requiredbooleanWhether field is required
defaultValuestringDefault value for new contacts
optionsstring[]Valid options (for select type)

Segments

Segments are subsets of contacts within an audience. They can be static (manually managed) or dynamic (rule-based).

List Segments

GET /api/audiences/:audienceId/segments
{
  "segments": [
    {
      "id": "clx3ghi789",
      "name": "Pro Users",
      "description": "Users on pro plan",
      "isDynamic": true,
      "rules": {
        "operator": "and",
        "conditions": [
          { "field": "plan", "operator": "equals", "value": "pro" }
        ]
      },
      "contactCount": 340
    }
  ]
}

Create Dynamic Segment

POST /api/audiences/:audienceId/segments
{
  "name": "Enterprise Users",
  "description": "Contacts on enterprise plan",
  "isDynamic": true,
  "rules": {
    "operator": "and",
    "conditions": [
      {
        "field": "plan",
        "operator": "equals",
        "value": "enterprise"
      },
      {
        "field": "subscribed",
        "operator": "equals",
        "value": true
      }
    ]
  }
}

Available operators: equals, not_equals, contains, not_contains, starts_with, ends_with, is_empty, is_not_empty

Get Segment Contacts

GET /api/segments/:segmentId/contacts

Get Segment Analytics

GET /api/segments/:segmentId/analytics

Returns detailed analytics for the segment including subscription rates and custom field distribution.

{
  "analytics": {
    "total": 340,
    "subscribed": 320,
    "unsubscribed": 20,
    "subscriptionRate": 94,
    "addedLastWeek": 15,
    "addedLastMonth": 45,
    "customFields": [
      {
        "field": "plan",
        "contactCount": 340,
        "coverage": 100,
        "topValues": [
          { "value": "pro", "count": 200, "percentage": 59 },
          { "value": "enterprise", "count": 140, "percentage": 41 }
        ]
      }
    ]
  }
}

Add Contacts to Static Segment

POST /api/segments/:segmentId/contacts
{
  "contactIds": ["clx2def456", "clx2def789"]
}

Using Custom Fields in Templates

Custom fields can be used in email templates for personalization using the {{fieldName}} syntax.

<p>Hi {{firstName}},</p>

<p>Your current plan is: <strong>{{plan}}</strong></p>

{{#if company}}
<p>Company: {{company}}</p>
{{/if}}

{{#if plan == "enterprise"}}
<p>Thank you for being an enterprise customer!</p>
{{else}}
<p>Upgrade to Enterprise for premium features.</p>
{{/if}}

See Templates for more information on template variables and conditionals.

Related