Skip to main content

Overview

The Meta Ads connector provides a convenient way of exporting data directly, as a customer list audience, from the Decentriq platform to Meta Ads Manager. The dataset contains one identifier per row, of the identifier type chosen for the export: SHA256 hashed email addresses, SHA256 hashed phone numbers, or mobile advertising IDs.

Prerequisites

  • Have a Meta Ads account with a valid account ID and access token.
  • Creating an audience does not require any prior input in the Ads Manager Portal.
  • Email addresses and phone numbers have to be normalized and hashed with SHA256 before the dataset is uploaded. The connector does not hash any values.

Identifier types​

Identifier typeValuesPrepare before uploading
Email (SHA256 hashed)SHA256 hash of the email address, as hexadecimalStrip leading and trailing whitespace and convert the address to lowercase, then hash it.
Phone number (SHA256 hashed)SHA256 hash of the phone number, as hexadecimalKeep only the digits, include the country code and drop leading zeros (+41 079 123 45 67 becomes 41791234567), then hash it.
Mobile advertising ID (MAID)Apple IDFA or Android AAID, in UUID format with hyphensUpload as-is. Do not hash.

Meta matches on the hash of the normalized value, so hashing an un-normalized email address or phone number lowers the match rate. Before uploading to Meta, the connector strips leading and trailing whitespace from every value, converts it to lowercase and skips empty rows. It does not change values in any other way.

Dataset requirements​

  • Exactly one column. A row containing more than one value fails the whole export. If a value can contain a comma, quote it.
  • No header row. The first line of the file is treated as data, so a header such as email would be uploaded as an identifier.
  • One identifier type. All rows must contain the identifier type chosen for the export.

Access token prerequisites​

For pushing custom audiences to the Meta Marketing API, your access token needs the following scopes:

  1. ads_management - Required for creating and managing custom audiences
  2. business_management - Allows access to business assets and accounts
  3. ads_read - Enables reading advertising data (recommended for verification)
  4. public_profile - Basic account information (usually included by default)
  5. email_marketing - Required for creating custom audiences from customer lists

API access tokens alone aren't enough - the user account associated with the token must also have the correct permission level assigned within the Meta Business Manager interface. Here's what this means:

  1. Business Manager Roles: The user needs at least an "Admin" or "Advertiser" role on the Business Manager account.
  2. Ad Account Permissions: The user needs specific permissions on the Ad Account where audiences are being created:
    • "Manage campaigns" permission
    • "Manage ads" permission
    • "Manage audiences" permission

Step-by-step guide

  1. Follow the steps to select a dataset for export and choose Meta Ads from the list of connectors.

  2. Input the requisite information:

    • Audience name: Name of the audience to be exported to Meta Ads.
    • Identifier type: Type of the identifiers in the dataset, see Identifier types.
    • Account ID: ID of the Meta Ads account to export data to.
    • Access token: Meta Ads access token for exporting data.

  3. After clicking the Export button navigate to the Imports/Exports tab on the Datasets page to track the status of the export.

  4. Once completed, open Meta Ads Manager to verify the created audience.

    1. Go to https://adsmanager.facebook.com/adsmanager/audiences (or select the “Audiences” button in the vertical bar on the left).
    2. Make sure the correct Ads Manager account is selected in the dropdown menu in the top left.
    3. The audience exported from the DCR will be shown in the list of audiences.
note

If the ad account already has a customer list audience with the same name, the export replaces the users of that audience instead of creating a new one. If several audiences share the name, the most recently updated one is replaced. Choose a different audience name to create a new audience. Meta can take up to 24 hours to finish replacing the users of an audience, and an export to that audience fails until it has finished.

Rejected identifiers

Meta reports how many of the uploaded identifiers it received and how many it rejected as invalid, for example because they are not hashed. If Meta rejects more than 25% of the identifiers, the export fails. Otherwise the export completes, and the number of rejected identifiers is shown as a warning in the details of the export on the Imports/Exports tab. If Meta reports receiving fewer identifiers than were uploaded, the export completes with a warning as well. If Meta's response with the counts is lost, the connector reads them from Meta's record of the upload; only if that fails too does the export complete with a warning that the counts are unavailable.

If an export fails after the upload has started, Meta replaces the users of the audience with the identifiers uploaded so far, and its previous users are removed. The error message names the audience and says how many identifiers were uploaded.