Parameters

These are the parameters you need if you use the Server-Side API. We listed all required event data parameters and any additional data parameters you want Facebook to use for ads attribution and/or ads delivery optimization. In this page, you find:

Server-Side API: DocumentationUsing the API

Main Body Parameters

Name Description

data

type: Array(Objects)

Required.

An array of Server Event objects. See Server Event Parameter Table below.

test_event_code

type: String

Code used to verify that your server events are received correctly by Facebook. Use this code to test your server events in the Test Events feature in Events Manager. See Test Events Tool for an example.

Server Event Parameters

Name Description

event_name

type: string

Required.

A Facebook pixel Standard Event or Custom Event name. This is used with event_id to determine if events are identical. Learn about Deduplicate Pixel and Server-Side Events.

event_time

type: int

Required.

A Unix timestamp in seconds indicating when the actual event occurred.

user_data

type: Object

Required.

A map that contains user data. See User Data Parameter Table for options. Also see Advanced Matching with the Pixel to see comparable options available for data sent via Facebook pixel.

custom_data

type: Object

A map that includes additional business data about the event. See Custom Data Parameter Table.

event_source_url

type: String

The browser URL where the event happened.

opt_out

type: Boolean

A flag that indicates we should not use this event for ads delivery optimization. If set to true, we only use the event for attribution.

event_id

type: String

This ID can be any string chosen by the advertiser. This is used with event_name to determine if events are identical. Learn about Deduplicate Pixel and Server-Side Events.

User Data Parameters

user_data is a set of identifiers Facebook can use for targeted attribution. See Custom Audiences from CRM Data for details on how to normalize and hash the data you send.

For example, you should trim string data and send it in lower-case. You should also send all data hashed with SHA256 and UTF-8 encoding. We do not accept unhashed data, unless noted below.

You must provide at least one of these user_data keys in your request. If you send client_ip_address or client_user_agent, you must send both keys.

All of these values for these keys are of type String.

Key Type Key Name Hashing? Description

Email

em

Yes

An email address, in lowercase.

Example: joe@eg.com

Phone

ph

Yes

A phone number. Include only digits with country code, area code, and number.

Example: 16505551212

Gender

ge

Yes

Gender, in lowercase. Either f or m.

Date of Birth

db

Yes

A date of birth given as year, month, and day.

Example: 19971226 for December 26, 1997.

Last Name

ln

Yes

A last name in lowercase.

Example: smith

First Name

fn

Yes

A first name in lowercase.

Example: joe

City

ct

Yes

A city in lower-case without spaces or punctuation.

Example: menlopark

State

st

Yes

A two-letter state code in lowercase.

Example: ca

Zip

zp

Yes

If you are in the United States, this is a five-digit zip code. For other locations, follow each country's standards.

Example: 94035 (for United States)

Country

country

Yes

A two-letter country code in lowercase.

Example: us

External ID

external_id

Do not hash

Any unique ID from the advertiser, such as loyalty membership IDs, user IDs, and external cookie IDs. In the Offline Conversions API, this is known as extern_id. For more information, see Offline Conversions, Providing External IDs. If External ID is being sent via other channels, then it should be sent in the same format via the server-side API.

Client IP address

client_ip_address

Do not hash

The IP address of the browser corresponding to the event.

Client user agent

client_user_agent

Do not hash

The user agent for the browser corresponding to the event.

Click ID

fbc

Do not hash

The Facebook click ID value stored in the _fbc browser cookie under your domain. See Managing fbc and fbp Parameters for how to get this value, or generate this value from a fbclid query parameter.

Browser ID

fbp

Do not hash

The Facebook browser ID value stored in the _fbp browser cookie under your domain. See Managing fbc and fbp Parameters for how to get this value.

Subscription ID

subscription_id

Do not hash

The subscription ID for the user in this transaction. This is similar to the order ID for an individual product.

Example: anid1234.

You can send most of these user data parameters through the Facebook Pixel as well. For instance, to send external_id through the Pixel, use the following code

fbq('init', 'PIXEL_ID', {'external_id': 12345});

You can read about the other parameters you can pass in the Advanced Matching documentation.

Custom Data Parameters

Use these parameters to send additional data we can use for ads delivery optimization.

Name Description

value

type: Float

A numeric value associated with this event. This could be a monetary value or a value in some other metric.

Example: 142.54.

currency

type: String

The currency for the value specified, if applicable. Currency must be a valid ISO 4217 three digit currency code.

Example: 'USD'.

content_name

type: String

The name of the page or product associated with the event.

Example: 'lettuce'.

content_category

type: String

The category of the content associated with the event.

Example: 'grocery'.

content_ids

type: Array(String)

The content IDs associated with the event, such as product SKUs for items in an AddToCart event: ['ABC123', 'XYZ789']. If content_type is a product, then your content IDs must be an array with a single string value. Otherwise, this array can contain any number of string values.

contents

type: Array(Object)

A list of JSON objects that contain the product IDs associated with the event plus information about the products. id, quantity, and item_price are available fields.

Example: [{'id':'ABC123','quantity' :2,'item_price':5.99}, {'id':'XYZ789','quantity':2, 'item_price':9.99}]

content_type

type: String

A String equal to either product or product_group. Set to product if the keys you send content_ids or contents represent products. Set to product_group if the keys you send in content_ids represent product groups.

order_id

type: String

The order ID for this transaction as a String.

Example: 'order1234'.

predicted_ltv

type: Float

The predicted lifetime value of a conversion event, as a String.

Example: '432.12'.

num_items

type: String

Use only with InitiateCheckout events. The number of items that a user tries to buy during checkout.

Example: '4'.

search_string

type: String

Use only with Search events. A search query made by a user.

Example: 'lettuce'.

status

type: String

Use only with CompleteRegistration events. The status of the registration event, as a String.

Example: 'registered'.

Custom Properties

If our predefined object properties don't suit your needs, you can include your own, custom properties. Custom properties can be used with both standard and custom events, and can help you further define custom audiences.

This behavior is the same for Server-Side API and Facebook Pixel. See Facebook Pixel Custom Properties.

fbp and fbc Parameters

When the Facebook pixel is installed on a website, and the pixel uses first-party cookies, the pixel automatically saves a unique identifier to an _fbp cookie for the website domain if one does not already exist.

When a user clicks on an ad on Facebook, the link sometimes includes a fbclid query parameter. When the user lands on the target website, if the website has a Facebook pixel that uses first-party cookies, the pixel automatically saves the fbclid query parameter to an _fbc cookie for that website domain. See About Cookie Settings For Your Facebook Pixel for information on first-party cookie settings.

We recommend that you always send _fbc and _fbp browser cookie values in the fbc and fbp event parameters, respectively, when available.

If the _fbc browser cookie is not available, either because there is no Facebook pixel running on the website or because first-party cookies are turned off, it is still possible to send the fbc event parameter if an fbclid query parameter is in the URL of the current page request.

The fbc event parameter value must be of the form: version.subdomainIndex.creationTime.fbclid

  • version is always this prefix: fb
  • subdomainIndex is which domain the cookie is defined on ('com' = 0, 'facebook.com' = 1, 'www.facebook.com' = 2). If you’re generating this on a server and not saving an _fbc cookie, use the value 1.
  • creationTime is the UNIX time since epoch in seconds when the _fbc cookie was saved. If you’re generating this on a server and not saving an _fbc cookie.
  • fbclid is the value for the fbclid query parameter in the page URL.

Here’s an example of what the fbc value could look like (note that the fbclid portion is invalid):

fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890

Next Step: Payload Helper