Customer File Custom Audiences

The Marketing API allows you to build 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.

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 improve how advertisers create and manage their audiences, Customer File Custom Audiences that have not been used in any active ad sets in over two years will be flagged for deletion on a rolling basis. You will need to provide us with your instructions before we take any action. Once audiences are moved to the “Expiring Audience” stage and flagged, you will need to provide your instructions by either using the flagged audience in an active ad set, which we will consider an instruction to retain the audience, or by deciding not to use the flagged audience in an active ad set, which we will consider an instruction to delete the audience. For more information, see the Custom Audiences Overview documentation.

Build a Custom Audience

Step 1: Create an Empty Custom Audience

Specify subtype=CUSTOM and customer_file_source in your API call.

curl -X POST \
  -F 'name="My new Custom Audience"' \
  -F 'subtype="CUSTOM"' \
  -F 'description="People who purchased on my website"' \
  -F 'customer_file_source="USER_PROVIDED_ONLY"' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/customaudiences

'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const AdAccount = bizSdk.AdAccount;
const CustomAudience = bizSdk.CustomAudience;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<AD_ACCOUNT_ID>';
const api = bizSdk.FacebookAdsApi.init(access_token);
const showDebugingInfo = true; // Setting this to true shows more debugging info.
if (showDebugingInfo) {
  api.setDebug(true);
}

const logApiCallResult = (apiCallName, data) => {
  console.log(apiCallName);
  if (showDebugingInfo) {
    console.log('Data:' + JSON.stringify(data));
  }
};

let fields, params;
fields = [
];
params = {
  'name' : 'My new Custom Audience',
  'subtype' : 'CUSTOM',
  'description' : 'People who purchased on my website',
  'customer_file_source' : 'USER_PROVIDED_ONLY',
};
const customaudiences = (new AdAccount(id)).createCustomAudience(
  fields,
  params
);
logApiCallResult('customaudiences api call complete.', customaudiences);

require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\AdAccount;
use FacebookAds\Object\CustomAudience;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

$access_token = '<ACCESS_TOKEN>';
$app_secret = '<APP_SECRET>';
$app_id = '<APP_ID>';
$id = '<AD_ACCOUNT_ID>';

$api = Api::init($app_id, $app_secret, $access_token);
$api->setLogger(new CurlLogger());

$fields = array(
);
$params = array(
  'name' => 'My new Custom Audience',
  'subtype' => 'CUSTOM',
  'description' => 'People who purchased on my website',
  'customer_file_source' => 'USER_PROVIDED_ONLY',
);
echo json_encode((new AdAccount($id))->createCustomAudience(
  $fields,
  $params
)->exportAllData(), JSON_PRETTY_PRINT);

from facebook_business.adobjects.adaccount import AdAccount
from facebook_business.adobjects.customaudience import CustomAudience
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_ACCOUNT_ID>'
FacebookAdsApi.init(access_token=access_token)

fields = [
]
params = {
  'name': 'My new Custom Audience',
  'subtype': 'CUSTOM',
  'description': 'People who purchased on my website',
  'customer_file_source': 'USER_PROVIDED_ONLY',
}
print AdAccount(id).create_custom_audience(
  fields=fields,
  params=params,
)

import com.facebook.ads.sdk.*;
import java.io.File;
import java.util.Arrays;

public class SAMPLE_CODE_EXAMPLE {
  public static void main (String args[]) throws APIException {

    String access_token = \"<ACCESS_TOKEN>\";
    String app_secret = \"<APP_SECRET>\";
    String app_id = \"<APP_ID>\";
    String id = \"<AD_ACCOUNT_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new AdAccount(id, context).createCustomAudience()
      .setName(\"My new Custom Audience\")
      .setSubtype(CustomAudience.EnumSubtype.VALUE_CUSTOM)
      .setDescription(\"People who purchased on my website\")
      .setCustomerFileSource(CustomAudience.EnumCustomerFileSource.VALUE_USER_PROVIDED_ONLY)
      .execute();

  }
}

require 'facebook_ads'

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_ACCOUNT_ID>'

FacebookAds.configure do |config|
  config.access_token = access_token
  config.app_secret = app_secret
end

ad_account = FacebookAds::AdAccount.get(id)
customaudiences = ad_account.customaudiences.create({
    name: 'My new Custom Audience',
    subtype: 'CUSTOM',
    description: 'People who purchased on my website',
    customer_file_source: 'USER_PROVIDED_ONLY',
})

Parameters

Step 2: Specify a List of Users

Use a POST API call to the /{audience_id}/users endpoint to specify the list of users you want to add to your Custom Audience.

Parameters

{
  "session_id":9778993, 
  "batch_seq":10, 
  "last_batch_flag":true, 
  "estimated_num_total":99996 
} 

{ 
  "schema":"EMAIL_SHA256", 
  "data":
    [
      ["<HASHED_DATA>"], 
      ["<HASHED_DATA>"], 
      ["<HASHED_DATA>"] 
    ]
}

Data Processing Options for US Users

{
   "payload": {
       "schema": [
           "EMAIL",
                    "DATA_PROCESSING_OPTIONS"
       ],
       "data": [
           [
               "<HASHED_DATA>
",
                           []
           ]
       ]
   }
}

{
   "payload": {
       "schema": [
           "EMAIL",
                    "DATA_PROCESSING_OPTIONS"
       ],
       "data": [
           [
               "<HASHED_DATA>
",
                           ["LDU"]
           ]
       ]
   }
}

{
    "customer_consent": true,
    "payload": {
        "schema": [
            "EMAIL",
            "DATA_PROCESSING_OPTIONS",
            "DATA_PROCESSING_OPTIONS_COUNTRY",
            "DATA_PROCESSING_OPTIONS_STATE"
        ],
        "data": [
            [
                "<HASHED_DATA>",
                ["LDU"],
                1,
                1000
            ]
        ]
    }
}

session Fields

Response

A successful response includes a JSON object with the following fields:

Learn more about sharing your Custom Audience with business objects.

Remove Audience Members

Use a DELETE API call to the /{audience_id}/users endpoint to specify the list of users you want to remove from your Custom Audience.

curl -X DELETE \
  --data-urlencode 'payload={ 
    "schema": "EMAIL_SHA256", 
    "data": [ 
      "<HASHED_DATA>", 
      "<HASHED_DATA>", 
      "<HASHED_DATA>" 
    ] 
  }' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<VERSION>/<CUSTOM_AUDIENCE_ID>/users

Or, you can add the method parameter 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 endpoint.

There may be some reasons why this information is not processed. For example, if the ad account is not owned by a business portfolio, you have not yet accepted the Custom Audience Terms, or the information does not match with a user.

To remove an Accounts Center account, 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

Multi-Key Matching

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 don't 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.

Add Users with Multi-Key Matches

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

Using 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

Hashing and Normalization for Multi-Key

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 alphabets. For the best match results, provide the Roman alphabet translation with no special characters.

Hashing

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 emails and phone numbers.

External Identifiers

You can match people for an audience with your own identifiers, known as External Identifiers (EXTERN_ID). This can be any unique ID from the advertiser, such as loyalty membership IDs, user IDs, and external cookie IDs.

For better matching, you should also use the exact 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.

You can reuse the EXTERN_ID mapping to build customer file custom 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

Replace Users API

The /<CUSTOM_AUDIENCE_ID>/usersreplace endpoint allows you to perform 2 actions with one API call:

• Completely remove existing users from a specific audience
• Replace those users with a new set of users.

Using the /<CUSTOM_AUDIENCE_ID>/usersreplace endpoint allows you to automatically delete all existing users rather than having to upload a list of users you want to delete. This endpoint does not reset your ad set's learning phase when an audience is part of active ad sets unlike POST or DELETE API calls to the /<CUSTOM_AUDIENCE_ID>/users endpoint.

The Replace Users API only works with audiences that meet the following requirements:

• The number of users in place before running a replace process must be smaller than 100 million. If your audience is larger than 100 million, we suggest leveraging the /<CUSTOM_AUDIENCE_ID>/users endpoint to add and remove users.
• Subtype must be set to CUSTOM.
• You cannot replace a value-based customer file custom audience with a non-value based customer file custom audience, or vice-versa.

Get Started

Before you start a replace process, we recommend the following:

• Make sure your audience’s operation_status is Normal.

• Don't add or remove users via /<CUSTOM_AUDIENCE_ID>/users during an ongoing replace operation via /<CUSTOM_AUDIENCE_ID>/usersreplace. If you try performing a second replace operation before the first is completed, you will receive a message indicating a replace operation is already in progress.

• The maximum duration window for 1 replace session is 90 minutes. The API will reject any batches for a session received after 90 minutes from the time the session started. If you need to send batches for a duration longer than 90 minutes, wait until the replace operation for that session is done, then use the /<CUSTOM_AUDIENCE>/users endpoint’s add operation for the rest of your uploads.

• Once your audience is ready, specify the list of users you want to replace with your custom audience using a POST call to /<CUSTOM_AUDIENCE_ID>/usersreplace.

  • Once you start the replacement progress, your audience’s operation_status switches to replace_in_progress.
  • If your replacement operation is incomplete, your audience’s operation_status switches to replace_error.

Call Parameters

You can include the following parameters in your POST call to /<CUSTOM_AUDIENCE_ID>/usersreplace:

{
  'session_id':9778993, 
  'batch_seq':10, 
  'last_batch_flag':true, 
  'estimated_num_total':99996 
}

{ 
  "schema":"EMAIL", 
  "data":["<HASHED_EMAIL>", "<HASHED_EMAIL>", "<HASHED_EMAIL>" ]
}

Session Fields

Payload Fields

Once you make your POST request, you get a response with the following fields:

Replace API Common Errors

All errors returned from the Replace endpoint have error code 2650. Here are some of the most common error subcodes returned, as well as guidance on how to resolve them.

Resources

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 Meta 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 the Facebook app.

• 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.

See Also

• Custom Audience
• Custom Audience Users
• Custom Audience Session
• Custom Audience Terms Of Service