Facebook Conversions API Reference

Destination Info

  • Accepts Track calls

  • Supports HIPAA mode

  • Refer to this destination as Facebook Conversions API in the Integrations object

    • If you've configured multiple Pixel IDs, you can choose a specific one by suffixing the Pixel ID, such as: Facebook Conversions API::0123456789012345. You can retrieve this value from the Facebook Conversions API configuration page for the Pixel ID of interest.

When no suffix is specified, all configured Pixel IDs are selected for inclusion / exclusion.

  • Connection Modes:

Client-sideServer-side

Web

Mobile

Server

This is a reference document for the Facebook Conversions API destination. For information on how to set up this integration, see the Quick Start guide.

Events

When you send an event to Facebook from Freshpaint, Freshpaint will create an event in Facebook by hitting Facebook's event API endpoint at: https://graph.facebook.com/{API_VERSION}/{PIXEL_ID}/events?access_token={TOKEN}.

Standard Facebook Events

See below for a complete list of Facebook standard events, the Freshpaint event definitions they are mapped to, and the available properties that can be sent in with each event. All properties are optional unless otherwise noted as "Required".

Facebook EventFreshpaint Event DefinitionAvailable Facebook Properties

AddToCart

AddToCart

content_ids, content_name, content_type, contents, currency, value

product added

added product

AddToWishlist

AddToWishlist

content_name, content_category, content_ids, contents, currency, value

AddPaymentInfo

AddPaymentInfo

content_category, content_ids, contents, currency, value

CustomizeProduct

CustomizeProduct

``

Contact

Contact

CompleteRegistration

CompleteRegistration

content_name, currency, status, value

Donate

Donate

InitiateCheckout

InitiateCheckout

content_category, content_ids, contents, currency, num_items, value

checkout started

started checkout

Lead

Lead

content_category, content_name, currency, value

Purchase

Purchase

Required: value, currency Optional: content_ids, content_name, content_type, contents, num_items

Schedule

Schedule

Search

Search

content_category, content_ids, contents, currency, search_string, value

products searched

searched products

StartTrial

StartTrial

value, currency, predicted_ltv

SubmitApplication

SubmitApplication

Subscribe

Subscribe

value, currency, predicted_ltv

ViewContent

ViewContent

content_ids, content_category, content_name, content_type, contents, currency, value

product list viewed

viewed product list

product category viewed

viewed product category

product viewed

viewed product

Facebook Events are case-sensitive

Any of the space-delimited names above are case-insensitive and may be alternatively delimited by an underscore or no separation. For example, "product added" can also be expressed as:

  • Product_added

  • productAdded

These non-Facebook-specific names can be useful when sending to multiple destinations, such as Facebook Conversion API and TikTok Ads, without requiring a Rename Transformation for one or both destinations.

Required Server Event Parameters

Parameters are JSON-formatted objects that you can include when tracking standard and custom events. They allow you to provide additional information about your users and their actions.

Event Source URL

If your Freshpaint account is set up in HIPAA Mode, the URL will be redacted by default because it may contain PHI. For example, if the URL of the event is https://example.com/heart-conditions#treatments?user=alice then Freshpaint will send https://example.com/url-redacted-by-freshpaint. To send the complete URL to facebook, add the Built-in URL ($current_url) property to your HIPAA allowlist.

Action Source

Facebook requires every event sent to the Conversions API to have an action_source parameter describing where the event came from. If action_source is "website" (the default value), then the Built-in User Agent($user_agent) / user_agent is required to be Allowlisted, if in HIPAA mode. The URL must also be sent in some form - as noted above, Freshpaint will always send a value for URL. These correspond to the client_user_agent and event_source_url properties described in facebook's documentation.

action_source is set to "website" by default for server-side events. action_source should be included under properties on track events.

Action source valueDescription

website

Conversion was made on your website.

email

Conversion happened over email.

phone_call

Conversion was made over the phone.

chat

Conversion was made via a messaging app, SMS, or online messaging feature.

physical_store

Conversion was made in person at your physical store.

system_generated

Conversion happened automatically, for example, a subscription renewal thatโ€™s set on auto-pay each month.

other

Conversion happened in a way that is not listed.

Client User Agent

client_user_agent is automatically set from the built-in $user_agent property, or by including the user_agent property on track events. The value should be the user agent of the browser where the event occurred.

Additional Parameters

When you send user actions to Facebook, Facebook will attempt to match those actions to a particular Facebook user. In most cases, you'll want to send additional user traits and Facebook parameters to improve the number of the events that are matched to a Facebook user. See Facebook's documentation on all of the parameters that Facebook Conversions API accepts.

User Traits

User traits you can include as event properties to improve match rate include:

  • email

  • phone

  • last_name

  • first_name

  • ip_address(is automatically set from built-in $ip property, or from ip_address property)

  • user_agent

  • state

  • city

  • zip

  • country

  • dob

  • gender

Facebook requires the following customer info parameters to be hashed:

  • email

  • phone

  • last_name

  • first_name

  • state

  • city

  • zip

  • country

  • dob

  • gender

Freshpaint will automatically hash the values sent with any of these properties when sending them to Facebook.

Read Facebook's documentation on how match quality for events helps deliver ads to people who are more likely to take the action you care about, and attribute those actions back to your ads.

Facebook's fbp and fbc Parameters

You should ensure thefbcparameter, at minimum, is sent whenever possible.

The fbc parameter is automatically derived and sent by Freshpaint when the fbclid query parameter is available (captured by Freshpaint as $fbclid). If in HIPAA mode, you must have the Recommended property $fbclid Allowlisted for this to work. You may explicitly send fbc if desired, in which case it will be sent, overriding the $fbclid-derived value if any (provided that it's Allowlisted, if in HIPAA mode).

The fbp parameter is automatically generated and sent by Freshpaint. This generated value can be overridden if you send the value with the event (Allowlisting applies here in HIPAA mode). See Facebook's documentation for more information.

Configuration Options

Transformations

Converting Freshpaint Events Into Facebook Standard Events

Freshpaint events can be converted into one of Facebook's standard events. A popular use case would be to convert an existing conversion event into Facebook's Purchase event. The Conversions API creates a connection between your first-party customer data and the Meta systems that optimize ad targeting and help measure the results of your advertising efforts.

In the example below, we are going to transform an existing "Test Event" into one of Facebook's standard Purchase events.

To get started, create a new Transformation and select Standard Event. Next, select the existing Freshpaint event you want to transform and the destination you want to send it to:

Then, select the "Purchase" event from the list of standard mappings and click "Save" to go to the following step:

Some of Facebook's standard events requires a certain set of properties.

In the case of the Purchase event, your existing Freshpaint event will need the following event properties:

  • value (amount of the conversion)

  • currency (USD, CAD, etc)

In the case of the InitiateCheckout event, your existing Freshpaint event will also need the following event property:

  • num_items (number of items)

For this transformation, you'll see that the event will be sent to Facebook named as "Purchase" while converting the value property type into a number and sending the currency property value in all uppercase characters as required by Facebook.

If a currency property isn't sent with your conversion event and all of your conversions are in a single currency type such as USD, you can add a new transformation rule to send USD as a constant property for your conversion event:

As new instances of "Test Event" occur, the transformation would then send them to the Facebook Conversions API destination as standard Purchase events.

If a currency property isn't sent with your conversion event and all of your conversions are in a single currency type such as USD, you can add a new transformation rule to send USD as a constant property for your conversion event:

As new instances of "Test Event" occur, the transformation would then send them to the Facebook Conversions API destination as standard Purchase events.

Finally, visit your Facebook Events Manager account and navigate to the Overview tab and confirm the Purchase event is in the list:

Note: events may take a few minutes to populate in this view.

Options for Configuring Facebook Destinations

There are a few different ways to implement conversion tracking with Freshpaint's Facebook Conversions API integration. You can use it to complement tracking with your Facebook Pixel, or you can use it as a standalone integration. The option that's best for you depends on your specific goals with the Facebook Conversions API.

You can choose from the following implementation options:

If you are a HIPAA customer, you should use only Facebook Conversions API

Use Only Facebook Conversions API

This approach is best if you don't want to load the Facebook Pixel on your site, or if you want more control over what gets sent to Facebook.

HIPAA customers should use this approach to remain HIPAA complaint

Matching

When you send user actions to Facebook, Facebook will attempt to match those actions to a particular Facebook user. When using just the Facebook Conversions API without including many properties normally collected in the browser, the match rate will likely be lower than if they were included.

The match rate can be improved by including additional parameters.

Deduplication

In this approach, events are only sent from the server, so no deduplication is necessary.

Use both Pixel and Conversions API to send the same events

By sending the same events from both the browser via the Pixel and the server via the Conversions API, you can improve the accuracy of browser events by providing redundancy. Events that previously would've been lost (e.g. due to the browser Pixel being blocked or network errors) can still be captured using the Conversions API.

Matching

When you send user actions to Facebook, Facebook will attempt to match those actions to a particular Facebook user. For matching in this configuration to work best, the same external_id should be sent from both the browser and server.

This can be done by enabling the "Use User Id or Anonymous Id as External Id" setting in the Facebook Pixel destination. Enabling this setting will direct Freshpaint to use the User ID for identified users or Anonymous ID for anonymous users as Facebook's external_id both on the browser for the Pixel and for the server/Conversions API, enabling Facebook to better match users.

You can also improve the match rate by including some additional parameters to your events.

Deduplication

When the same event is sent from both the browser and the server, the events must be deduplicated to avoid having the same event counted twice. For events to be deduplicated, event names must be the same, and the server event from the Conversions API must arrive after the client event from the Pixel. In this case, the server event is discarded.

If the server events is received first, no deduplication occurs. The server event must arrive after the client event in order to deduplicate.

For Facebook to deduplicate events correctly, the recommended "Use UserId or Anonymous Id as External Id" setting must be enabled, OR the fbp parameter must be included in server-side events.

Use both Pixel and Conversions API to send different events

In this configuration, you will send some browser events through the Pixel and some server events to the Conversions API. This approach is best when you have events that can't be captured in the browser, such as a separate payment system. This approach is also ideal when you want to include sensitive data that shouldn't be sent to the browser.

Matching

When you send user actions to Facebook, Facebook will attempt to match those actions to a particular Facebook user. For matching in this configuration to work best, the same external_id should be sent from both the browser and server.

This can be done by enabling the "Use User Id or Anonymous Id as External Id" setting in the Facebook Pixel destination. Enabling this setting will direct Freshpaint to use the User ID for identified users or Anonymous ID for anonymous users as theexternal_id both on the browser for the Pixel and for the server/Conversions API, enabling Facebook to better match users.

You can also improve the match rate by including some additional parameters to your events.

Deduplication

In this approach, different events are sent from the browser and the server, so no deduplication is necessary.

Validation

To validate that your events are making it to Facebook, you can use Facebook's test_event_code property. To set up a test event code, see: https://www.facebook.com/business/help/1624255387706033?id=818859032317965.

Then, you can send the test event code from your browser console like so:

  • freshpaint.track("Test Event", {test_event_code: 'TEST60659'}) OR

  • freshpaint.addEventProperties({test_event_code: 'TEST60659'})

View-Through Conversions and Retargeting

View-through conversions and retargeting are possible for a user when the user traits provided, such as email or IP address, match a user in Facebook.

If user traits are not provided, then view-through conversions and retargeting are not possible.

Last updated