Payload Specification

Updated: Apr 26, 2025

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

Required Parameters

Name	Description
`user_data` object	A map that contains customer information data. See Customer Information Parameters for options. See Advanced Matching for comparable options available for data sent via Meta Pixel.
`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. Initial Lead from Facebook Marketing Qualified Lead Sales Opportunity 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.

Customer Information Parameters

Customer information helps Meta match events from your server with Meta accounts. Sending as many of these parameters can lead to more accurate event data and better ad performance.

Note: You must send at least one customer information parameter. If sending lead_id, please use a valid lead_id or else the system will reject the event. If you choose to send email, phone number, these have to be hashed. Click ID currently does not have API rejection level error, but a large volume of invalid click_id will cause an alert in the system.

Parameter	Priority	Description
Lead ID (recommended) How to find the lead ID?	Highest	The Facebook generated ID for every lead. It is a 15-17 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.
Click ID	Highest
Hashed email	Highest
Hashed phone number	High
Other hashed Contact Information	Medium

Note: In addition to a hashed email and phone number, you can send hashed gender, date of birth, last name, first name, city, state, zip and more to Meta.

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

Business Help Center: Set Up Your CRM for Conversion Leads⁠

Business Help Center: About Delivery Optimization for Lead Ads⁠

Did you find this page helpful?