Audiences API

19min
Overview
Chord's Audiences API allows you to access audiences, along with associated audience attributes, directly via API.
Use Cases
Use the audience "Products Abandoned," which has every visitor's top products last viewed but not yet purchased, to customize the experience on your website for repeat visitors by featuring these users' top products for enhanced personalization and conversion opportunity.
Create an audience with personalized user attributes, such as new vs. returning visitor, last campaign seen, and more, to test different landing page customizations on your website.
Getting Started
Data Destination
Once your account has the Audiences API enabled, the "Dynamic Audiences API" data destination will be available in Data Activations.
﻿
 Audiences
You can use a pre-built audience or create a custom audience you want to activate via the Audiences API. 
The audience must use the CDP Blended User ID, which is derived from the Chord data models and contains the CDP User ID, if one exists, else the CDP Anonymous ID. This use case is particularly useful when mixing users who may or may not have a known CDP User ID. By using the CDP Blended User ID, audiences can be created for both users and visitors using the same ID, also allowing us to aggregate all audiences at the Blended User ID level in the API.
Activations Sync
Select a Source and Destination
Once your destination is enabled and you have the audience you'd like to use, you'll create a sync in Activations. Using our Sync UI, we must create a new sync that connects a custom audience as the source, the Dynamic Audiences API as the destination, and the object as {name}_audiences, with the object being pre-configured in the provisioning process. 
﻿
Sync Behavior
Sync Behaviors dictate the types of change that should be applied to your data when a sync finds a matching (or not) record in a source and a destination. 
﻿
We want to use the "Mirror" option, which will perform the following behaviors for records in the destination:
Create: This will add new users in a given audience.
Update: This will change values for users in a given audience. For example, if data like top products change for a given user in an audience, this behavior will update that record in the destination.
Delete: This will delete values for users no longer in a given audience.
Sync Key
Sync Keys will dictate how to associate data in the source with the destination. Both the source and destination need to provide a single, unique per record, identifying field. The identifiers will be used to look for matches. When a match is found, or not found, we can use your selected Sync Behavior to decide what to do. Your sync key can be any unique identifier, like a user ID, an email address, etc. However, we recommend using the CDP Blended User ID provided by Chord to provide user consistency across all datasets, allowing for the best matching in the destination.
Field Mappings
Once you've defined how data is related between your source and destination, the next step is to determine what properties should be updated. The field mapping step lets you specify how fields should be mapped from your source model to the destination object's fields.
We start by assigning our unique user identifier. anonymous_current_cdp_blended_user_id will become our pk (primary key).
We can then set up the sk (sort key). It is important to ensure that this value reflects the name of the Audience being synced. You can easily obtain that value by choosing Sync Metadata > Source Name, which will dynamically populate the name applied to your audience.
﻿
You should end up with the following:
﻿
Data Field (Optional)
The destination supports flexible schemas, allowing you to send any data and define custom names for destination fields.
Make sure to send the content to a data destination field:
﻿
You must use Liquid templating to perform last-mile transformations on your source data.
For example, if your audience contains an anonymous_id, user_id, and a list of products and you'd like to append these data components for use via the API, the following mapping will create a data attribute in the API response:
Text
{
  "anonymous_id": {{ record['ANONYMOUS_ID'] }},
  "user_id": {{ record['USER_ID'] }},
  "products": {{ record['PRODUCTS'] | raw }}
}
{
  "anonymous_id": {{ record['ANONYMOUS_ID'] }},
  "user_id": {{ record['USER_ID'] }},
  "products": {{ record['PRODUCTS'] | raw }}
}
﻿
Any column can be added to this data attribute, making these supplemntary values will be available via API.
Sync Schedule
Like any other sync on our Data Activations page, it can be scheduled to run at regular intervals:
﻿
Sync Results
The Chord platform will display the sync results as usual:
﻿
How to Make Requests to the Audiences API
Prerequisites
An API key provided by Chord, to be used as a bearer token. If you have not received your API key, please reach out to [email protected].
A unique user identifier that is being used as the pk in your Sync.
It should be included in the request headers.
Depending on your sync field mapping, it could be an email address, an anonymous ID, a user ID, etc. Chord recommends using the CDP Blended User ID as the primary key
Request Example
When CDP Blended User ID is being used as the pk in your sync
JSON
curl -X GET \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -H "chord-user-id: 7496fd47cc30-143c-4279-6e6e8a7a" \
  https://analytics.api.chord.co/audiences
curl -X GET \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -H "chord-user-id: 7496fd47cc30-143c-4279-6e6e8a7a" \
  https://analytics.api.chord.co/audiences
﻿
Response Example
When Blended User ID is being used a the pk in your sync
JSON
{
  "user": "7496fd47cc30-143c-4279-6e6e8a7a",
  "audiences": [
    {
      "name": "Audience - Cart Abandoned",
      "data": {
        "unique_session_count": 2,
        "unique_session_with_completed_order_count": 0,
        "user_email": "",
        "unique_session_added_product_count": 1
      }
    }
  ]
}
{
  "user": "7496fd47cc30-143c-4279-6e6e8a7a",
  "audiences": [
    {
      "name": "Audience - Cart Abandoned",
      "data": {
        "unique_session_count": 2,
        "unique_session_with_completed_order_count": 0,
        "user_email": "",
        "unique_session_added_product_count": 1
      }
    }
  ]
}
﻿
Request Sample
Below are example requests, but this will depend on your server-side framework. Audiences API should always be called server-side.
TypeScript
TypeScript
const userId: string | null = null; // assuming that userId is not known
const anonymousId: string = '7496fd47cc30-143c-4279-6e6e8a7a';

// Use the nullish coalescing operator (??) to fall back to anonymousId 
// if userId is null or undefined
const blendedUserId: string = userId ?? anonymousId;

const url: string = 'https://analytics.api.chord.co/audiences';

const headers: HeadersInit = {
  'Authorization': 'Bearer YOUR_BEARER_TOKEN',
  'Chord-User-Id': blendedUserId
};

async function fetchData() {
  try {
    const response = await fetch(url, {
      method: 'GET',
      headers: headers
    });

    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }

    const data = await response.json();
    console.log(data); // Handle the response data here
  } catch (error) {
    console.error('Error:', error); // Handle errors here
  }
}

fetchData();
const userId: string | null = null; // assuming that userId is not known
const anonymousId: string = '7496fd47cc30-143c-4279-6e6e8a7a';

// Use the nullish coalescing operator (??) to fall back to anonymousId 
// if userId is null or undefined
const blendedUserId: string = userId ?? anonymousId;

const url: string = 'https://analytics.api.chord.co/audiences';

const headers: HeadersInit = {
  'Authorization': 'Bearer YOUR_BEARER_TOKEN',
  'Chord-User-Id': blendedUserId
};

async function fetchData() {
  try {
    const response = await fetch(url, {
      method: 'GET',
      headers: headers
    });

    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }

    const data = await response.json();
    console.log(data); // Handle the response data here
  } catch (error) {
    console.error('Error:', error); // Handle errors here
  }
}

fetchData();
﻿
Troubleshooting and FAQs
Question: How do I get access to Audiences API?
Please reach out to [email protected] or your account executive for more information about or access to this feature.
﻿
Updated 05 Mar 2025
Did this page help you?
Custom Audiences
Data Sources