Twitter Custom Audiences Connector Setup Guide | Server-Side Connectors

API Information

This connector uses the following vendor API:

API Name: Twitter Ads API
API Version: v11
API Endpoint: https://ads-api.twitter.com/
Documentation: Twitter Custom Audiences API

Batch Limits

This connector uses batched requests to support high-volume data transfers to the vendor. For more information, see Batched Actions. Requests are queued until one of the following thresholds is met or the profile is published:

Max number of requests: 1000
Max time since oldest request: 60 minutes
Max size of requests: 2 MB

Prerequisites

Sign up for a developer account. Both Essential and Elevateddeveloper access can access the Ads API. Please see the access levels to determine what access is required.
Create a developer app and secure your token
Request access to the Ads API. Make sure to include the correct App ID in the application. The App ID can be found in theDeveloper Portalunder Projects & Apps. For example: 16489123

If you are already building on the Twitter Developer Platform and have a developer account, skip to step 3.

How it works

Twitter Custom Audiences gives you control on who sees your Twitter Ads. Twitter Ads gives you powerful context to connect your message to what’s most meaningful to your customers in real time. Engaging with real-time Tweets can influence conversations in a way that can help build your business.

Audiences is a tool in your Twitter Ads account that allows you to review and manage your audiences. You can access it by navigating to Tools > Audiences.

From there, you can use your Custom Audiences in your campaign targeting to directly reach the users you care about. Tealium provides the ability to create a Twitter Custom Audience through the user interface within AudienceStream and leverage your audience data to populate the Audience lists. Additionally, Audience lists can be created in your Twitter Ads account and populate into AudienceStream to add or remove users. Examples of audiences that you can re-target previous customers, web visitors who haven’t yet converted, and/or target high-value customers.

Tealium provides a list of hashed identifiers that can be sent to Twitter to add or remove a user from the custom audience list, and Twitter performs a match and produces segments that are made available against media buying on Twitter. Your lists are matched with @handles on Twitter so that you can directly target them in your campaigns, making your marketing highly relevant.

Considerations

All user identifiers except “Partner User ID” must be hashed using SHA256 hashing methods and normalized.
If the “User Identifier is already hashed” checkbox is unchecked, The connector action will normalize and hash the mapped value.
When you create a Custom Audience, there’s an initial processing period where the users on the Custom Audience are “matched” by the Twitter systems to their Twitter @handle. This will then enable ad serving with the Promoted Ads to their account.
- It’s possible that not all of the users on your Custom Audience are active Twitter users, which is why you might see a final Custom Audience size that is smaller than the connector actions firing volume.
- All Custom Audiences show up in AudienceStream, but only those in Ready serving status will properly target users in your campaign. This is viewable within your Twitter Ads account > Audiences section.
An audience can only be targeted if it matches at least 100 users active within the past 90 days on Twitter-owned and -operated clients.
Generally speaking audience changes are processed in batches that run every 6-8 hours. While an audience change is processing the existing audience to be updated is unaffected.
Audience lists created through AudienceStream will be added as a “List” Type within the Ads Campaign manager.
It is recommended to not use Twitter data to derive or infer potentially sensitive characteristics about Twitter users. A listing of these characteristics can be found at More About Restricted uses of the Twitter APIs.

Connector Actions

Action Name	AudienceStream	EventStream
Add User To Custom Audience	✓	✓
Remove User From Custom Audience	✓	✓

Configure Settings

Go to the Connector Marketplace and add a new connector. Read the Connector Overview article for general instructions on how to add a connector.

After adding the connector, configure the following settings:

Ad Account ID
- Required.
- Provide your Twitter Ad Account ID.
- Your Account ID can be located in your account’s URL when logged in.
- Example: If the URL is https://ads.twitter.com/accounts/1234abcd/, the account ID is 1234abcd.

Create a Custom Audience Overview

The Create Custom Audience overlay appears within the Configuration screen of the Twitter Custom Audiences connector. The Name field is the only required value for creation of an Audience List.

The list_type parameter was previously used to identify the user identifier type of the Audience (for instance: email, Twitter User ID, Partner User ID, et cetera). However, Audiences now have the ability to accept multiple user identifiers for the same Audience, and this field is no longer required.

Action Settings - Parameters and Options

Click Next or go to the Actions tab. This is where you configure connector actions.

This section describes how to set up parameters and options for each action.

Action - Add User To Custom Audience

Parameters

Parameter	Description
Custom Audience	Required Select audience from list. This value is retrieved from the Twitter Ads account and will appear instantly when created through the AudienceStream Configuration screen. For more information, see Custom Audiences.
Device ID	User Device ID. This value should be an iOS Advertising Identifier, Google Advertising ID, or when not available - Android ID.
Email	User Email. If an unhashed email address is mapped, please utilize the User Identifier Hashing checkbox. Otherwise a SHA256 Email should be mapped.
Partner User ID	The user’s ID in the partner’s system. If your company uses its own standard ID system to track users (i.e. not common user identifiers like email addresses, device ids, twitter user ID, et cetera), then this is the recommended parameter.
Phone Number	The user’s phone number. This value is no longer supported by the API and should not be mapped
Twitter Handle	The Twitter @handle belonging to the user.
Twitter ID	The Twitter ID belonging to the user. The Twitter ID is a unique value that every account on Twitter has. No two people have the same ID. Although an account can change its @handle, it can never change its Twitter ID
User Identifier Hashing	All user identifiers except “Partner User ID” must be hashed using SHA256 hashing methods and normalized. If the checkbox is unchecked, the Add User action will normalize and hash the mapped value.
Effective At	Membership option. The UTC time at which the custom audience associations should take effect. Expressed in ISO 8601. Defaults to the current date and time. A millisecond (MS) since epoch timestamp may be provided, and will be formatted correctly.
Expired At	Membership option. The UTC time at which the custom audience associations should expire. The specified time must be later than the value of “Effective At”. Expressed in ISO 8601. Defaults to your configured default expiration period, which is typically 30 days or 720 hours from the value of “Effective At”.

Action - Remove User From Custom Audience

Parameters

Parameter	Description
Custom Audience	Required Select audience from list. This value is retrieved from the Twitter Ads account and will appear instantly when created through the AudienceStream Configuration screen. For more information, see Custom Audiences.
Device ID	User Device ID. This value should be an iOS Advertising Identifier, Google Advertising ID, or when not available - Android ID.
Email	User Email. If an unhashed email address is mapped, please utilize the User Identifier Hashing checkbox. Otherwise a SHA256 Email should be mapped.
Partner User ID	Partner User ID. If your company uses its own standard ID system to track users (for instance, not common user identifiers like email addresses, device ids, twitter user ID, et cetera), then this is the recommended parameter.
Phone Number	The user’s phone number. This value is no longer supported by the API and should not be mapped
Twitter Handle	The Twitter @handle belonging to the user.
Twitter ID	The Twitter ID belonging to the user. The Twitter ID is a unique value that every account on Twitter has. No two people have the same ID. Although an account can change its @handle, it can never change its Twitter ID
User Identifier Hashing	All user identifiers except “Partner User ID” must be hashed using SHA256 hashing methods and normalized. If the checkbox is unchecked, the Remove User action will normalize and hash the mapped value.
Effective At	Membership option. The UTC time at which the custom audience associations should take effect. Expressed in ISO 8601. Defaults to the current date and time. A millisecond (ms) since epoch timestamp may be provided, and will be formatted correctly.
Expired At	Membership option. The UTC time at which the custom audience associations should expire. The specified time must be later than the value of “Effective At”. Expressed in ISO 8601. Defaults to your configured default expiration period, which is typically 30 days or 720 hours from the value of “Effective At”.