Conversions API

3: Developer Implementation

This page deals with the manual integration and covers:

This section is only applicable if you decide to complete this integration using a manual integration and developer resources. If you instead decide to complete this integration using a partner, follow the respective partner instructions for the integration. You can skip to 4: Verify your data section of this guide once the partner integration is complete.

You will need Business Manager admin access to complete these integration steps. You may acquire access from the email sent to you if you were invited as a developer. Otherwise, contact a Business Manager admin to request access.

Step 1: Build a payload

This step will lay out the payload specifications for the Conversion Leads integration and provide some recommendations on how to send it from your server.

  1. Open the CRM integration guide from the Settings tab of your CRM Pixel to get started.

  2. Review the Conversion API Developers Guide to gain an understanding of how the Conversion API functions.

  3. We recommend using the Payload Helper to build your payload. The Payload Helper will format your payload and check for errors. Once all payload errors are resolved, click the Get Code button inside the Payload Helper to generate a code template for your programming language.

  4. Here is the list of required parameters. Review the Conversion Leads Integration - Payload Specification guide to see the full description for each parameter. This payload specification should only be used for Conversion Leads Optimization events. This means the events should only pertain to Meta lead ads and have a valid Lead ID. Refrain from using this payload specification for other event types, such as website leads.

    Parameters
    NameDescription

    event_name

    string

    Free-form field to capture the lead stages you use within your CRM.

    The event_name parameter should indicate a lead moving through the sales funnel in your CRM. Make sure to send all stages as they are updated, including the raw lead.

    event_time

    integer

    A Unix timestamp in seconds indicating when the lead stage update event is updated by your CRM.
    The timestamp must occur after the lead generation time or else the event may be discarded.

    action_source

    string

    Value: system_generated


    (By using the Conversions API, you agree that the action_source parameter is accurate to the best of your knowledge.)

    lead_id

    integer

    The 15 or 16 digit leadgen_id from your downloaded leads.

    lead_event_source

    string

    The name of the CRM where the events are coming from.

    event_source

    string

    Value: crm



    Example
    An example payload may look like this. Note: You must use a valid lead_id or else the system will reject your event. 
    {
    "data": [
        {
            "event_name": "initial_lead",
            "event_time": 1629424350,
            "action_source": "system_generated",
            "user_data": {
                "lead_id": 525645896321548
            },
            "custom_data": {
                "event_source": "crm",
                "lead_event_source": "salesforce"
            }
        }
    ]
}

  5. If events do not follow the payload specification or do not match a Meta lead ad, then they will not be recognized for the integration and will not be used for training the model.
    For example the Web payload would be accepted by the Conversions API and appear in Events Manager, but it will not be recognized for this integration. You must also use a valid lead_id or else the system will reject your event.
    Only the Conversion Leads payload will be recognized for the integration and used for training.

Step 2: Create an access token and an API call

Once you configure what you will send, the next step is to configure where you will send the data.

This step will help you generate an access token for your Meta Pixel, which will then be used to establish a connection between your server and the Conversions API.

  1. You can return to the CRM integration guide from the Settings tab of your CRM Pixel.

  2. Scroll down to the Create Endpoint section and click the Generate Access Token button. The access token will be used to build your API call.
    You can generate a new access token by returning to the integration guide or from the Settings tab in Events Manager by navigating to the Conversions API section and clicking the Generate access token link.

  3. The rest of this guide will vary depending on whether you are using Meta's SDK. Using the Meta Business SDK is recommended because they provide better error and diagnostic messaging. You will need your Pixel ID and access token to make the API call via the Meta Business SDK. You can get the access token by clicking Copy access token in the CRM integration guide and saving it. Examples of SDK API calls can be found in the Conversion API Developers Guide or the Get Code functionality within the Meta Payload Helper.

  4. This is the endpoint format to make a POST request to the Conversions API without the SDK. You can get the entire endpoint by clicking Copy endpoint in the CRM Integration guide and saving it. 
    https://graph.facebook.com/API_VERSION/PIXEL_ID/events?access_token=ACCESS_TOKEN
    • API_VERSION: The current Marketing API version
    • PIXEL_ID: The Pixel ID can be obtained from Events Manager for each Pixel
    • ACCESS_TOKEN: The access token generated above
  5. You can see the Marketing API release and expiration dates in the API Version documentation. Be sure to update the API version or the Meta Business SDK in your code before the Marketing API expiration date. Using a deprecated version in your code could result in errors and your events may be discarded by the system.

Step 3: Test a payload (optional)

At this point you may want to send a test payload to your Pixel before implementing the code on your server. You can do so by using the Test Events tab in Events Manager.

  1. In the Test Server Events section, click on the Graph API Explorer link. Using this unique link will prefill some information from your Pixel. (You can also directly access the Graph API Explorer if you wish.) Take note of the test_event_code value, which can change over time.

  2. Complete the following in the Graph API Explorer tool:
    1. Ensure you are in POST mode.
    2. Check that your API version and Pixel ID are correct.
    3. Switch to the JSON view.
    4. Input your payload. This can be manually created or generated using the Payload Helper. Make sure to include the test_event_code parameter from the previous step and a valid lead_id.
  3. Enter your Pixel access token, and click the Submit button.

  4. If your payload does not contain any syntax or API errors, you should receive a success message with a fbtrace_id.

  5. The test event should appear under the Test Events tab in Events Manager after a short time.

Step 4: Send production data

The production data should be in the same format as the payload generated in Step 3, except the data will be coming directly from your server. This step will vary for every integration so this section will provide guidelines rather than a walkthrough.

  1. Send the lead_id rather than PII for matching.

  2. Make sure to send all lead stages as they are updated, including the raw lead event that represents all leads generated on Meta and downloaded into your CRM. Below is an example funnel. The event names and stages are advertiser-defined so they do not have to conform to this example.


    If your campaigns generate 100 leads then we would expect 100 “Raw Lead” events uploaded to represent the first lead stage. Sending the first lead stage will let the system know that the lead was received and processed. As the leads move down the sales funnel, we would expect 70 “Marketing Qualified Lead”, 30 “Sales Opportunity", and 15 “Converted” stages to be uploaded.

    To recap, 100 leads are generated from the campaigns but we would expect 215 events to be uploaded in this example scenario.

  3. Create a function that retrieves updates from your CRM’s API or database whenever the lead status updates. Then send your payload to Meta’s Conversions API using a custom function or Meta’s business SDK. What makes the most sense for your integration will depend on your CRM and database configuration.

    Variables are recommended for:
    • lead_id
    • event_name
    • event_time
    For example, a payload that explicitly states the parameter values may look like this: 
    {
  "event_name": "initial_lead",
  "event_time": 1628294742,
  "user_data": {
    "lead_id": 1234567890123456
  },
  "action_source": "system_generated",
  "custom_data:" {
    "lead_event_source": "Salesforce",
    "event_source": "crm"
  }
}
    A payload that passes in values from your database using variables may look like this: 
    {
  "event_name": lead_stage // "initial_lead"
  "event_time": unix_time // 1628294742
  "user_data": {
    "lead_id": fb_lead_id // 1234567890123456
  },
  "action_source": "system_generated",
  "custom_data:" {
    "lead_event_source": "Salesforce",
    "event_source": "crm"
  }
}

  4. Upload data at least once a day. Ideally the calls to your CRM should be made in real-time, but you may employ hourly or daily batching methods if a real-time integration is not feasible.
    If you choose the batching methods, make sure you capture the lead status change history rather than a snapshot of the lead at the time of batching. For example, if a lead's status updates 3 times between batches, we would expect 3 events for this lead rather than just the final update.
    Note: Each batch can include up to 1,000 events. If there is an error in the batch, the whole batch will be discarded so we HIGHLY recommend employing smaller batches and adding logic for retrying attempts.

  5. Optional. We recommend logging error messages from the CAPI call and creating alerts if there are issues. Exception handling for these errors would also be a good idea.

  6. You can backfill your data for up to 7 days in the past. The time difference is calculated between event_time and upload_time. Backfilling some data may speed up the training process.

    WARNING: Do not attempt to backfill more than 7 days of data by modifying the event_time values. The model relies on an accurate time stamp to optimize. Doing so may cause all your backfilled data to be discarded.

  7. Ensure that your event_time values are after the lead generation timestamp, otherwise your events may be discarded.

  8. You should start seeing events appear in Events Manager for your Pixel within an hour if your integration is uploading events to Meta. Remember to use a valid lead_id in your payloads for events to appear. Open each event sent for the Conversion Leads CRM integration in Events Manager and check that they have the custom parameters lead_event_source and event_source populated. If the event does not have these parameters, it will not get registered as a Conversion Leads event.
  9. The system will verify if any of your events are valid Conversion Leads events. After 1 day, a green check will appear next to the Send a CRM event step of the integration if a valid event is detected.