Marketing API Version

Custom Audiences

Custom Audience from a customer list is a type of audience you can create made up of your existing customers. You can target ads to the audience you've created on Facebook, Instagram, and Audience Network.

You give us your hashed customer list by uploading it, or by integrating with your CRM with Marketing API. For the upload option in Ads Manager or Power Editor for Custom Audiences, see Help Center, What's a Custom Audience

Build an Audience

As the owner of CRM data and other business data, you will be responsible for creating and managing this data. To create an audience, you will share your data in an encrypted format to maintain privacy. Facebook compares your encrypted data with encrypted data on our side to see if we can add someone to an audience for your ad.

The accepted method for hashing is SHA256. Other hashing mechanisms are not supported.

1. First normalize keys for your data, see Custom Audiences, Hashing.

2. Then hash your contact data, for example:

hash("sha256", "mary@example.com")

Returns the hashed result:

f1904cf1a9d73a55fa5de0ac823c4403ded71afd4c3248d00bdcd0866552bb79

3. Create a custom audience. For example:

curl \
  -F 'name=My new CA' \
  -F 'subtype=CUSTOM' \
  -F 'description=People who bought from my website' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.5/act_<AD_ACCOUNT_ID>/customaudiences

On success, the Custom Audiences API returns a new custom_audience_ID.

4. Add your user data to the audience. Make a call to {custom_audience_ID}/users with your normalized, hashed data. For example:

curl \
  -F 'payload={ 
    "schema": "EMAIL_SHA256", 
    "data": [ 
      "83b1fe0afe7e25f11db408baf85f5acea6c9381049619b75909bef957373ff83", 
      "24bf0dd10ca4df1cdd5dcd07b503f5468f74cc145d0451517bd9892af0dd5728", 
      "caa0190ae6bf9c6c77cb57a2c249122039a8d687e4ab8c88479c2cbe858dfe82" 
    ] 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.5/<CUSTOM_AUDIENCE_ID>/users

Facebook compares your data with our encrypted user data. If we find a match, we can add people to your Facebook Ads custom audience and deliver ads to them. A successful return result looks like this:

Struct {
audience_id: numeric string,
session_id: numeric string,
num_received: int32,
num_invalid_entries: int32,
invalid_entry_samples: Map {
string: string
},
}

The num_invalid_entries indicates a number of users that did not match and are not in the custom audience. This number is not exact but represent the number range of users which do not match.

Opting-Out Users

If a person has opted out of being targeted, you must remove the person from all custom audiences containing this person. To do so, you can send us the person and Facebook will delete them from all audiences that you own so that you don't have to remember which audience this person is a part of.

To opt-out a person from audience after they have clicked through to your opt-out URL, make an HTTP DELETE call to

https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/usersofanyaudience

with the same fields as in user update.

This will remove the people you specify from ALL custom audiences belonging to the specified ad account.

Obtain User Ad Accounts

If you want to fetch a list of all the ad account IDs associated with the current user you can use this URL:

GET /me/adaccounts HTTP/1.1
Host: graph.facebook.com
curl https://graph.facebook.com/me/adaccounts

or

GET /<USER_ID>/adaccounts HTTP/1.1
Host: graph.facebook.com
curl https://graph.facebook.com/<USER_ID>/adaccounts

Examples

More examples can be found here.

You might also be interested in:

API details are documented here, important points from this document are: