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.

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





The FB generated ID for every lead. It is a 16 or 18-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.



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.



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.



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



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.



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


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"


  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 and it must pass all the requirements before proceeding to the next step. One requirement is uploading at least 7 days worth of data.

Once you have configured your funnel, we may require additional data to train the optimization model before it is turned on for your integration. Ideally, about one month of valid data will need to be uploaded.

Learn More