Custom Audiences

Custom audiences allow advertisers to target their Sponsored Story or Ad to a specific set of users with whom they have already established a relationship on/off Facebook. Audiences can be defined by either user email address, Facebook UIDs, user phone numbers, or app user IDs. When utilizing Facebook UIDs please ensure you comply with Section II of the Platform Policies.

Create a Blank Audience

 curl -F 'name=testAudience' 
 https://graph.facebook.com/act_adaccountid/customaudiences?access_token=___

If successful, the above call with return an ID for the newly created audience.

 {id: 12345}

Getting the list of Audiences

 curl https://graph.facebook.com/act_adaccountid/customaudiences?access_token=___

Adding users to an audience

Users can be added to audiences either using a hash of an Email Address, their Facebook ID, their Phone Number, or their App User ID.

 curl -F 'users=[{"email_hash":"MD5"}, {"email_hash":"MD5"}, {"email_hash":"MD5"} …]'
   https://graph.facebook.com/{audience_id}/users?access_token=___

There is no max on the total number of users that can be added to an audience, but up to 1000 users can be added at a given time.

If the addition of the user succeeds, the API call will return true.

Note: It may take up to 1 hour before the users are added to the audience.

Deleting users from an Audience

 DELETE /{audience_id}/users/
 users=[{…}]

Getting details about an audience

 curl -F https://graph.facebook.com/{audience_id}?access_token=___

Sample response:

 Response
 {
   "id": "6004192254512",
   "account_id": 38847137,
   "name": "customaudience",
   "parent_category": "Custom",
   "type": 4,
   "type_name": "Advertiser Generated",
   "time_updated": 1348480901,
   "approximate_count": 20,
   "status": "ready",
   "subtype": 0,
   "subtype_name": "REGULAR"
 }

Fields

Name	Description	Type
id	The ID of this category	long
account_id	The ID of ad account which this audience belongs to	long
approximate_count	Approximate number of people in this audience	int
lookalike_audience_ids	The IDs of the lookalike audiences generated from this audience	array
name	The name of this audience	string
parent_audience_id	Parent audience ID; set this field if audience hierarchy is desired	long
parent_category	Type of the parent audience weather it is custom audience (e.g. Custom), partner category (e.g. Acxiom) or broad category (e.g. Activities)	string
status	Current status of the audience (e.g. ready, waiting, error)	string
subtype	Subtype of the custom audience (e.g. 0->custom audience, 2->lookalike audience)	string
subtype_name	Subtype of the custom audience (e.g. Regular->custom audience, Lookalike->lookalike audience)	string
type	User cluster type (e.g. 4->custom audience, 6->broad categories)	string
type_name	Name of the cluster type (e.g. Advertiser generated->custom audience, BCT->broad categories)	string
time_updated	Last time this audience was updated	long

 

Using Custom Audiences in Targeting

Targeting

Custom Audiences can be used alongside existing Broad Categories

targeting:{
  'countries':['US'],
  'user_adclusters':[{'id':6002714885172,'name':'Cooking'}],
  'custom_audiences':[{'id':6004192254512,'name':'customaudience'}]}

Exclusion Targeting

Advertisers can exclude a custom targeting audience from seeing an Ad or Sponsored Story as follows:

 targeting:{
      "countries":["US"],
      "age_min":25,
      "age_max":40,
      "excluded_custom_audiences":
        [{"id":"6004192254512","name":"customaudience"}],
      "broad_age":false
  }

Using conjunctive AND targeting

See the Advanced targeting section of the targeting spec doc.

Constructing a Hash of an email

You can choose to send us only the MD5 hash or compute both the MD5 and the CRC32 and combine them together in the format CRC32_MD5. The former is preferred.

• Normalize the email address. Trim leading and trailing whitespace, and convert all characters to lowercase.
• Compute the CRC32 value for the normalized email address and use the unsigned integer representation of this value. (Note that some implementations return signed integers, in which case you will need to convert that result to an unsigned integer.)
• Compute the MD5 value for the normalized email address and use the hex representation of this value (using lowercase for A through F).
• Combine these two value with an underscore. For example, the address mary@example.com converts to 4228600737_c96da02bba97aedfd26136e980ae3761

Normalization function example (PHP):

 trim(utf8_strtolower($email), " \t\r\n\0\x0B.");

The hash is a construct with the following format:

 CRC32(normalized email) . '_' . MD5(normalized_email) 

Constructing a Hash of a phone number

• Normalize the phone number by removing any symbols, letters, and any leading zeroes.
• Compute the CRC32 and MD5 values in the same way as for emails and combine the two values with an underscore. For example, the phone number 15559876543 converts to 2432411640_16e811712f42e84af0e87d5d6c4e5e02

View Tags

Atlas View Tags

Atlas view tags are supported on ads targeting custom audiences, partner categories, and lookalike audiences.

• View tags from all approved providers are still allowed with exclusion targeting of custom audiences or lookalikes.
• Other view tag providers are still blocked from adding view tags to ads targeting custom audiences, partner categories, and lookalike audiences.

Implementation details

• Create the custom audiences as you have been. When you select an audience or partner category for targeting an ad, you'll now be able to apply Atlas view tags to that ad.
• Set up and implement view tags using the same processes and interfaces that you normally use to implement your Atlas tags. Previously, the system would not let you combine custom audience targeting with view tag tracking. Now the system will let you to combine these as you do on any other ad.

Click Tags

Click tags from all approved providers are allowed with these targeting options and will continue to be allowed.