Payload Specification - Developers Meta Docs

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

Name	Description
`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

Marketing Qualified Lead
Sales Opportunity
ConvertedUse a variable to pass in the stages from your CRM. Alternatively, you could create a separate API call for each stage. | | event_timeinteger | 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_sourcestring | 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_sourcestring | 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_sourcestring | 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

Business Help Center: Set Up Your CRM for Conversion Leads
Business Help Center: About Delivery Optimization for Lead Ads

​Event Payload

​Parameters

​Example

​Learn More

Event Payload

Parameters

Example

Learn More