Using the API

Once you have completed the prerequisites on the Get Started page, use this page to learn how to send events and use the Test Events tool. Once you’ve sent an event, verify your setup.

The Conversions API is based on Facebook's Marketing API, which was built on top of our Graph API. Marketing and Graph APIs have different version deprecation schedules. Our release cycle is aligned with the Graph API, so every version is supported for at least two years. This exception is only valid for the Conversions API.

Conversions API: OverviewParameters

Web, app, and physical store events shared using the Conversions API require specific parameters. By using the Conversions API, you agree that the action_source parameter is accurate to the best of your knowledge. The list of required parameters is available here.

Send Requests

To send new events, make a POST request to this API's /events edge from this path: https://graph.facebook.com/{API_VERSION}/{PIXEL_ID}/events?access_token={TOKEN}. When you post to this edge, Facebook creates new server events.

curl -X POST \ -F 'data=[ { "event_name": "Purchase", "event_time": 1733319709, "user_data": { "em": [ "309a0a5c3e211326ae75ca18196d301a9bdbd1a882a4d2569511033da23f0abd" ], "ph": [ "254aa248acb47dd654ca3ea53f48c2c26d641d23d7e2e93a1ec56258df7674c4", "6f4fcb9deaeadc8f9746ae76d97ce1239e98b404efe5da3ee0b7149740f89ad6" ], "client_ip_address": "123.123.123.123", "client_user_agent": "$CLIENT_USER_AGENT", "fbc": "fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890", "fbp": "fb.1.1558571054389.1098115397" }, "custom_data": { "currency": "usd", "value": 123.45, "contents": [ { "id": "product123", "quantity": 1, "delivery_category": "home_delivery" } ] }, "event_source_url": "http://jaspers-market.com/product/123", "action_source": "website" } ]' \ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v21.0/<PIXEL_ID>/events
'use strict'; const bizSdk = require('facebook-nodejs-business-sdk'); const Content = bizSdk.Content; const CustomData = bizSdk.CustomData; const DeliveryCategory = bizSdk.DeliveryCategory; const EventRequest = bizSdk.EventRequest; const UserData = bizSdk.UserData; const ServerEvent = bizSdk.ServerEvent; const access_token = '<ACCESS_TOKEN>'; const pixel_id = '<ADS_PIXEL_ID>'; const api = bizSdk.FacebookAdsApi.init(access_token); let current_timestamp = Math.floor(new Date() / 1000); const userData = (new UserData()) .setEmails(['joe@eg.com']) .setPhones(['12345678901', '14251234567']) // It is recommended to send Client IP and User Agent for Conversions API Events. .setClientIpAddress(request.connection.remoteAddress) .setClientUserAgent(request.headers['user-agent']) .setFbp('fb.1.1558571054389.1098115397') .setFbc('fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890'); const content = (new Content()) .setId('product123') .setQuantity(1) .setDeliveryCategory(DeliveryCategory.HOME_DELIVERY); const customData = (new CustomData()) .setContents([content]) .setCurrency('usd') .setValue(123.45); const serverEvent = (new ServerEvent()) .setEventName('Purchase') .setEventTime(current_timestamp) .setUserData(userData) .setCustomData(customData) .setEventSourceUrl('http://jaspers-market.com/product/123') .setActionSource('website'); const eventsData = [serverEvent]; const eventRequest = (new EventRequest(access_token, pixel_id)) .setEvents(eventsData); eventRequest.execute().then( response => { console.log('Response: ', response); }, err => { console.error('Error: ', err); } );
require __DIR__ . '/vendor/autoload.php'; use FacebookAds\Api; use FacebookAds\Logger\CurlLogger; use FacebookAds\Object\ServerSide\ActionSource; use FacebookAds\Object\ServerSide\Content; use FacebookAds\Object\ServerSide\CustomData; use FacebookAds\Object\ServerSide\DeliveryCategory; use FacebookAds\Object\ServerSide\Event; use FacebookAds\Object\ServerSide\EventRequest; use FacebookAds\Object\ServerSide\UserData; $access_token = '<ACCESS_TOKEN>'; $pixel_id = '<ADS_PIXEL_ID>'; $api = Api::init(null, null, $access_token); $api->setLogger(new CurlLogger()); $user_data = (new UserData()) ->setEmails(array('joe@eg.com')) ->setPhones(array('12345678901', '14251234567')) // It is recommended to send Client IP and User Agent for Conversions API Events. ->setClientIpAddress($_SERVER['REMOTE_ADDR']) ->setClientUserAgent($_SERVER['HTTP_USER_AGENT']) ->setFbc('fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890') ->setFbp('fb.1.1558571054389.1098115397'); $content = (new Content()) ->setProductId('product123') ->setQuantity(1) ->setDeliveryCategory(DeliveryCategory::HOME_DELIVERY); $custom_data = (new CustomData()) ->setContents(array($content)) ->setCurrency('usd') ->setValue(123.45); $event = (new Event()) ->setEventName('Purchase') ->setEventTime(time()) ->setEventSourceUrl('http://jaspers-market.com/product/123') ->setUserData($user_data) ->setCustomData($custom_data) ->setActionSource(ActionSource::WEBSITE); $events = array(); array_push($events, $event); $request = (new EventRequest($pixel_id)) ->setEvents($events); $response = $request->execute(); print_r($response);
import time from facebook_business.adobjects.serverside.action_source import ActionSource from facebook_business.adobjects.serverside.content import Content from facebook_business.adobjects.serverside.custom_data import CustomData from facebook_business.adobjects.serverside.delivery_category import DeliveryCategory from facebook_business.adobjects.serverside.event import Event from facebook_business.adobjects.serverside.event_request import EventRequest from facebook_business.adobjects.serverside.user_data import UserData from facebook_business.api import FacebookAdsApi access_token = '<ACCESS_TOKEN>' pixel_id = 'ADS_PIXEL_ID>' FacebookAdsApi.init(access_token=access_token) user_data = UserData( emails=['joe@eg.com'], phones=['12345678901', '14251234567'], # It is recommended to send Client IP and User Agent for Conversions API Events. client_ip_address=request.META.get('REMOTE_ADDR'), client_user_agent=request.headers['User-Agent'], fbc='fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890', fbp='fb.1.1558571054389.1098115397', ) content = Content( product_id='product123', quantity=1, delivery_category=DeliveryCategory.HOME_DELIVERY, ) custom_data = CustomData( contents=[content], currency='usd', value=123.45, ) event = Event( event_name='Purchase', event_time=int(time.time()), user_data=user_data, custom_data=custom_data, event_source_url='http://jaspers-market.com/product/123', action_source=ActionSource.WEBSITE, ) events = [event] event_request = EventRequest( events=events, pixel_id=pixel_id, ) event_response = event_request.execute() print(event_response)
import com.facebook.ads.sdk.APIContext; import com.facebook.ads.sdk.APIException; import com.facebook.ads.sdk.serverside.ActionSource; import com.facebook.ads.sdk.serverside.Content; import com.facebook.ads.sdk.serverside.CustomData; import com.facebook.ads.sdk.serverside.DeliveryCategory; import com.facebook.ads.sdk.serverside.Event; import com.facebook.ads.sdk.serverside.EventRequest; import com.facebook.ads.sdk.serverside.EventResponse; import com.facebook.ads.sdk.serverside.UserData; import java.util.Arrays; public class ServerSideApiExample { public static final String ACCESS_TOKEN = "<ACCESS_TOKEN>"; public static final String PIXEL_ID = "<ADS_PIXEL_ID>"; public static void main(String[] args) { APIContext context = new APIContext(ACCESS_TOKEN).enableDebug(true); context.setLogger(System.out); UserData userData = new UserData() .emails(Arrays.asList("joe@eg.com")) .phones(Arrays.asList("12345678901", "14251234567")) // It is recommended to send Client IP and User Agent for Conversions API Events. .clientIpAddress(clientIpAddress) .clientUserAgent(clientUserAgent) .fbc("fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890") .fbp("fb.1.1558571054389.1098115397"); Content content = new Content() .productId("product123") .quantity(1L) .deliveryCategory(DeliveryCategory.home_delivery); CustomData customData = new CustomData() .addContent(content) .currency("usd") .value(123.45F); Event purchaseEvent = new Event(); purchaseEvent.eventName("Purchase") .eventTime(System.currentTimeMillis() / 1000L) .userData(userData) .customData(customData) .eventSourceUrl("http://jaspers-market.com/product/123") .actionSource(ActionSource.website); EventRequest eventRequest = new EventRequest(PIXEL_ID, context); eventRequest.addDataItem(purchaseEvent); try { EventResponse response = eventRequest.execute(); System.out.println(String.format("Standard API response : %s ", response)); } catch (APIException e) { e.printStackTrace(); } } }
require 'facebook_ads' access_token = '<ACCESS_TOKEN>' pixel_id = '<ADS_PIXEL_ID>' FacebookAds.configure do |config| config.access_token = access_token end user_data = FacebookAds::ServerSide::UserData.new( emails: ['joe@eg.com'], phones: ['12345678901', '14251234567'], # It is recommended to send Client IP and User Agent for Conversions API Events. client_ip_address: request.remote_ip, client_user_agent: request.user_agent, fbc: 'fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890', fbp: 'fb.1.1558571054389.1098115397' ) content = FacebookAds::ServerSide::Content.new( product_id: 'product123', quantity: 1, delivery_category: 'home_delivery' ) custom_data = FacebookAds::ServerSide::CustomData.new( contents: [content], currency: 'usd', value: 123.45 ) event = FacebookAds::ServerSide::Event.new( event_name: 'Purchase', event_time: Time.now.to_i, user_data: user_data, custom_data: custom_data, event_source_url: 'http://jaspers-market.com/product/123', action_source: 'website' ) request = FacebookAds::ServerSide::EventRequest.new( pixel_id: pixel_id, events: [event] ) print request.execute

Attach your generated secure access token using the access_token query parameter to the request. You can also use Graph API Explorer to POST to the /<pixel_id>/events endpoint.

An example request body looks like this:

{
   "data": [
      {
         "event_name": "Purchase",
         "event_time": 1633552688,
         "event_id": "event.id.123",
         "event_source_url": "http:\/\/jaspers-market.com\/product\/123",         
         "action_source": "website",
         "user_data": {
            "client_ip_address": "192.19.9.9",
            "client_user_agent": "test ua",
            "em": [
               "309a0a5c3e211326ae75ca18196d301a9bdbd1a882a4d2569511033da23f0abd"
            ],
            "ph": [
               "254aa248acb47dd654ca3ea53f48c2c26d641d23d7e2e93a1ec56258df7674c4",
               "6f4fcb9deaeadc8f9746ae76d97ce1239e98b404efe5da3ee0b7149740f89ad6"
            ],
            "fbc": "fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890",
            "fbp": "fb.1.1558571054389.1098115397"
         },
         "custom_data": {
            "value": 100.2,
            "currency": "USD",
            "content_ids": [
               "product.id.123"
            ],
            "content_type": "product"
         },
         "opt_out": false
      },
      {
         "event_name": "Purchase",
         "event_time": 1633552688,
         "user_data": {
            "client_ip_address": "192.88.9.9",
            "client_user_agent": "test ua2"
         },
         "custom_data": {
            "value": 50.5,
            "currency": "USD"
         },
         "opt_out": false
      }
   ]
}

Upload Time versus Event Transaction Time

event_time is the event transaction time. It should be sent as a Unix timestamp in seconds indicating when the actual event occurred. The specified time may be earlier than the time you send the event to Facebook. This is to enable batch processing and server performance optimization.

The event_time can be up to 7 days before you send an event to Meta. If any event_time in data is greater than 7 days in the past, we return an error for the entire request and process no events. For offline and physical store events with physical_store as action_source, you should upload transactions within 62 days of the conversion.

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

Batch Requests

You can send up to 1,000 events in data. However, for optimal performance, we recommend you send events as soon as they occur and ideally within an hour of the event occurring. If any event you send in a batch is invalid, we reject the entire batch.

Hashing

Please check our customer information parameters page to see which parameters should be hashed before they are sent to Facebook. If you are using one of our Business SDKs, the hashing is done for you by the SDK.

Business SDK Features for Conversions API

Learn more about three specific Business SDK features designed especially for Conversions API users: Asynchronous Requests, Concurrent Batching, and HTTP Service Interface. Minimum language version required to use these features:

  • PHP >= 7.2
  • Node.js >= 7.6.0
  • Java >= 8
  • Python >= 2.7
  • Ruby >= 2

Business SDK support for PHP 5 has been deprecated since January 2019. Please upgrade to PHP 7 to use the Business SDK.

If you must use PHP 5, consider using our Swagger implementation.

Conversions API Parameters

Verify Events

After you send your events, confirm that we have received them in Events Manager:

  • On the Data Sources page, click on the Pixel corresponding to the PIXEL_ID in your POST request. For more information see Business Help Center: Navigate Events Manager.
  • Then, click Overview. You see the number of raw, matched and attributed events we received. Under Connection Method, you see the channel in which that event was sent.
  • You can click on each event to get more specific information.
  • After you start sending events, you should be able to verify them within 20 minutes. Now you can start sending events from your server.

Test Events Tool

You can verify that your server events are received correctly by Facebook by using the Test Events feature in Events Manager. To find the tool, go to Events Manager > Data Sources > Your Pixel > Test Events.

The Test Events tool generates a test ID. Send the test ID as a test_event_code parameter to start seeing event activity appear in the Test Events window.

Note: The test_event_code field should be used only for testing. You need to remove it when sending your production payload.

Events sent with test_event_code are not dropped. They flow into Events Manager and are used for targeting and ads measurement purposes.

Here's an example of how the request should be structured:

{ "data": [ { "event_name": "ViewContent", "event_time": 1733319109, "event_id": "event.id.123", "event_source_url": "http:\/\/jaspers-market.com", "user_data": { "client_ip_address": "1.2.3.4", "client_user_agent": "test user agent" } } ], "test_event_code": "TEST123" }

Here's an example of how the request appears in Graph API Explorer:

You can generate this test payload using the Payload Helper tool. Please note that the test event code is only for testing payload.

Your server events appear in the Test Events window once the request is sent.

Data Processing Options for US Users

For these two APIs, implement data processing options by adding data_processing_options, data_processing_options_country, and data_processing_options_state inside each event within the data parameter of your events.

Note: The App Events and Offline Conversions APIs are no longer recommended for new integrations. Instead, it is recommended that you use the Conversions API as it now supports web, app, and offline events. See Conversions API for App Events and Conversions API for Offline Events for more information.

To explicitly not enable Limited Data Use (LDU), specify an empty array for each event or simply remove the field in the payload:

{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": <EVENT_TIME>,
            "user_data": {
                "em": "<EMAIL>"
            },
            "custom_data": {
                "currency": "<CURRENCY>",
                "value": "<VALUE>"
            },
            "data_processing_options": []
        }
    ]
}

To enable LDU and have Meta perform geolocation:

{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": <EVENT_TIME>,
            "user_data": {
                "em": "<EMAIL>",
                "client_ip_address": "256.256.256.256"
            },
            "custom_data": {
                "currency": "<CURRENCY>",
                "value": "<VALUE>"
            },
            "data_processing_options": ["LDU"],
            "data_processing_options_country": 0,
            "data_processing_options_state": 0
        }
    ]
}

To enable LDU and manually specify the location, e.g., for California:

{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": <EVENT_TIME>,
            "user_data": {
                "em": "<EMAIL>"
            },
            "custom_data": {
                "currency": "<CURRENCY>",
                "value": "<VALUE>"
            },
            "data_processing_options": ["LDU"],
            "data_processing_options_country": 1,
            "data_processing_options_state": 1000
        }
    ]
}

Manual Upload UI

The Offline Conversions API offers the option to manually upload your events from a .csv file. In this case, add Data Processing Options, Data Processing Country, and Data Processing State as columns inside your file. More information about this can be found in the upload user interface.


Learn more about Data Processing Options.

API Limits

The Marketing API has its own rate-limiting logic and is excluded from all the Graph API rate limitations. So if you make a Marketing API call, it won't be calculated into the Graph API throttling.

There is no specific rate limit for the Conversions API. Conversions API calls are counted as Marketing API calls. The only limitation is that you can send us up to 1,000 events at a time. See Send Requests for more information.

Marketing API Rate Limiting

Business SDK API Usage in the Conversions API Gateway

This guide helps you navigate Meta Business SDK advanced features designed especially for Conversions API Gateway users. For basic Conversions API Gateway usage, refer to the Conversions API Gateway documentation.

Send Events to Your Conversions API Gateway Instance

Requirements

Before using any of the features listed below, you need to have the Meta Business SDK installed. See Get Started with the Meta Business SDK or follow the README instructions listed here:

Currently, these features are only available on the PHP and Java business SDK. The other languages will be implemented by the end of 2023.

The minimum language version required to use these features are:

PHP >= 7.2

Java >= 8

Note: To dedupe events to the Conversions API endpoint, please pass the eventId in your request. This will help prevent duplicate events from showing up if Conversions API publishing is enabled.

Formatting the CAPIGatewayIngressRequest Parameters

ParameterDescription
endpointUrl
string

The Conversions API Gateway endpoint that events get sent to. No prevalidation will be done on the parameter other than checking if it is a valid url.


Example: https://test.example.com


accessKey
string

Conversions API Gateway access key that is needed to send events to the Conversions API Gateway events endpoint. These are the instructions for generating it.

The CAPIGatewayIngressRequest Setters

ParameterDescription
setSendToDestinationOnly
Boolean

Boolean flag on whether the events get sent to the selected endpoint only.


Default: False


setFilter
CustomEndpointRequest.Filter() function

Filter function that processes each event. If the filtering logic returns true, the event gets passed through. Otherwise, the event gets dropped. You have to implement the shouldSendEvent function in the interface that has the parameter Event.


Default: Null



Migration Example: PHP

For systems that already use the Business SDK, you just need to reference the new CAPIGatewayIngressRequest and attach it to the eventRequest’s customEndpoint object.

// this is the standard event request that we attach events to
$event_request = new EventRequest($this->pixel_id);
$capiIngressRequest = new CAPIGatewayIngressRequest($this->cb_url, $this->access_key);
$event_request->setCustomEndpoint($capiIngressRequest);
// pass the events to this event Request object
$event_request->setEvents($events);
$event_request->execute()

Migration Example: Java

For systems that already use the Business SDK, you just need to reference the new CAPIGatewayIngressRequest and attach it to the eventRequest’s customEndpoint object.

// this is the standard event request that we attach events to


EventRequest eventRequest = new EventRequest(PIXEL_ID, context);


CAPIGatewayIngressRequest capiSyncRequest = new CAPIGatewayIngressRequest(CB_URL, CAPIG_ACCESS_KEY);
eventRequest.setCustomEndpoint(capiSyncRequest);
eventRequest.addDataItem(testEvent);
eventRequest.execute();

Synchronous option

PHP Code Example

$api = Api::init(null, null, $this->access_token);
$api->setLogger(new CurlLogger());
$event_request = new EventRequest($this->pixel_id);
$capiIngressRequest = new CAPIGatewayIngressRequest($this->cb_url, $this->access_key);
$event_request->setCustomEndpoint($capiIngressRequest);
$user_data = (new UserData())
   ->setEmails(array('joe@eg.com'))
   ->setPhones(array('12345678901', '14251234567'))
   ->setFbc('fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890')
   ->setFbp('fb.1.1558571054389.1098115397');
$event1 = (new Event())
   ->setEventName('Purchase')
   ->setEventId('125')
   ->setEventTime(time())
   ->setEventSourceUrl('http://jaspers-market.com/product/123')
   ->setUserData($user_data);
$events = array($event1, $event2);
$event_request->setEvents($events);
$response = $event_request->execute();
print($response->__toString());

Java Code Example

EventRequest eventRequest = new EventRequest(PIXEL_ID, context);
UserData userData = new UserData()
       .email("abc@eg.com");
CAPIGatewayIngressRequest capiSyncRequest = new CAPIGatewayIngressRequest(CB_URL, CAPIG_ACCESS_KEY);
eventRequest.setCustomEndpoint(capiSyncRequest);
Event testEvent = new Event();
testEvent.eventId("125").eventName("Purchase")
       .eventTime(System.currentTimeMillis() / 1000L)
       .userData(userData)
       .dataProcessingOptions(new String[]{}).setEventId("134423232");
eventRequest.namespaceId("11")
       .uploadId("22222")
       .uploadTag("upload-tag-4")
       .uploadSource("upload-source-4")
       .testEventCode("test-event-code-5")
       .partnerAgent("partner-agent-6");
eventRequest.addDataItem(testEvent);
eventRequest.execute();

Asynchronous option

PHP Code Example

$api = Api::init(null, null, $this->access_token);
$api->setLogger(new CurlLogger());
$event_request = new EventRequestAsync($this->pixel_id);
$capiIngressRequest = new CAPIGatewayIngressRequest($this->cb_url, $this->access_key);
$capiIngressRequest->setSendToDestinationOnly(true);
$event_request->setCustomEndpoint($capiIngressRequest);
$event1 = (new Event())
   ->setEventName('test Async Event')
   ->setEventId('134423232')
   ->setEventTime(time())
   ->setEventSourceUrl('http://jaspers-market.com/product/123');
$events = array($event1, $event2);
$event_request->setEvents($events);
$response = $event_request->execute()->wait();

Java Code Example

EventRequest eventRequest = new EventRequest(PIXEL_ID, context);
UserData userData = new UserData()
       .email("abc@eg.com");
CAPIGatewayIngressRequest capiSyncRequest = new CAPIGatewayIngressRequest(CB_URL, CAPIG_ACCESS_KEY);
capiSyncRequest.setSendToDestinationOnly(true);
eventRequest.setCustomEndpoint(capiSyncRequest);
Event testEvent = new Event();
testEvent.eventName("test Async Event")
       .eventTime(System.currentTimeMillis() / 1000L)
       .userData(userData)
       .dataProcessingOptions(new String[]{}).setEventId("134423232");
eventRequest.namespaceId("11222")
       .uploadId("22222")
       .uploadTag("upload-tag-4")
       .uploadSource("upload-source-4")
       .testEventCode("test-event-code-5")
       .partnerAgent("partner-agent-6");
eventRequest.addDataItem(testEvent);
eventRequest.executeAsync();

Filter Functionality

PHP Code Example

lass APIFilter implements Filter {
   public function shouldSendEvent(Event $event): bool
   {
       if ($event->getEventId() === '125') {
           return false;
       }
       return true;
   }
}
$capiIngressRequest = new CAPIGatewayIngressRequest($this->cb_url, $this->access_key);
$event_request->setCustomEndpoint($capiIngressRequest);
$capiIngressRequest->setFilter(new APIFilter());

Java Code Example

CAPIGatewayIngressRequest capiSyncRequest = new CAPIGatewayIngressRequest(CB_URL, CAPIG_ACCESS_KEY);
eventRequest.setCustomEndpoint(capiSyncRequest);


capiSyncRequest.setFilter(new CustomEndpointRequest.Filter() {
   @Override
   public boolean shouldSendEvent(Event event) {
   if (event.getEventId().equals("125")) {
       return true;
   }
   return false;
}
});