Send data to Meta Ads Manager

Meta Ads Manager is a unified ad creation tool that your brand can use to create and publish ads to Facebook, Messenger, Instagram and the Meta Audience Network.

Your brand can send custom audiences and offline events to Meta Ads Manager:

Custom audiences

Custom audiences

Send custom audiences to help find people who already know about or have engaged with your brand. Use custom audiences for re-marketing, finding potential repeat customers, and finding lookalike audiences that can be activated from Facebook, Facebook Messenger, Instagram, and WhatsApp.

The Facebook Marketing API , specifically the Replace Users endpoint , is used to send custom audiences.

This endpoint removes existing customers from an audience without resetting your ad set’s learning phase when an audience is part of active ad sets, and then replaces those users with the list of customers that was sent to Meta Ads Manager from Amperity.

Note

Changes to audiences are not immediately available in Meta Ads Manager. Allow for up to 24 hours after the point at which Amperity has finished sending audience updates for them to be available.

Offline events

Offline events

Send offline events to Meta Ads Manager to help your brand track offline conversions from your marketing campaigns. Offline events are matched with audiences in Facebook, Facebook Messenger, Instagram, and WhatsApp.

Transaction events that occurred within the previous seven days and contain positive values for product quantity are sent to Meta Ads Manager using the Conversions API for offline events .

Important

The first time transaction events are sent to Meta Ads Manager, seven days of data is sent, after which Amperity should be configured to send daily updates, which will maintain a 7-day rolling window of transaction events.

This topic describes the steps that are required to send customer data to Meta Ads Manager from Amperity:

  1. Get details

  2. Authorize Amperity access to the customer’s account

  3. Custom audiences

  4. Offline events

How this destination works

You can build custom audiences in Meta Ads Manager. Send customer information, such as email addresses, phone numbers, names, birthdates, gender, city, state, postal code, and mobile advertising IDs, from Amperity to find customer matches on Meta Ads Manager.

Use audiences in Meta Ads Manager to advertise to customers on Facebook, Instagram, and Messenger, and to use Meta Audience Network to extend your advertising beyond Facebook to reach new audiences on apps and mobile devices, such as WhatsApp.

Build custom audiences in Meta Ads Manager using data from Amperity.

A Meta Ads Manager destination works like this:

Step one.

Use a query or segment to build a custom audience.

Step two.

Configure the Meta Ads Manager destination and data template.

Step three.

Send a test set of first-party data from Amperity, and then from within Meta Ads Manager verify that this data is available from Meta Ads Manager.

Important

The custom audience terms of service must be signed by each business user that is associated with your Facebook Ads account. If the terms of service are not signed, a permissions error will prevent Amperity from sending data to Meta Ads Manager.

Meta Ads Manager uses OAuth to grant access to Amperity. You may need to reauthorize OAuth if the token expires or is removed.

Step four.

Build ads for that audience in Meta Ads Manager.

About Meta Ads Manager

Audiences sent to Meta Ads Manager have access to Facebook, Messenger, Instagram and the Meta Audience Network.

Facebook Ads

Use Meta Ads Manager to configure a variety of ad placements across Facebook .

Instagram

Use Meta Ads Manager to configure objectives that place ads on Instagram .

Facebook Messenger

Use Meta Ads Manager to configure objectives that place ads on Messenger .

WhatsApp

Use Audience Manager to reach users who are not on Facebook or Instagram, but are on mobile apps that are within the audience network. For example, creating ads that open conversation threads in WhatsApp .

Get details

Meta Ads Manager requires the following configuration details:

Detail one.

The account ID.

Note

You may use the same credentials to send offline events.

Detail two.

The custom audience name and customer file source settings.

The custom audience name is visible from Meta Ads Manager. This name should be clear and understandable to users of Meta Ads Manager. The custom audience name will be created if it does not exist.

The customer file source specifies if the data was provided by users, provided by partners, or provided from both users and partners.

Note

The customer file source maps directly to the customer_file_source parameter in the Facebook Marketing API. This value describes how the customer information in the custom audience was originally collected:

  • USER_PROVIDED_ONLY Select this option when advertisers collected information directly from customers.

  • PARTNER_PROVIDED_ONLY Select this option when advertisers sourced information directly from partners, such as an agency or data provider.

  • BOTH_USER_AND_PARTNER_PROVIDED Select this option when advertisers collected information directly from customers and it was also sourced from partners.

Detail three.

Acccept the custom audience terms of service .

Important

Terms of service must be signed by each business user that is associated with your Facebook Ads account.

Detail four.

Authorize Amperity to send data to the customer’s Facebook Ads account. This requires activation in the Amperity Meta Ads Manager account and approval in the customer’s Meta Ads Manager account.

Note

You may need to reauthorize Amperity at various intervals.

Detail two.

Meta Ads Manager offline events only

Datasets allow you to connect and manage event data from different sources—such as from websites, mobile apps, physical store locations or business chats––from one location.

A dataset ID must be configured in Meta Ads Manager to support sending send offline events from Amperity.

A query that defines the set of offline events to be sent to Meta Ads Manager.

Terms of service

The custom audience terms of service must be signed by each business user that is associated with your Facebook Ads account. If the terms of service are not signed, a permissions error will prevent Amperity from sending data to Facebook Ads.

The permissions error is similar to:

Permissions error: To create or edit an audience with an uploaded
customer list, please agree to the Custom Audience terms at
https://business.facebook.com/ads/manage/customaudiences/tos/?act=123.

To resolve this error the terms of service must be signed by a business user who has a role in your Facebook Ads account.

Configure OAuth

OAuth is an open standard for access delegation, commonly used to grant websites or applications access to information on other websites.

Use OAuth to configure Amperity to send customer data to Meta Ads Manager.

To configure OAuth

Step 1.

Open the Destinations tab and click Add Destination. The Add Destination dialog box opens.

Select Meta Ads Manager from the Plugin drop-down, and then from the Credential drop-down, select Create a new credential.

This opens the Create New Credential dialog box.

Step 2.

In the Create New Credential dialog box, click “Generate authorization URL”.

Copy the URL, and then provide the URL to a user who has credentials that allow access to Meta Ads Manager. The user must log in and complete the steps required by the OAuth process for Meta Ads Manager.

After this is completed, you will be redirected to the Credentials page in Amperity.

Verify the credential is on the page, and then return to the Destinations tab.

Step 3.

Open the Destinations tab and click Add Destination. The Add Destination dialog box opens.

Select Meta Ads Manager from the Plugin drop-down, and then from the Credential drop-down, select the credential that is authorized to access Meta Ads Manager.

Note

The value for the Refresh Token setting is updated automatically after you select the credential.

Reauthorize Amperity

You may need to reauthorize access to Meta Ads Manager. This is necessary when an authorization token has expired or when it has been removed by someone with permission to manage access within Meta Ads Manager. To reauthorize access to Meta Ads Manager, follow the steps to configure OAuth and create a new credential.

Custom audiences

Send custom audiences to help find people who already know about or have engaged with your brand. Use custom audiences for re-marketing, finding potential repeat customers, and finding lookalike audiences that can be activated from Facebook, Facebook Messenger, Instagram, and WhatsApp.

The Facebook Marketing API , specifically the Replace Users endpoint , is used to send custom audiences.

This endpoint removes existing customers from an audience without resetting your ad set’s learning phase when an audience is part of active ad sets, and then replaces those users with the list of customers that was sent to Meta Ads Manager from Amperity.

Add destination

Configure Amperity to send customer data directly to Meta Ads Manager.

Warning

Amperity must be authorized to send data to your Meta Ads Manager account prior to configuring the destination.

To add a destination

Step 1.

Open the Destinations tab to configure a destination for Meta Ads Manager. Click the Add Destination button to open the Destination dialog box.

Name, description, choose plugin.

Enter a name for the destination and provide a description. For example: “Meta Ads Manager” and “This sends customer data to Meta Ads Manager”.

From the Plugin drop-down, start typing “face” to filter the list, and then select Meta Ads Manager.

Step 2.

Credentials allow Amperity to connect to Meta Ads Manager.

The credential type is set automatically. You may use an existing credential or you may add a new one.

Choose an existing credential or add credential.

Select an existing credential from the Credential drop-down.

– or –

Select Create a new credential from the Credential drop-down. This opens the Credential dialog box.

Choose an existing credential or add credential.

Enter the name for the credential, and then add a description.

Steps to configure OAuth

  1. Generate an authorization link, and then visit the URL that was generated to complete the authorization process.

  2. Log in to Meta Ads Manager at the generated URL using credentials that allow access to your instance of Meta Ads Manager.

    Note

    Send the URL to an individual who can provide these credentials, and then ask them to log into Meta Ads Manager on your behalf.

  3. When complete, you will be redirected to the Credentials page in Amperity.

  4. Verify the credential is on the page, and then return to the Destinations tab. From the Plugin drop-down, select the Meta Ads Manager, and then use the credential that was just created.

Step 3.

Each destination has settings that define how Amperity will deliver data to Meta Ads Manager. These settings are listed under the Settings section of the Destination dialog box.

Settings for Meta Ads Manager.

The following settings are specific to Meta Ads Manager:

Setting

Description

Custom audience name

The name of the custom audience in Meta Ads Manager.

Account ID

The account ID for your Meta Ads Manager account.

Customer file source

A setting that describes how the information in the custom audience was originally collected. Select one of the following settings:

  • USER_PROVIDED_ONLY

  • PARTNER_PROVIDED_ONLY

  • BOTH_USER_AND_PARTNER_PROVIDED

Step 4.

Business users are assigned to the Amp360 User and/or AmpIQ User policies. (Amp360 User allows access to queries and orchestrations and AmpIQ User allows access to segments and campaigns.) A business user cannot select a destination that is not visible to them.

Business users – including users assigned to the DataGrid Operator policy – may have restricted access to PII.

What is restricted access to PII?

Restricted PII access is enabled when the Restrict PII access policy option that prevents users who are assigned to that option from viewing data that is marked as PII anywhere in Amperity and from sending that data to any downstream workflow.

You can make this destination visible to orchestrations and allow users with restricted access to PII to use this destination by enabling one (or both) of the following options:

Allow business users access to this destination.

Note

To allow business users to use this destination with campaigns, you must enable the Available to campaigns option within the data template. This allows users to send campaign results from Amperity to Meta Ads Manager.

The other two settings may be configured within the data template instead of the destination.

Step 5.

Review all settings, and then click Save.

Save the destination.

Important

You must configure a data template for this destination before you can send data to Meta Ads Manager.

Add data template

A data template defines how columns in Amperity data structures are sent to downstream workflows. A data template is part of the configuration for sending query and segment results from Amperity to an external location.

About paid media campaigns

Amperity provides the right set of data to support your brand’s paid media advertising with Meta Ads Manager.

  1. Merged Customers vs. Unified Paid Media

    The Merged Customers table contains each of your customers’ best profiles.

    The Unified Paid Media table contains all your customer’s known profile data.

    Your brand will require additional data templates to use the Unified Paid Media table alongside the Merged Customers table to support paid media campaigns.

  2. Enable dedicated data templates for each table.

    Use a consistent naming pattern to label data templates that use data from the Merged Customers table. For example: “Best profile”.

    Use a consistent naming pattern to label data templates that use data from the Unified Paid Media table. For example: “Full profile”.

  3. After data templates are configured for both tables, use the default attributes component on the Campaigns page to configure which attributes will be associated with the destination, including the table from which those attributes will be pulled.

    The selected table will affect your brand’s downstream match rates and overall customer matches within your paid media campaigns. The decision behind which table to use depends on your brand’s downstream use case and the type and amount of customer profile data your brand wants to use to match customers.

    You brand should expect to see higher match rates when sending audiences from the Merged Customers table, but a higher number of matched customer profiles when sending audiences from the Unified Paid Media table. Use A/B testing to compare the results from each table, after which your brand can use the audience that works best for your campaigns.

To add a data template

Step 1.

From the Destinations tab, open the menu for a destination that is configured for Meta Ads Manager, and then select Add data template.

This opens the Add Data Template dialog box.

Step 1

Enter the name of the data template and a description. For example: “Meta Ads Manager” and “Send customer data to Meta Ads Manager.”.

Step 2.

Verify business user access to queries and orchestrations and access to segments and campaigns.

A business user may also have restricted access to PII, which prevents them from viewing and sending customer profile data.

Step 2.

If business user access was not configured as part of the destination, you may configure access from the data template.

Important

To allow business users to use this destination with campaigns, you must enable the Available to campaigns option. This allows users to send campaign results from Amperity to Meta Ads Manager.

If you enable this option, the data extension settings require using campaign name and group name template variables to associate the name of the data extension to your campaign.

Step 3.

Verify all configuration settings.

Verify settings for the data template.

Note

When the account ID, custom audience, and the customer file source settings were are not configured as part of the destination, you must configure them as part of the data template before making this destination available to campaigns.

Step 4.

Review all settings, and then click Save.

Save the data template.

After you have saved the data template, and depending on how you configured it, business users can send query results and/or send campaigns to Meta Ads Manager.

Offline events

Send offline events to Meta Ads Manager to help your brand track offline conversions that result from your marketing campaigns. Offline events may be matched with audiences in Facebook, Facebook Messenger, Instagram, and WhatsApp.

Transaction events that occurred within the previous seven days and contain positive values for product quantity may be sent to Meta Ads Manager using the Conversions API for offline events .

Important

The first time transaction events are sent to Meta Ads Manager, seven days of data is sent, after which Amperity should be configured to send daily updates, which will maintain a 7-day rolling window of transaction events.

Note

Offline events are not immediately available in Meta Ads Manager. Allow for up to 24 hours after the point at which Amperity has finished sending offline events for them to be available.

Offline events that are sent to Meta Ads Manager can be accessed from Meta Events Manager .

Build a query

Use a query to build a combination of data from the Unified Itemized Transactions and Customer 360 tables to represent the set of offline events that your brand wants to use within Meta Ads Manager.

A query that returns a collection offline events for use in Meta Ads Manager is similar to:

SELECT
  c360.amperity_id AS extern_id
  ,c360.email AS email
  ,c360.phone AS phone
  ,c360.given_name AS given_name
  ,c360.surname AS surname
  ,c360.birthdate AS birthdate
  ,c360.gender AS gender
  ,c360.city AS city
  ,c360.state AS state
  ,c360.postal AS postal
  ,c360.country AS country
  ,uit.order_id AS order_id
  ,uit.item_quantity AS quantity
  ,uit.product_id AS product_id
  ,uit.order_datetime AS timestamp
  ,CAST(uit.item_revenue / uit.item_quantity AS DOUBLE) AS price
  ,'USD' AS currency
  ,action_source AS 'physical_store'
FROM Unified_Itemized_Transactions uit
LEFT JOIN Customer_360 c360 ON uit.amperity_id = c360.amperity_id
WHERE uit.order_datetime > (CURRENT_DATE - interval '7' day)
GROUP BY order_id

The query MUST contain the following fields: extern_id, order_id, quantity, email (OR phone), product_id, timestamp, price, and currency. If action_source will default to “physical_store” when it is not specified.

You may include any of the following customer profile fields to help improve match rates in Meta Ads Manager: given_name, surname, birthdate, gender, city, state, postal, and country.

Tip

Extend the WHERE clause to filter query results by purchase channel, purchase brand, purchase quantity, and to remove items that were returned and/or cancelled.

For example:

WHERE uit.order_datetime > (CURRENT_DATE - interval '7' day)
AND uit.purchase_channel = 'channel'
AND uit.purchase_brand = "ACME Essentials"
AND uit.item_quantity > 0
AND (c360.email IS NOT NULL OR c360.phone IS NOT NULL)
AND (
    (is_cancellation IS NULL)
    OR (NOT is_cancellation)
)
AND (
    (is_return IS NULL)
    OR (NOT is_return)
)

Review the Conversions API parameters section for detailed information about the columns that must be (or may be) returned by your query.

Add destination

Configure Amperity to send customer data directly to Meta Ads Manager.

Warning

Amperity must be authorized to send data to your Meta Ads Manager account prior to configuring the destination.

To add a destination

Step 1.

Open the Destinations tab to configure a destination for Meta Ads Manager. Click the Add Destination button to open the Destination dialog box.

Name, description, choose plugin.

Enter the name of the destination and a description. For example: “Meta Ads Manager offline events” and “Send offline events to Meta Ads Manager.”.

Step 2.

Credentials allow Amperity to connect to Meta Ads Manager.

The credential type is set automatically. You may use an existing credential or you may add a new one.

Choose an existing credential or add credential.

Select an existing credential from the Credential drop-down.

– or –

Select Create a new credential from the Credential drop-down. This opens the Credential dialog box.

Meta Ads Manager requires using OAuth to authorize Amperity to send offline events to your Meta Ads Manager account.

Note

You may use the same credentials custom audiences and offline events.

Step 3.

Each destination has settings that define how Amperity will deliver data to Meta Ads Manager. These settings are listed under the Settings section of the Destination dialog box.

Settings for Meta Ads Manager offline events.

Datasets allow you to connect and manage event data from different sources—such as from websites, mobile apps, physical store locations or business chats––from one location.

A dataset ID must be configured in Meta Ads Manager to support sending send offline events from Amperity.

Step 4.

Business users are assigned to the Amp360 User and/or AmpIQ User policies. (Amp360 User allows access to queries and orchestrations and AmpIQ User allows access to segments and campaigns.) A business user cannot select a destination that is not visible to them.

Business users – including users assigned to the DataGrid Operator policy – may have restricted access to PII.

What is restricted access to PII?

Restricted PII access is enabled when the Restrict PII access policy option that prevents users who are assigned to that option from viewing data that is marked as PII anywhere in Amperity and from sending that data to any downstream workflow.

You can make this destination visible to orchestrations and allow users with restricted access to PII to use this destination by enabling one (or both) of the following options:

Allow business users access to this destination.
Step 5.

Review all settings, and then click Save.

Save the destination.

Important

You must configure a data template for this destination before you can send data to Meta Ads Manager.

Add data template

Offline events must be sent using a query and orchestration. The data template associated with offline events should not be made available to the Campaigns editor.

To add a data template

Step 1.

From the Destinations tab, open the menu for a destination that is configured for Meta Ads Manager, and then select Add data template.

This opens the Add Data Template dialog box.

Step 1

Enter the name of the data template and a description. For example: “Meta Ads Manager offline events” and “Send offline events to Meta Ads Manager.”.

Step 2.

Verify business user access to queries and orchestrations and access to segments and campaigns.

A business user may also have restricted access to PII, which prevents them from viewing and sending customer profile data.

Step 2.

If business user access was not configured as part of the destination, you may configure access from the data template.

Step 3.

Verify all configuration settings.

Verify settings for the data template.

Note

If the dataset ID is not specified in the data template it must be specified at orchestration.

Step 4.

Review all settings, and then click Save.

Save the data template.

After you have saved the data template, and depending on how you configured it, business users can send query results and/or send campaigns to Meta Ads Manager.

Workflow actions

A workflow will occasionally show an error that describes what prevented a workflow from completing successfully. These first appear as alerts in the notifications pane. The alert describes the error, and then links to the Workflows tab.

Open the Workflows page to review a list of workflow actions, choose an action to resolve the workflow error, and then follow the steps that are shown.

Step one.

You may receive a notifications error for a configured Meta Ads Manager destination. This appears as an alert in the notifications pane on the Destinations tab.

Review a notifications error.

If you receive a notification error, review the details, and then click the View Workflow link to open this notification error in the Workflows page.

Step two.

On the Workflows page, review the individual steps to determine which step(s) have errors that require your attention, and then click Show Resolutions to review the list of workflow actions that were generated for this error.

The workflow tab, showing a workflow with errors.
Step three.

A list of individual workflow actions are shown. Review the list to identify which action you should take.

Choose a workflow action from the list of actions.

Some workflow actions are common across workflows and will often be available, such as retrying a specific task within a workflow or restarting a workflow. These types of actions can often resolve an error.

In certain cases, actions are specific and are shown when certain conditions exist in your tenant. These types of actions typically must be resolved and may require steps that must be done upstream or downstream from your Amperity workflow.

Amperity provides a series of workflow actions that can help resolve specific issues that may arise with Meta Ads Manager, including:

Step four.

Select a workflow action from the list of actions, and then review the steps for resolving that error.

Choose a workflow action from the list of actions.

After you have completed the steps in the workflow action, click Continue to rerun the workflow.

Authorization error

OAuth is an open standard for access delegation, commonly used to grant websites or applications access to information on other websites.

You may need to reauthorize access to Meta Ads Manager. This is necessary when an authorization token has expired or when it has been removed by someone with permission to manage access within Meta Ads Manager. To reauthorize access to Meta Ads Manager, follow the steps to configure OAuth and create a new credential.

Cannot create ads

The advertising account that is used by this workflow must have permission to create ads.

To resolve this error, update the user permissions in Meta Ads Manager to ensure that the advertising account can create ads.

  1. Log into Meta Ads Manager and verify the user permissions for the account.

  2. Update the user permissions to ensure that the Create and edit ads permission is assigned to the advertising account used by this workflow.

  3. Return to the workflow action, and then click Resolve to retry this workflow.

EXTERN_ID is missing

An EXTERN_ID is a unique ID used within Meta Ads Manager, such as a loyalty ID, a customer ID, an external ID, or the Amperity ID.

Amperity will be unable to send orchestrations or campaigns when EXTERN_ID is not included within an audience that is sent to Meta Ads Manager.

For campaigns

To resolve this error, verify that EXTERN_ID is included in the list of attributes that are being sent to Meta Ads Manager.

  1. Open the Campaigns page, and then open the segment used with this workflow.

  2. Verify that EXTERN_ID is included in the list of attributes for each treatment group that sends audiences to Meta Ads Manager. Update the list of attributes for each treatment group if required.

  3. Return to the workflow action, and then click Resolve to retry this workflow.

For orchestrations

To resolve this error, verify that EXTERN_ID is included in the query results.

  1. Open the Queries page, and then open the query used with this workflow.

  2. Verify that EXTERN_ID is included in the query results. Update the query if required.

  3. Return to the workflow action, and then click Resolve to retry this workflow.

Invalid credentials

The credentials that are defined in Amperity are invalid.

To resolve this error, verify that the credentials required by this workflow are valid.

  1. Open the Credentials page.

  2. Review the details for the credentials used with this workflow. Update the credentials for Meta Ads Manager if required.

  3. Return to the workflow action, and then click Resolve to retry this workflow.

Maximum custom audiences exceeded

Meta Ads Manager supports having up to 500 custom audiences in your account at any given time. Amperity will be unable to create custom audiences when this limit is exceeded.

To resolve this error, verify the number of custom-audiences associated with your Meta Ads Manager account.

  1. Log into Meta Ads Manager and verify the number of custom audiences that are associated with your Meta Ads Manager account.

  2. Remove custom audiences that are not in active use.

  3. Return to the workflow action, and then click Resolve to retry this workflow.

Must agree to Facebook terms

The custom audience terms of service must be signed by each business user that is associated with your Facebook Ads account. If the terms of service are not signed, a permissions error will prevent Amperity from sending data to Facebook Ads.

When the business user has not agreed to Facebook terms, an error similar to the following is shown:

Permissions error: To create or edit an audience with an uploaded customer list,
please agree to the Custom Audience terms at
https://business.facebook.com/ads/manage/customaudiences/tos/?act=1234567890123456.

To resolve this error, log into Meta Ads Manager as the business user associated with this workflow and agree to the terms of service.

  1. Follow the instructions in the error message, and then open the provided link in a new tab.

  2. Log in as the business user associated with this workflow, and then agree to the Facebook terms of service.

  3. Return to the workflow action, and then click Resolve to retry this workflow.

Must belong to business account

The advertising account used to enable workflows to be sent to Meta Ads Manager from Amperity requires the advertising account to also belong to a business account. When an advertising account does not also belong to a business account, Amperity workflows will be unable to create or edit a custom audience.

To resolve this error, verify that the advertising account also belongs to a business account.

  1. Log into Meta Ads Manager and verify the configuration for the advertising account to ensure that it also belongs to a business account.

  2. Return to the workflow action, and then click Resolve to retry this workflow.

Security challenge

Sometimes Meta Ads Manager will issue a security challenge to the advertising account and/or business account associated with this workflow.

To resolve this error, complete the steps that are required to resolve the security challenge.

  1. Log into Meta Ads Manager using the link provided in the workflow action, and then follow the instructions to resolve the security challenge.

  2. Return to the workflow action, and then click Resolve to retry this workflow.

Facebook Marketing API keys

The following Amperity columns should be mapped to the corresponding Facebook Marketing API keys when they are present in query data:

Amperity Column

Facebook API Key

Description

Amperity ID

EXTERN_ID

This value is a unique ID used by the advertiser, such as a loyalty ID, a customer ID, an external cookie ID, or the Amperity ID.

For this key, the connector trims leading and trailing whitespace.

Tip

A query can alias the Amperity ID directly in a query: SELECT amperity_id AS EXTERN_ID from custom_table. This approach can be helpful for queries that are dedicated to returning data to be sent only to Facebook Ads.

Email Addresses

EMAIL

For this key, the connector:

  • Trims leading and trailing whitespace

  • Converts to lower-case

  • Hashes data as SHA-256

Phone Numbers

PHONE

Converts each phone number to E.164 format which represents a phone number as a number up to fifteen digits in length (without spaces) that starts with a + symbol. For example: +12061234567.

For this key, the connector:

  • Trims leading and trailing whitespace

  • Removes symbols, letters, and any leading zeros

  • Hashes data as SHA-256

Gender

GEN

For this key, the connector:

  • Trims leading and trailing whitespace

  • Converts to lower-case

  • Converts to m and f

  • Hashes data as SHA-256

Birth Date

BIRTH

The birth date in Amperity date format.

For this key, the connector splits this value into three fields: birth year (DOBY), birth month (DOBM), and birth day (DOBD).

Birth Year

DOBY

Warning

Do not pass this column. For this key, the connector will use birthdate to split out the value for DOBY with a format of YYYY and a range from 1900 to the current year.

Birth Month

DOBM

Warning

Do not pass this column. For this key, the connector will use birthdate to split out the value for DOBM with a format of 01 to 12.

Birth Day

DOBD

Warning

Do not pass this column. For this key, the connector will use birthdate to split out the value for DOBD with a format of 01 to 31.

Last Name

LN

This key supports special characters and non-Roman alphabet characters. For this key, the connector:

  • Trims leading and trailing whitespace

  • Converts to lower-case

  • Removes punctuation

  • Updates special characters to UTF-8 format

  • Hashes data as SHA-256

First Name

FN

This key supports special characters and non-Roman alphabet characters. For this key, the connector:

  • Trims leading and trailing whitespace

  • Converts to lower-case

  • Removes punctuation

  • Updates special characters to UTF-8 format

  • Hashes data as SHA-256

First Initial

FI

Warning

Do not pass this column. The connector will use the first character of the normalized first name.

US States

ST

A two-character ANSI abbreviation code for US states.

For this key, the connector:

  • Trims leading and trailing whitespace

  • Converts to lower-case

  • Normalizes states located outside of the United States

  • Removes punctuation, special characters, and whitespace

  • Hashes data as SHA-256

City

CT

For this key, the connector:

  • Trims leading and trailing whitespace

  • Converts to lower-case

  • Removes punctuation, special characters, and whitespace

  • Hashes data as SHA-256

Zip Code

ZIP

Use only the first five digits for the United States. Use postcodes (area, district, sector) format for United Kingdom.

For this key, the connector:

  • Trims leading and trailing whitespace

  • Converts to lower-case

  • Removes whitespace from lower-case for United Kingdom

  • Trims to five digits for United States

  • Hashes data as SHA-256

Country Code

COUNTRY

A two-letter country code in ISO 3166-1 alpha-2 format.

For this key, the connector:

  • Trims leading and trailing whitespace

  • Converts to lower-case

  • Hashes data as SHA-256

Mobile Advertiser ID

MADID

For this key, the connector:

  • Trims leading and trailing whitespace

  • Converts to lower-case

  • Keeps hyphens

  • Hashes data as SHA-256

Conversions API parameters

The following table describes each of the parameters that are required by Meta Ads Manager for offline events. The final row lists the optional fields your brand may include to extend the customer profile information that is associated with offline events that are returned by the query and sent to Meta Ads Manager.

The fields are listed alphabetically, but may be returned by the query in any order.

Field name

Description

action_source

Required

Action sources group offline events into categories and enable ad measurmeent and custom audience creation abilities from within the Meta Ads Manager user interface.

Add action_source to your query and then set a value:

,action_source AS 'physical_store'

The value for action_source must be one of the following:

app

Use when the offline conversion was made from a mobile app.

chat

Use when the offline conversion was made over a messaging app, SMS, or online messaging feature.

email

Use when the offline conversion happened over email.

other

Use when the offline conversion occurred by some other workflow.

phone_call

Use when the offline conversion was made over a phone call.

physical_store

Use when the offline conversion was made in-person at a physical store location.

system_generated

Use when the offline conversion occurred automatically, such as from a subscription renewal or monthly auto-pay.

website

Use when the offline conversion was made on a website.

The value for action_source is used by the Conversions API to categorize offline conversions within the Meta Ads Manager user interface and may not be customized. Use the action source that best associates how your brand wants to use offline conversions within Meta Ads Manager.

When action_source is not specified the default value is “physical_store”.

currency

Required

A value for currency is required by the Conversions API for purchase events. Currency must be a valid ISO 4217 three-digit currency code, such as “USD” (United States dollar), “AUD” (Australian dollar), “CAD” (Canadian dollar), “EUR” (Euro), “JPY” (Japanese yen) or “MXN” (Mexican peso).

Add currency to your query, and then set a value:

,'USD' AS currency

Note

When viewing parameters in the Meta Ads Manager user interface, price, quantity, and currency are combined to be shown as value, which represents the sum of price times quantity, shown in the currency used for the transaction.

email or phone

Required

You must send an email address or a phone number to Meta Ads Manager; you may configure the query to send both.

Add at least one of email or phone to your query:

,c360.email AS email
,c360.phone AS phone

Note

Amperity performs the same actions for email addresses and phone numbers when sending to the Conversions API as when sending to the Marketing API.

event_name

Required

Identifies an offline event as a purchase within Meta Ads Manager.

Note

The default value for event_name is “Purchase”. The event_name parameter and the “Purchase” value are applied automatically when sending data to the Conversions API. This value may not be customized.

external_id

Required

The amperity_id field MUST be renamed to extern_id.

Add extern_id to your query:

,c360.amperity_id AS extern_id

Note

Amperity performs the same actions for the external ID when sending to the Conversions API as when sending to the Marketing API.

order_id

Required

The order ID for the transaction.

Use the Order ID field that is available from the Unified Itemized Transactions table:

,uit.order_id AS order_id

Important

The number of rows that results from the query will not be the same as the number of events that are uploaded to Meta Ads Manager.

This is because itemized transactions within the query are grouped by Order ID as the data is sent to Meta Ads Manager.

Grouping by Order ID ensures that individual events are combined to describe a complete transaction.

Amperity performs the GROUP BY action automatically if a GROUP BY clause is not set to “order_id”.

price

Required

Calculate price by dividing item revenue by item quantity. These fields are available from the Unified Itemized Transactions table:

,CAST(
  uit.item_revenue / uit.item_quantity AS DOUBLE
) AS price

Note

When viewing parameters in the Meta Ads Manager user interface, price, quantity, and currency are combined to be shown as value, which represents the sum of price times quantity, shown in the currency used for the transaction.

product_id

Use the Product ID field that is available from the Unified Itemized Transactions table:

,uit.product_id AS product_id

quantity

Required

Use the Item Quantity field from the Unified Itemized Transactions table to define quantity:

,uit.item_quantity AS quantity

Note

When viewing parameters in the Meta Ads Manager user interface, price, quantity, and currency are combined to be shown as value, which represents the sum of price times quantity, shown in the currency used for the transaction.

timestamp

Required

A Unix timestamp (in seconds) that indicates when the transaction occurred.

Use the Order Datetime field from the Unified Itemized Transactions table to define timestamp:

,uit.order_datetime AS timestamp

Use a WHERE clause to limit the number of days to a maximum of seven:

WHERE uit.order_datetime > (
  CURRENT_DATE - interval '7' day
)

Note

When viewing parameters in the Meta Ads Manager user interface, timestamp is shown as event_time.

Optional profile attributes

You may include any of the profile attributes that are supported by the Marketing API, including Gender, Birthdate, First Name, Last Name, City, State, Zip Code, and Country Code.