Conversions API

Payload Specification

Integrating your CRM with Meta's Conversions API and using the Lead Ads - Conversion Leads optimization goal may yield higher quality results. Currently, this optimization only supports native Lead Ads (Instant Forms) generated on Facebook or Instagram.

This guide provides the payload specification for CRM events uploaded for the Conversion Leads optimization only. Do not use this specification for events not related to this optimization.

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 Facebook generated ID for every lead. It is a 15 or 16-digit number obtained from the leadgen_id field in the lead generation Webhook and included under the user_data parameter. Refer to Find the Lead ID for more information.
It is required to use lead IDs instead of customer information for matching. Use a variable to pass in the ID values from your CRM.
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 Facebook
  2. Marketing Qualified Lead
  3. Sales Opportunity
  4. Converted

Use a variable to pass in the stages from your CRM. 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.
Use 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 Meta. Also the timestamp must occur after the lead generation time or else the event may be discarded.

action_source

string

Required.
Set this parameter to the value system_generated for all Conversion Leads events.
For Conversion Leads integrations, this specifies where your conversions are system generated.

lead_event_source

string

Required.
Set this parameter to 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.
Set this parameter to the value crm for all Conversions Leads events.
For Conversion Leads 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"
    }
}

Learn More