X Custom Audiences Connector Setup Guide

API Information

This connector uses the following vendor API:

• API Name: X Ads API
• API Version: v12
• API Endpoint: https://ads-api.x.com/
• Documentation: X 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

1. 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.
2. Create a developer app and secure your token
3. 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 X Developer Platform and have a developer account, skip to step 3.

How it works

X Custom Audiences gives you control on who sees your X Ads. X 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 X 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 X 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 X 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 X to add or remove a user from the custom audience list, and X performs a match and produces segments that are made available against media buying on X. Your lists are matched with @handles on X 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 X systems to their X @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 X 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 X Ads account > Audiences section.

• An audience can only be targeted if it matches at least 100 users active within the past 90 days on X-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 X data to derive or infer potentially sensitive characteristics about X users. A listing of these characteristics can be found at More About Restricted uses of the X APIs.

Connector Actions

Action Name	AudienceStream	EventStream
Add User To Custom Audience	✓	✓
Remove User From Custom Audience	✓	✓
Add User To Custom Audience (multiple identifiers)	✓	✓
Remove User From Custom Audience (multiple identifiers)	✓	✓

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 X Ad Account ID.
  • Your Account ID can be located in your account’s URL when logged in.
  • Example: If the URL is https://ads.x.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 X 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, X 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 X 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 (that is, not common user identifiers like email addresses, device IDs, X user ID, etc.), 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
X Handle	The X @handle belonging to the user.
X ID	The X ID belonging to the user. The X ID is a unique value that every account on X has. No two people have the same ID. Although an account can change its @handle, it can never change its X 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 X 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, X 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
X Handle	The X @handle belonging to the user.
X ID	The X ID belonging to the user. The X ID is a unique value that every account on X has. No two people have the same ID. Although an account can change its @handle, it can never change its X 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”.

Action - Add User To Custom Audience

User identifiers

You must provide at least one of the following parameters:

| Parameter | Type |Description | | — | — | | Email (apply SHA256 hash) | String | Provide a plain text email address and the connector whitespaces trim, lowercase, and hash this value using SHA256 hash. | | Email (already SHA256 hashed) | String| Provide an email address which has been already whitespace trimmed, lowercased, and SHA256 hashed. | | Phone Number (apply SHA256 hash) | String | Provide a plain text phone number and the connector will whitespace trim, lowercase, and hash this value using SHA256 hash. | | Phone Number (already SHA256 hashed) | String| Provide a phone number which has been already whitespace trimmed, lowercased, SHA256 hashed, and in E164 format. | | Device ID (apply SHA256 hash) | String| Provide the device ID and the connector whitespaces trim, lowercase, and hash this value using SHA256 hash. | | Device ID (already SHA256 hashed)| String | Provide a device ID which has been already whitespace trimmed, lowercased, and SHA256 hashed. | | X Handle (apply SHA256 hash)| String | Provide an X handle and the connector will whitespace trim, lowercase, and hash this value using SHA256 hash. | | X Handle (already SHA256 hashed) | String| Provide a X handle which has been already whitespace trimmed, lowercased, and SHA256 hashed. | | X ID (apply SHA256 hash) | String| Provide an X ID and the connector will whitespace trim, lowercase, and hash this value using SHA256 hash. | | X ID (already SHA256 hashed)| String | Provide an X ID which has been already whitespace trimmed, lowercased, and SHA256 hashed. | | Partner User ID | String| Provide the partner user ID. |

Parameters

Parameter	Description
Custom Audience	Required Select audience from list. This value is retrieved from the X 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 (that is, not common user identifiers like email addresses, device IDs, X user ID, etc.), 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
X Handle	The X @handle belonging to the user.
X ID	The X ID belonging to the user. The X ID is a unique value that every account on X has. No two people have the same ID. Although an account can change its @handle, it can never change its X 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

User identifiers

You must provide at least one of the following parameters:

| Parameter | Type |Description | | — | — | | Email (apply SHA256 hash) | String | Provide a plain text email address and the connector whitespaces trim, lowercase, and hash this value using SHA256 hash. | | Email (already SHA256 hashed) | String| Provide an email address which has been already whitespace trimmed, lowercased, and SHA256 hashed. | | Phone Number (apply SHA256 hash) | String | Provide a plain text phone number and the connector will whitespace trim, lowercase, and hash this value using SHA256 hash. | | Phone Number (already SHA256 hashed) | String| Provide a phone number which has been already whitespace trimmed, lowercased, SHA256 hashed, and in E164 format. | | Device ID (apply SHA256 hash) | String| Provide the device ID and the connector whitespaces trim, lowercase, and hash this value using SHA256 hash. | | Device ID (already SHA256 hashed)| String | Provide a device ID which has been already whitespace trimmed, lowercased, and SHA256 hashed. | | X Handle (apply SHA256 hash)| String | Provide an X handle and the connector will whitespace trim, lowercase, and hash this value using SHA256 hash. | | X Handle (already SHA256 hashed) | String| Provide a X handle which has been already whitespace trimmed, lowercased, and SHA256 hashed. | | X ID (apply SHA256 hash) | String| Provide an X ID and the connector will whitespace trim, lowercase, and hash this value using SHA256 hash. | | X ID (already SHA256 hashed)| String | Provide an X ID which has been already whitespace trimmed, lowercased, and SHA256 hashed. | | Partner User ID | String| Provide the partner user ID. |

Parameters

Parameter	Description
Custom Audience	Required Select audience from list. This value is retrieved from the X 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, X 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
X Handle	The X @handle belonging to the user.
X ID	The X ID belonging to the user. The X ID is a unique value that every account on X has. No two people have the same ID. Although an account can change its @handle, it can never change its X 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”.