Choosing and Implementing Facebook Marketing API Custom Audiences

Decision Point & Constraints

\n

You need to upload customer data to Facebook's Custom Audiences but must decide which audience type to use, ensure identifiers hash correctly, and verify the match rate. Choosing the wrong audience type or mishandling hashing can result in audience rejection, low match rates, or policy flags.

\n

Constraints

\n

\n
• Hashed identifiers must use SHA256 with proper salt per Facebook spec.
\n
• Policy compliance required; mismatched data can lead to audience rejection.
\n
• Rate limits: 100 custom audiences per ad account, with API call throttling.
\n

\n

Supported Options Comparison

\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

Audience Type	Data Source	Hashing Requirement	Rate Limit	Typical Use Case
Customer List	Email, phone, other CRM fields	SHA256 of raw value + salt	100 total per ad account	Offline sales, CRM retargeting
App Activity	In-app events, user IDs	MD5 or SHA256 per Facebook SDK spec	100 total per ad account	Re‑engage dormant users
Website Traffic	Browser cookies, pixel data	No user‑level hash; relies on pixel matching	100 total per ad account	Retarget website visitors

\n

Trade‑offs Explained

\n

Customer List offers the most direct control over who sees your ads based on your own CRM data, but requires correct hashing and sufficient record volume for meaningful match rates. App Activity is ideal for re‑engaging users within your app ecosystem without exposing raw identifiers, but depends on the app SDK correctly reporting events. Website Traffic relies on Facebook's pixel and cookie matching, which works well for anonymous browsing behavior but cannot target specific individuals by contact detail. Choose the type that matches your data source and targeting goals.

\n

Concrete Implementation: Creating a Customer List via the Marketing API

\n

To create a Customer List, you first hash each identifier. Facebook requires the raw value lowercased, trimmed, and then SHA256‑hashed with a salt that is unique to your application or business unit. The resulting hash is prefixed with 'sha256' in the API payload.

\n

Where to run

\n

On any machine with curl or an HTTP client and a valid Facebook access token with ads_management or business_management permissions.

\n

Required permissions

\n

ads_management (for ad account) or business_management (for Business Manager context).

\n

Meaningful placeholders

\n

\n
• {ad_account_id} – the numeric or string ID of the ad account (e.g., 1234567890).
\n
• {access_token} – a long‑lived token with appropriate scopes.
\n
• {salt} – your application‑specific salt string (not sent to Facebook, used locally before hashing).
\n

\n

Example request (do not run without valid credentials)

\n

curl -X POST \
  -F 'name=Customer List' \
  -F 'subtype=CLIENT_EMAIL' \
  -F 'data=[{'hash': 'sha256:HASHED_VALUE'}]' \
  -F 'access_token={access_token}' \
  'https://graph.facebook.com/v20.0/act_{ad_account_id}/customaudiences'

\n

Validation & Checking Results

\n

After the request, navigate to Ads Manager → Audiences → Your new list. The matching status column shows the percentage of uploaded records that Facebook successfully matched to user profiles. Compare this percentage with the expected match rate documented by Facebook for your industry and data quality.

\n

You can also call the Marketing API to fetch the audience:

\n

GET https://graph.facebook.com/v20.0/{audience_id}

\n

The response includes status, subtype, and approx_size. A status of ACTIVE indicates the audience is ready for use.

\n

Limitations & Practical Verification

\n

\n
• Quota: 100 custom audiences per ad account. To create more, archive or delete existing ones.
\n
• Rate throttling: Facebook may return 4 with a Retry-After header; implement exponential backoff and honor that header.
\n
• Hashing compliance: Only SHA256 with the prescribed salt format is accepted. Using plain SHA256 without salt, or different encoding, will cause rejection.
\n
• Policy: Audiences must meet minimum size thresholds (typically 20‑100 matched users) and must use data collected with proper consent.
\n

\n

Practical verification: After upload, always cross‑check the matched size in Ads Manager against your uploaded count. If the match rate falls below 20 %, revisit the hashing pipeline (salt format, character case, encoding). Facebook’s developer documentation specifies that emails should be lowercased before hashing; phone numbers should be normalized to E.164 format without dashes or spaces before hashing.