CRM Integration

Integrating your CRM system with Facebook’s Conversions API to use with the Conversion Leads optimization goal for lead ads yields better results. Currently, this optimization only supports native lead ads (Instant Forms) generated on Facebook.

This guide provides the payload specifications for CRM integration. See the Conversions API documentation for more information on getting started with the API and other useful resources.

Event Payload

Parameters

NameDescription

lead_id

integer

Required
The FB generated ID for every lead. It is a 15 or 16-digit number obtained from the leadgen_id field in the lead gen Webhook and included under the user_data parameter.
It is required to use lead IDs instead of customer information for matching. We recommend using a variable to pass in the ID values from your database.
Note: Do not hash.

event_name

string

Required
Free form field to capture the stages you use within your CRM.
Make sure to send all stages as they are updated, including the initial lead stage.
For example, your stages may include the following types. If a lead reaches the final “Converted” stage, then all previous stages should have been sent beforehand.

  1. Initial Lead from FB
  2. Marketing Qualified Lead
  3. Sales Opportunity
  4. Converted

We recommend using a variable to pass in the stages from your database. Alternatively, you could create a separate API call for each stage.

event_time

integer

Required
A Unix timestamp in seconds indicating when the lead stage update event is updated by your CRM.
We recommend using a variable to pass in the Unix timestamp values from your database.
Note: The event_time parameter value can be up to 7 days before you send an event to Facebook.

action_source

string

Required
Value: system_generated
For lead ads integrations, this specifies where your conversions are system generated.

lead_event_source

string

Required
The name of the tool where the leads are coming from (e.g., Hubspot, SAP, Oracle, Dynamics, In-house CRM, etc.), included under the custom_data parameter.

event_source

string

Required
Value: crm
For lead ads integration, this specifies the source of the event as your CRM under the custom_data parameter.

Example

This example illustrates the format of the event payload sent in the API call.

{
    "event_name": "my lead stage",
    "event_time": 1617693833,
    "user_data": {
        "lead_id": 1234567890123456
    },
    "action_source": "system_generated",
    "custom_data": {
        "lead_event_source": "Salesforce",
        "event_source": "crm"
    }
}

FAQ

Below are some guidelines that we look for in integrations. Note that these guidelines are to ensure compatibility with the model but can be flexible.

  • Use Facebook native lead ads (Instant Forms)
  • Generate at least 250 leads per month on Facebook
  • Can upload data frequently and regularly; we recommend uploading data at least once per day
  • The stage you want to optimize for occurs within a month of leads being generated
  • The stage you want to optimize for has an approximate conversion rate between 3% and 40%
  1. Go to Events Manager.
  2. In the left side navigation menu, click on the green circle with a plus sign in it to connect a new data source.
  3. Select CRM, and click Connect.
  4. Create or choose a Pixel to associate with your CRM, then click Confirm.
  5. Work with a developer to integrate your CRM with this guide and the Conversions API documentation.

The integration is currently in the data validation phase; it must pass all of the following requirements before proceeding to the next step:

  • Continually send at least seven days worth of data. This does not have to be seven days in a row because you might not generate leads on the weekends.
  • Enough events are being uploaded to match with leads generated on Facebook. For example, if you generate 100 leads in one day we would expect all 100 leads to have uploaded events to match to them.
  • Minimum of two stages for events from your sales funnel. However, we recommend at least three stages if possible. For example, only sending in the “Sale” event will not be enough; make sure you send in previous stages as well.
  • Data has all the required parameters and in the correct format highlighted in this guide. Sending data in old formats will trigger an error.

After the funnel configuration is complete the system will analyze your data again to determine if it matches with your indicated funnel.

Once your integration has passed the funnel analysis there is a training period of at least 30 days before your integration is added to the production model. The exact number of days will depend on the refresh cadence of the optimization model. You can enable the optimization in Ads Manager during this period, but you might not see the full performance gains until after the training period.

Learn More