Using the Server-Side API

Before implementing the API, make sure you have all the prerequisites listed on the main Server-Side API document. In this page, you learn to:

The Server-side API is based on Facebook's Marketing API. API calls are versioned, and the availability of each version is detailed in the Marketing API Changelog.

This API is under limited availability. Please contact your Facebook Representative to access it.

Server-Side API: DocumentationParameters

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": "PageView", "event_time": 1574440165, "user_data": { "fbc": "fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890", "fbp": "fb.1.1558571054389.1098115397", "em": "309a0a5c3e211326ae75ca18196d301a9bdbd1a882a4d2569511033da23f0abd" } } ]' \ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v5.0/<PIXEL_ID>/events
'use strict'; const bizSdk = require('facebook-nodejs-business-sdk'); const AdsPixel = bizSdk.AdsPixel; const access_token = '<ACCESS_TOKEN>'; const app_secret = '<APP_SECRET>'; const app_id = '<APP_ID>'; const id = '<ADS_PIXEL_ID>'; const api = bizSdk.FacebookAdsApi.init(access_token); const showDebugingInfo = true; // Setting this to true shows more debugging info. if (showDebugingInfo) { api.setDebug(true); } const logApiCallResult = (apiCallName, data) => { console.log(apiCallName); if (showDebugingInfo) { console.log('Data:' + JSON.stringify(data)); } }; let fields, params; fields = [ ]; params = { 'data' : [{'event_name':'PageView','event_time':1569260711,'user_data':{'fbc':'fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890','fbp':'fb.1.1558571054389.1098115397','em':'309a0a5c3e211326ae75ca18196d301a9bdbd1a882a4d2569511033da23f0abd'}}], }; const events = (new AdsPixel(id)).createEvent( fields, params ); logApiCallResult('events api call complete.', events);
require __DIR__ . '/vendor/autoload.php'; use FacebookAds\Api; use FacebookAds\Logger\CurlLogger; 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()) ->setFbc('fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890') ->setFbp('fb.1.1558571054389.1098115397') ->setEmail('joe@eg.com'); $event = (new Event()) ->setEventName('PageView') ->setEventTime(time()) ->setUserData($user_data); $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.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( email='joe@eg.com', fbc='fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890', fbp='fb.1.1558571054389.1098115397' ) event = Event( event_name='PageView', event_time=int(time.time()), user_data=user_data, ) 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.Event; import com.facebook.ads.sdk.serverside.EventRequest; import com.facebook.ads.sdk.serverside.EventResponse; import com.facebook.ads.sdk.serverside.UserData; 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() .fbc("fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890") .fbp("fb.1.1558571054389.1098115397") .email("joe@eg.com"); Event pageViewEvent = new Event(); pageViewEvent.eventName("PageView") .eventTime(System.currentTimeMillis() / 1000L) .userData(userData); EventRequest eventRequest = new EventRequest(PIXEL_ID, context); eventRequest.addDataItem(pageViewEvent); 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>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ADS_PIXEL_ID>' FacebookAds.configure do |config| config.access_token = access_token config.app_secret = app_secret end ads_pixel = FacebookAds::AdsPixel.get(id) events = ads_pixel.events.create({ data: [{'event_name':'PageView','event_time':1569260711,'user_data':{'fbc':'fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890','fbp':'fb.1.1558571054389.1098115397','em':'309a0a5c3e211326ae75ca18196d301a9bdbd1a882a4d2569511033da23f0abd'}}], })

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 endpoint:

An example request body looks like this:

{ "data": [ { "event_name": "Purchase", "event_time": 1574439565, "event_id": "event.id.123", "event_source_url": "http:\/\/jaspers-market.com\/product\/123", "user_data": { "client_ip_address": "192.19.9.9", "client_user_agent": "test ua", "em": "309a0a5c3e211326ae75ca18196d301a9bdbd1a882a4d2569511033da23f0abd", "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": 1574439565, "user_data": { "client_ip_address": "192.88.9.9", "client_user_agent": "test ua2" }, "custom_data": { "value": 50.5, "currency": "USD" }, "opt_out": true } ] }

Dropped Events

Network errors or malformed requests may cause events to be dropped.

Upload Time versus Event Transaction Time

event_time is the event transaction time, and it may be earlier than the time you send the event to Facebook. This is to enable batch processing and server performance optimization. event_time can be up to 7 days before you send an event to Facebook. 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.

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.

Server-Side Parameters

Verify Events

After you send your events, confirm that we have received them in the overview and breakdown views:

  • Go to Business Manager > Pixels.
  • Click on the pixel corresponding to the PIXEL_ID in your POST request.

Overview

  • Change the View tab from All to Server. You see the number of events you have successfully sent.

Breakdown

  • Change the higher level Overview tab from Overview to Breakdown. You see the breakdown of the events that you have successfully sent.
  • Dropped events will not show up in the "Server Events Received" column.

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 > Server.

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

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

{ "data": [ { "event_name": "ViewContent", "event_time": 1574439565, "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 will appear in Graph API Explorer.

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

Deduplicate Pixel and Server-Side Events

Facebook tries to deduplicate identical events sent from the Facebook Pixel and the Server-Side Events API. We determine if events are identical based on their ID and name. For your event to be deduplicated, we need the following field matches:

  • Facebook Pixel's eventID must match Server-Side's event_id, in corresponding events
  • Facebook Pixel's event must match Server-Side's event_name, in corresponding events

For better matching, we need accurate information from both your Facebook Pixel and Server-Side Events API:

  • The eventID in the optional eventData parameter should be a unique value. Depending on your pixel implementation, you can use:
    • track: send the event for all pixels on the page,
    • trackSingle: send the event for one pixel,
    • an image pixel tag with the eid parameter.
fbq('track', 'Purchase', {value: 12, currency: 'USD'}, {eventID: 'EVENT_ID'});
fbq('trackSingle', 'SPECIFIC_PIXEL_ID', 'Purchase', {value: 12, currency: 'USD'}, {eventID: 'EVENT_ID'});
<img src="https://www.facebook.com/tr?id=PIXEL_ID&event=Purchase&eid=EVENT_ID"/>
  • The eventID from Facebook pixel must match the event_id in the corresponding server-side API event.

  • If we find the same server key combination (event_id, event_name) and browser key combination (eventID, event) sent to the same pixel ID within 48 hours, we discard the subsequent events. There is one exception to this: if a server and browser event arrive at approximately the same time (within 5 minutes of each other), we favor the browser event.

Debug

This API returns minimal data to conserve network bandwidth. If the event payload is valid, a 2xx HTTP response code is returned. If invalid, a 4xx HTTP response code is returned, with minimal error details in the response body.

You can get more detailed information for debugging any request by making a POST request to /events/?trace= in Graph API Explorer.

Options for trace include:

  • 1 - Error
  • 2 - Info
  • 3 - Debug

This API is under limited availability. Please contact your Facebook Representative if you believe that you have been granted access, but encounter one of the following errors:

  • "Application does not have the capability to make this API call."
  • "This pixel is not authorized to report server events."

API Limits

The Marketing API has it is 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 Server-Side API. Server-Side 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.

API-Level LimitsApp-Level LimitsAd Account Level LimitsAd Set Level LimitsAd Level Limits

Getting Support

Under the hood, all Facebook APIs share the same infrastructure. Searching the Facebook Developers website may reveal more relevant information for your specific situation. You can also visit the Developer Support page, check open bugs, and drop by the Facebook Developer Community Forum.

Other helpful resources are: