Skip to main content

Meta Audiences

Meta Audiences lets you keep a Meta (Facebook/Instagram) Custom Audience in sync with a dataset of user identifiers from your warehouse — for example hashed emails, phone numbers, or mobile advertiser IDs — so you can retarget or exclude those users in your ad campaigns.

Introduction to Meta Audiences​

  • Goal: keep a Meta Custom Audience up to date with your upstream audience table.
  • How it works (high level): on each sync, Extract reads the rows produced by your stream and calls the Meta Custom Audience Users API — rows marked Added/Changed are added to the audience, and rows marked Removed are removed from it.
  • Official Meta docs: Custom Audiences API.

Setup Guide​

  • Connection: authenticate the Meta Audiences destination using Meta OAuth, granting Extract permission to manage Custom Audiences on your ad account(s).
  • Ad Account (required): the Account ID dropdown is dynamically populated from the ad accounts available to your authenticated Meta user. All audiences created/updated by this destination live under the selected ad account.
  • Audience name (optional, per stream): if set, Extract uses this as the name of the Meta Custom Audience; otherwise it falls back to the stream title.
    • Extract looks for an existing writable audience (subtype CUSTOM) with that name in the selected ad account and reuses it, creating a new one only if none exists.
    • If more than one writable audience shares that name, the sync fails — audience names must resolve to a single writable audience.
  • Data contract (required): every stream connected to this destination must have a data contract attached. Pick the contract below that matches the identifiers available in your source data.

Required and optional fields​

Every contract includes a required diff_result column with allowed values Added, Changed, or Removed, which determines whether a row is added/updated or removed from the audience.

Data contractFieldsRequired / optional
custom_audience_emailEMAIL_SHA256Required
custom_audience_phonePHONE_SHA256Required
custom_audience_mobile_advertiser_idMOBILE_ADVERTISER_IDRequired
custom_audience_multikey (Multiple identifier custom audience)EXTERN_ID, EMAIL, PHONE, GEN, DOBY, DOBM, DOBD, LN, FN, FI, CT, ST, ZIP, MADID, COUNTRYAll optional — include whichever identifiers you have. Provide at least one per row for the record to be useful for matching.

Validation rules enforced for the multi-identifier contract:

  • GEN (gender) must be m or f.
  • DOBY (birth year) must be 4 digits, DOBM (birth month) between 1–12, DOBD (birth day) between 1–31.
  • ST (state) and COUNTRY must be 2-character codes.

Troubleshooting common issues​

  • Authentication errors: re-run the Meta connection flow and make sure you complete every consent step, and that the Meta user still has access to the ad account.
  • Ad account not appearing in the dropdown: confirm the ad account is part of the Meta account you authenticated with (/me/adaccounts).
  • "Found multiple writable Meta audiences named ..." error: two or more CUSTOM audiences share the configured audience name in that ad account. Rename one of them in Meta, or choose a unique Audience name for the stream.
  • Stream not connected to a data contract: this destination requires a data contract on the stream; attach one of the contracts listed above before syncing.
  • Audience not updating: verify the stream is pointed at the correct ad account and audience name, and that upstream Added/Changed/Removed rows are actually being produced.
  • Identifier formatting and hashing issues: for GEN, DOBY, DOBM, DOBD, ST, and COUNTRY, make sure values meet the format rules above — invalid values fail the sync.

Hashing and normalization​

  • When Apply hashing (SHA256) is enabled, Extract trims and lowercases email-style identifiers before hashing.
  • Phone identifiers are normalized by stripping non-digit characters and leading zeroes before hashing.
  • If you choose Source values are already hashed, normalize the values according to the rules above before hashing them upstream.
  • More detail: Identifier Hashing and Normalization.

Data Contract Information​

custom_audience_email​

Loading ....

custom_audience_mobile_advertiser_id​

Loading ....

custom_audience_multikey​

Loading ....

custom_audience_phone​

Loading ....