Our API allows you to build the target Custom Audiences from customer information. This includes email addresses, phone numbers, names, dates of birth, gender, locations, App User IDs, Page Scoped User IDs, Apple's Advertising Identifier (IDFA), or Android Advertising ID.
As the owner of your business' data, you are responsible for creating and managing this data. This includes information from your Customer Relationship Management (CRM) systems. To create audiences, you must share your data in an hashed format to maintain privacy. See Hashing and Normalizing Data. Facebook compares this with our hashed data to see if we should add someone on Facebook to your ad's audience.
You can add an unlimited number of records to an audience, but only up to 10000 at a time. Changes to your Custom Audiences don't happen immediately and usually take up to 24 hours. The number of records you request to remove and/or the number of Custom Audiences your account contains will increase the amount of time it takes to process this request.
To build a custom audience:
Specify subtype=CUSTOM
and customer_file_source
:
Name | Description |
---|---|
type: enum string | Describes how the customer information in your Custom Audience was originally collected. Possible values include:
|
type: string | Custom Audience name |
type: string | Custom Audience description |
type: string | Type of Custom Audience |
To specify the list of users you want to add to your custom audience, POST
to the /{audience_id}/users
endpoint. Add the following parameters:
Parameter | Description |
---|---|
type: JSON Object | Required. Use If you have an upload with more than 10000 users, you need to split it into separate batches —each request can take up to 10000 users. For example: { "session_id":9778993, "batch_seq":10, "last_batch_flag":true, "estimated_num_total":99996 } |
type: JSON Object | Required. Includes two fields: For example: { "schema":"EMAIL_SHA256", "data": [ "<HASHED_DATA>", "<HASHED_DATA>", "<HASHED_DATA>" ] } |
Inside session
, include the following fields:
Parameter | Description |
---|---|
type: positive 64 bits integer | Required. Identifier used to track the session. This number must be:
|
type: positive integer | Required. A number to identify the request listed in the current session. This number must be:
|
type: boolean | Required. If set to |
type: integer | Optional. Estimated total number of users to be uploaded in this session. This is used to improve this session's processing. |
A successful return includes a JSON object with the following fields:
Field | Description |
---|---|
type: numeric string | Audience identifier. |
type: integer | The session ID you passed in. |
type: integer | Total number of users received in this session so far. |
type: integer | Indicates the number of entries sent with incorrect hashing. Those entries did not return a match and are not added to the custom audience. This is not an exact number, but it represents the number range of users that did not match. |
type: JSON Array of String or Map { string: string } | Up to 100 samples of invalid entries found in the current request. |
Share your custom audience with business objects. Learn more here.
Use the same data you used to create an audience. Use the DELETE
method, instead of POST
.
curl -X DELETE \ --data-urlencode 'payload={ "schema": "EMAIL_SHA256", "data": [ "<HASH>", "<HASH>", "<HASH>" ] }' \ -d 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/<VERSION>/<CUSTOM_AUDIENCE_ID>/users
Or you can add a parameter called method
and set it to DELETE
in the POST
request used to add audience members.
You can remove people from a list with EXTERN_ID
, if available:
curl -X DELETE \ --data-urlencode 'payload={ "schema": "EXTERN_ID", "data": [ "<ID>", "<ID>", "<ID>" ] }' \ -d 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/<VERSION>/<CUSTOM_AUDIENCE_ID>/users
You can remove a list of people from all Custom Audiences across your ad account using this end point.
There may be some reasons why this information is not processed. For example if the ad account is not owned by a business account, you have not yet accepted the Custom Audience Terms, or the information does not match with a user.
To remove a person, include the same fields as in user update and make a HTTP DELETE
call to:
https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/usersofanyaudience
To increase the match rate for your records, provide multiple keys in an array of individual keys, for example [EXTERN_ID
, LN
, FN
, EMAIL
]. While you do not need to hash EXTERN_ID
, you must hash all personally identifying information, such as emails and names. For details see Hashing and Normalizing Data.
You can provide some or all multi-keys for a record. For details, see multi-key extern id matching.
curl \ -F 'payload={ "schema": [ "FN", "LN", "EMAIL" ], "data": [ [ "<HASH>", "<HASH>", "<HASH>" ], [ "<HASH>", "<HASH>", "<HASH>" ] ] }' \ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/<VERSION>/<CUSTOM_AUDIENCE_ID>/users
PAGEUID
If you use the PAGEUID
key, you must also include a list of Page IDs. You can only send us one PAGEUID
, which should be an array with one element.
curl -X POST \ -F 'payload={ "schema": [ "PAGEUID" ], "is_raw": "true", "page_ids": [ "<PAGE_IDs>" ], "data": [ [ "<HASH>", "<ID>", "<ID>", "<VALUE>" ], [ "<HASH>", "<ID>", "<ID>", "<VALUE>" ], [ "<HASH>", "<ID>", "<ID>", "<VALUE>" ] ] }' \ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/<VERSION>/<CUSTOM_AUDIENCE_ID>/users
You must hash data as SHA256
. We don't support other hashing mechanisms. This is required for all data except External Identifiers, App User IDs, Page Scoped User IDs and Mobile Advertiser IDs.
Before you hash your data, normalize it so we can handle it. Only First name FN
and Last Name LN
support special characters and non-Roman alphabet. For best match results, provide the Roman alphabet translation with no special characters.
Key | Guidelines |
---|---|
criteria: email addresses | Hashing required. Trim leading, trail white space, and convert all characters to lowercase. |
criteria: phone numbers | Hashing required. Remove symbols, letters, and any leading zeroes. You should prefix the country code if |
criteria: gender | Hashing required. Use these values: |
criteria: birth year | Hashing required. Use the |
criteria: birth month | Hashing required. Use the MM format: |
criteria: birthday | Hashing required. Use the DD format: |
criteria: last and first names | Hashing required. Use |
criteria: first name initial | Hashing required. Use |
criteria: U.S. states | Hashing required. Use the 2-character ANSI abbreviation code, lowercase. Normalize states outside U.S. in lowercase, no punctuation, no special characters, no white space. |
criteria: city | Hashing required. Use |
criteria: zip code | Hashing required. Use lowercase, no white space. Use only the first 5 digits for U.S. Use Area/District/Sector format for the UK. |
criteria: country code | Hashing required. Use lowercase, 2-letter country codes in ISO 3166-1 alpha-2. |
criteria: mobile advertiser ID | Hashing NOT required. Use all lowercase, keep hyphens. |
Provide SHA256
values for normalized keys and HEX
representations of this value, using lowercase for A through F. The hash function in PHP converts normalized email and phone number:
example | result |
---|---|
| f1904cf1a9d73a55fa5de0ac823c4403ded71afd4c3248d00bdcd0866552bb79 |
| 1ef970831d7963307784fa8688e8fce101a15685d62aa765fed23f3a2c576a4e |
You can match people for an audience with your own identifiers, known as External Identifiers or EXTERN_ID
. This can be any unique ID from the advertiser, such as loyalty membership IDs, user IDs, and external cookie IDs.
While you do not need to hash this ID, you must hash all Personally Identifying Information (PII) that you send with the EXTERN_ID
s.
Read about other parameters you can pass in the Advanced matching documentation.
For better matching, you should also use the exact same format when you send the IDs. For example, if you choose to hash using SHA256, make sure to use the same hashed value.
You can use these IDs as individual keys to delete people from Custom Audiences or create new Custom Audiences. This way you don't need to re-upload any other matching keys. If you tag someone with hashed personal information and EXTERN_ID
, we give EXTERN_ID
lower precedence when we match them with people on Facebook.
The data retention period for EXTERN_ID
is 90 days.
Note that you can reuse the EXTERN_ID
mapping across audiences within a single ad account.
If you have an audience of EXTERN_ID
fields in your ad account, create a new audience with just these identifiers:
curl \ -F 'payload={"schema":"EXTERN_ID","data":["<ID>","<ID>"]}' \ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/<VERSION>/<CUSTOM_AUDIENCE_ID>/users
You can also add people tagged EXTERN_ID
and with multi-key matching:
curl \ -F 'payload={ "schema": [ "EXTERN_ID", "FN", "EMAIL", "LN" ], "data": [ [ "<ID>", "<HASH>", "<HASH>", "<HASH>" ], [ "<ID>", "<HASH>", "<HASH>", "<HASH>" ], [ "<ID>", "<HASH>", "<HASH>", "<HASH>" ] ] }' \ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/<VERSION>/<CUSTOM_AUDIENCE_ID>/users
Facebook supports EXTERN_ID
parameters for individual Ad Accounts. Facebook cannot use values from one Account for any other Ad Accounts, even if the accounts belong to the same entity.
There are other types of audiences you can build and target, or share:
Custom Audiences From Your Website - Create an audience based on people who visited a specific page or made action on your website. Build an audience based on data from Facebook Pixel on your site.
Custom Audiences From Your Mobile App - Create an audience based on people who use your mobile app. Build an audience based on data from App Events.
Lookalike Audiences - Identify people you already know and advertise to similar people on Facebook.
Offline Custom Audiences - Create an audience based on people who visited your store, made calls to your customer service, or took action through other offline means.
Canvas Engagement Audiences - Create an audience that contains anyone who engaged with your Canvas.