# Facebook Conversions API Reference ## Destination Info * Accepts [Track](https://documentation.freshpaint.io/developer/freshpaint-sdk-reference#track) calls * Supports [HIPAA mode](https://documentation.freshpaint.io/hipaa-mode) * Supports forwarding from the [Google Tag Manager Integration](/integrations/google-tag-manager-integration.md) * Refer to this destination as **Facebook Conversions API** in the [Integrations object](https://documentation.freshpaint.io/reference/developer/freshpaint-sdk-reference#using-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. {% hint style="info" %} When no suffix is specified, all configured Pixel IDs are selected for inclusion / exclusion. {% endhint %} * Connection Modes:
Client-sideServer-side
Webfalsetrue
Mobilefalsetrue
Serverfalsetrue
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](/integrations/destinations/direct-response-ads/facebook-conversions-api/facebook-conversions-api-reference.md). ## Events When you send an event to Facebook from Freshpaint, Freshpaint will create an event in Facebook by hitting Facebook's [event API](https://developers.facebook.com/docs/graph-api) endpoint at:[ ](https://graph.facebook.com/%7BAPI_VERSION%7D/%7BPIXEL_ID%7D/events?access_token={TOKEN})[https://graph.facebook.com/{API\_VERSION}/{PIXEL\_ID}/events?access\_token={TOKEN}](https://graph.facebook.com/%7BAPI_VERSION%7D/%7BPIXEL_ID%7D/events?access_token={TOKEN})[.](https://graph.facebook.com/%7BAPI_VERSION%7D/%7BPIXEL_ID%7D/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 Event | Freshpaint Event Definition | Available 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 | | {% hint style="info" %} Facebook Events are case-sensitive {% endhint %} 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. ### Custom Facebook Events {% hint style="warning" %} Due to recent Meta changes, healthcare companies may be restricted from using lower-funnel Standard Events such as "Schedule" or "Add to Cart". Freshpaint recommends sending custom events with generic naming that excludes any health information. {% endhint %} #### Steps 1. Create an event in Freshpaint or GTM, using the Freshpaint template. 2. Use a generic name, excluding health context (ex: Event1). You can also do this by adding a Rename Transformation in Freshpaint.
3. Accept the custom event(s) in Events Manager > Overview. After creating custom events, you'll need to review and confirm them in [Meta Events Manager](https://www.facebook.com/business/help/642275438032995). Review and select events. 4. These events should now show up in your Data Sources view. ### 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 {% hint style="warning" %} If your Freshpaint account is set up in [HIPAA Mode](/readme/hipaa-mode.md), 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. {% endhint %} #### Action Source {% hint style="warning" %} 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](https://developers.facebook.com/docs/marketing-api/conversions-api/best-practices/#req-rec-params). {% endhint %} `action_source` is set to "website" by default for server-side events. `action_source` should be included under `properties` on track events. | Action source value | Description | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `website` | Conversion was made on your website. | | `app` | Conversion was made on an application(Android, iOS, Windows). See Facebook conversions app data [documentation](https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/app-data/). | | `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](https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/fbp-and-fbc) to improve the number of the events that are matched to a Facebook user. See [Facebook's documentation](https://developers.facebook.com/docs/marketing-api/conversions-api/parameters) on all of the parameters that Facebook Conversions API accepts. The Freshpaint integration also supports the values seen in [conversion app data parameters](https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/app-data/). #### 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](https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/customer-information-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](https://www.facebook.com/business/help/765081237991954) 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 {% hint style="warning" %} You should ensure the`fbc`parameter, at minimum, is sent whenever possible. {% endhint %} 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](https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/fbp-and-fbc) 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](https://developers.facebook.com/docs/meta-pixel/reference#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](https://app.freshpaint.io/transformations/new) and select [Standard Event](https://app.freshpaint.io/transformations/new/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:
{% hint style="info" %} Some of Facebook's [standard events](https://developers.facebook.com/docs/meta-pixel/reference#standard-events) requires a certain set of properties. {% endhint %} 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](https://business.facebook.com/events_manager2/list) and navigate to the Overview tab and confirm the Purchase event is in the list:
{% hint style="info" %} Note: events may take a few minutes to populate in this view. {% endhint %} ## 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](/integrations/destinations/apps/facebook-pixel.md), 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. {% hint style="info" %} If you are a HIPAA customer, you should use only Facebook Conversions API {% endhint %} ### 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. {% hint style="info" %} HIPAA customers should use this approach to remain HIPAA complaint {% endhint %} #### 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](#additional-parameters). #### Deduplication In this approach, events are only sent from 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: .
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](https://documentation.freshpaint.io/integrations/destinations/advertising-destinations/facebook-conversions-api/facebook-conversions-api-reference#additional-parameters), 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://documentation.freshpaint.io/integrations/destinations/direct-response-ads/facebook-conversions-api/facebook-conversions-api-reference.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.