POST to /act_AD_ACCOUNT_ID/customaudiences with name, subtype set to CUSTOM, and customer_file_source (e.g. USER_PROVIDED_ONLY).
Capture the audience id returned and prepare your customer list with PII fields normalized and SHA-256 hashed according to Meta's requirements (email lowercase + trimmed, phone in E.164).
POST to /{AUDIENCE_ID}/users with a schema array describing the data columns (e.g. ['EMAIL', 'PHONE']) and a data array of hashed value tuples.
Batch uploads into chunks of up to 10,000 rows per request to stay within API limits.
Poll the audience's operation_status field via GET /{AUDIENCE_ID}?fields=operation_status,approximate_count until status is Normal.
Use the audience id in ad set targeting by adding it to the included_custom_audiences array in the targeting spec.
Known gotchas
Audiences with fewer than 100 matched users cannot be used for targeting; the approximate_count will show 0 until the minimum threshold is met.
Data must be hashed client-side before sending — Meta's API does not perform hashing on ingestion; sending plaintext will result in zero matches.
Custom audiences expire after a configurable inactivity period; re-upload or refresh data regularly to keep audiences active.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp