Conversions API:

Direct
Integration
Playbook for
Developers
Introduction
Conversions API is a Facebook Business Tool that lets
you share key web and offline events, or customer
actions, directly from your server to Facebook’s.
Conversions API works with your Facebook pixel to help
improve the performance and measurement of your
Facebook ad campaigns. Table of contents
Preparation p.2
A direct Conversions API integration is a great choice for
businesses that have developer resources available, Implementing the API p.4
access to their server codebase, and need the ability to Send events p.5
customize their configuration, control what data they Add parameters to events p.6
share to Facebook and when they share it. Test events p.9
Verify events p.10
Alternatively, businesses that need faster and easier
Conversions API setups often use Facebook Business Troubleshoot and optimal configuration p.12
Partners that offer Conversions API as one of several Glossary and additional resources p.19
consolidated business solutions.

Learn more about comparing these two integration

options on the Facebook for Business Help Center.

Watch this webinar where Facebook Conversions API

experts guide you through implementing the
Conversions API.
Conversions API: 2
Direct Integration Playbook

1. Preparation
Before you begin building your direct Conversions API integration, you’ll need a Facebook pixel, Business
Manager and access token.

Facebook Pixel Business Manager

• Make sure you have the Facebook pixel • To use the Conversions API, you need a
correctly implemented in your website Business Manager account

• We recommend that you use the same pixel • Business Manager is a Facebook tool that
for your browser and server events helps you organize and manage your business

• If you don't have a Business Manager

account, you can create one at
business.facebook.com/overview

Before you Create a Business Manager

Make sure that you have a personal Facebook account to confirm your identity.

• You use your Facebook username and password to sign into Business Manager

To create a Business Manager

• Go to business.facebook.com/overview

• Click Create Account

• Enter a name for your business, your name and work email address and click Next

• Enter your business details and click Submit

Note
You can create only 2 Business Manager accounts. If you need more, please work with someone else in your
organization to create additional Business Manager accounts.
Conversions API: 3
Direct Integration Playbook

Access Token
• To use the Conversions API, you need an access token, which is passed as a parameter in each API call

• You can generate an access token through Events Manager (recommended) or, if you already have your
own app and your own system user, you can generate an access token inside Business Manager

• For either option, there is no need to go through App Review or to request any permissions

Instructions for creating an access token:

Option A (Recommended) Option B

Generate access token in Events Manager Generate access token in Business Manager

1. Choose a pixel (we recommend starting with 1. Go to your Business' Settings

the pixel and main event you use for optimization)
2. Assign a pixel to your system user (you also
2. Navigate to “Settings” > “Conversions API” > have an option to create a new system user at
“Set up manually” > “Generate access token” link this stage)

3. Select the assigned system user and click

Generate Token

Note
The “Generate access token” link is only visible to
users with developer privileges for the business.
The link is hidden from other users.

3. Follow the pop-up instructions

4. Once you have your token, navigate to the

“Implementation” tab and follow the
instructions displayed in the screen. This way,
we automatically create a Conversions API App
and Conversions API System User for you
Conversions API: 4
Direct Integration Playbook

2. Implementing the API

1 Go to Events Manager

2 Start by sending a test event to the API

If this is your first time using the API

Start with a test call. You’ll need a payload and a API call method:

Generate payload Make an API call with the payload

To create your payload from the Payload Once you are satisfied with your payload, decide
Helper tool, add your pixel ID under “Test this how to make your call.
Payload” and click on Send to Test Events
• You can use our Graph API Explorer or cURL
• You should be able to see the event on
• Independently on your call method, you should
Events Manager > Your Pixel > Test Events
call the /{pixel_id}/events endpoint and
• Learn more about the Test Events Tool attach the JSON data generated by the Payload
Helper tool

If you need additional guidance for completing your first API call, watch this video tutorial
Conversions API: 5
Direct Integration Playbook

3. Send events
The most important events to send using Best practices for upload times, batching,
Conversions API are your optimization events and timeouts:
(usually a conversion event like “purchase”). That
said, we recommend sending events throughout event_time should be sent as a Unix timestamp*
your purchase funnel (as advertisers often do with in seconds indicating when the actual event
the pixel). occurred.

• To send events from your server, make a POST • *Note: Unix timestamps are timezone agnostic
request to this API's /events edge from this path: • The delay between event_time and the time
https://graph.facebook.com/{API_VERSION} you send to Facebook should be as close to 0 as
/{PIXEL_ID}/events?access_token={TOKEN} possible, and no longer than 7 days (if longer than
• When you post to this edge, Facebook creates 7 days, we return an error for the entire request
new server events and process no events)

• Attach your generated secure access token

using the access_token query parameter to
You can batch up to 1,000 events in data.
the request
• However, we recommend sending events in
• You can also use Graph API Explorer to POST
real time as soon as they occur, or ideally within
to the /<pixel_id>/events endpoint for
an hour
testing purposes
• If any event you send in a batch is invalid, we
reject the entire batch

You can also use open source editor Swagger to

generate client-side API code for the
Conversions API. Network errors or malformed requests may
cause dropped events.
• The generated code handles the API calls,
exception handling, and retries • We recommend retrying the request in cases
where the HTTP response indicates a
• To use Swagger, you need Java (version 7 non-client error, such as a timeout
or higher)
• To account for network delays, we
• Learn more about our Swagger API recommend setting a timeout of 1500
integration on github milliseconds on the request

• For the majority of requests, the response

time will be under 600 milliseconds
Conversions API: 6
Direct Integration Playbook

4. Add parameters to all events

Customer information parameters are needed in matching events to a Facebook account. Some of these
parameters are also used as deduplication keys for redundant browser + server events.

• Only matched and processed events can be used for ads attribution and ad delivery optimization

• The more customer information parameters you add, the more effective your customer information
may be at matching your server event to a Facebook account, which may improve campaign performance

Later in this guide (in the Event Match Quality (EMQ) score section), we describe how the parameters you
send can improve Event Match Quality—the better your EMQ score, the more effective your event may be at
matching to Facebook account. Only matched events can be used for targeting and optimization.

Note
“Hashing needed” indicates these fields contain personally identifiable information (PII). This data
must be hashed with SHA256 and UTF-8 encoding. We do not accept this data unhashed and reject
the entire event.

The following server event parameters are required and recommended:

Required parameters (events missing these parameters will not be processed):

• client_user_agent (for web events) - Do not hash

The user_agent parameter is a field that identifies the web browser (i.e. Safari, Chrome, Firefox,
etc.) on which a website event occurred

• event_source_url (for web events)

The event_source_url is a field that identifies the website URL where a website event occurred.
It is most appropriately set as the specific page of a specific website where the event occurred

• action_source (for web and non-web events)

The action_source parameter is a field that identifies where the event occurred (i.e. website,
email, phone call, store, etc.)
Conversions API: 7
Direct Integration Playbook

Recommended parameters (events missing these parameters will still be processed, but may not be
effectively matched and deduplicated):

• external_id
external id is a string that represents a user on an advertiser’s system, like loyalty membership
IDs, user IDs, and external cookie IDs. You can send one or more external_ IDs for a given event and
we try to match it to someone on Facebook

• event_id
This ID can be any unique string chosen by the advertiser. event_id is used to deduplicate events
sent by both Facebook Pixel and Conversions API. event_name is also used in deduplication

When hashed PII is available, add the following parameters

Additional parameters to add for improved event matching:

Email address (em) - Hashing needed Zip (zp) - Hashing needed

Phone number (ph) - Hashing needed Country (country) - Hashing needed
Gender (ge) - Hashing needed Client IP address (client_ip_address) - Do not hash
Date of Birth (db) - Hashing needed Click ID (fbc) - Do not hash
First name (fn) - Hashing needed Browser ID (fbp) - Do not hash
Last name (ln) - Hashing needed External ID (external_id) - Hashing recommended
City (ct) - Hashing needed Subscription ID (subscription_id) - Do not hash
State (st) - Hashing needed Lead ID (lead_id) - Do not hash
FB Login ID (fb_login_id) - Do not hash

When hashed PII is NOT available, add the following parameters

Additional parameters to add for improved event matching:

IP address (client_ip_address) - Do not hash

Click ID (fbc) - Do not hash
Browser ID (fbp) - Do not hash
External ID (external_id) - Hashing recommended

Limited Data Use:

The Limited Data Use feature gives businesses more control over how their data is used in our systems,
for example, to support businesses in complying with the California Consumer Privacy Act (CCPA).

Learn more about data processing options for users in California on Facebook for Developers.
Conversions API: 8
Direct Integration Playbook

Parameters used as
Deduplication Keys
Because we recommend using a pixel + Conversions
API connection for as many of your events as
possible, these redundant events require
deduplication by using a consistent event naming
convention and one of the following sets of
deduplication keys:

Option A (Recommended)

Duplicate Event name and Event ID

Deduplication method
Events received within 48 hours of one another
containing the same event_name, same
event_id and sent to the same pixel ID are
considered duplicates, and we discard the latter
of the two.

Deduplication Keys
event_name
event_id

Option B

Duplicate Event name and Facebook

Browser ID or External ID

Deduplication method
You must use event_name along with the fbp
and/or external_id consistently across
browser and server events. A browser event must
arrive first and if a server event is received before
the corresponding browser event, it may be
double counted. Because of these limitations, we
recommend Option A.

Deduplication Keys
event_name
fbp and/or external_id
event_time
Conversions API: 9
Direct Integration Playbook

5. Test events
Check that events are processed and deduplicated correctly using the Test Events 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

Your test events should show up in the Test Events tool within 30 seconds after you send a test event.

• If they don’t, make sure your payload is structured correctly using the Payload Helper tool
• Test information remains in the Test Events tool for 24 hours or until you clear it by clicking “Clear
Activity”

Note
Events sent with test_event_code are processed and used for targeting and ads measurement.
Conversions API: 10
Direct Integration Playbook

6. Verify events
After you start sending events, you should be able to verify them within 20 minutes.

• Go to Events Manager > Data Sources > click on the pixel corresponding to the PIXEL_ID in your
POST request
• For each pixel, go to Overview > Events > Connection Method
• Under “Connection Method,” you’ll see “Browser,” “Server” or “Browser + Server”

Best practice

We recommend using a “Browser + Server” connection method for as many of your events as possible.
Events with a browser-only connection are more susceptible to being missed or unattributed due to a
customer’s poor internet connection, page load errors and 3rd party cookie deprecation by web browsers.

Example: Illustration purposes only.

Conversions API: 11
Direct Integration Playbook

Best practice

Click on each event to see more details and recent activity, such as:

• Aggregated event parameters

• Percent of Events received, and from which connection method (Pixel or Conversions API)
• "Events processed or ignored from each connection method
• Event Match Quality score (out of 10), including how it’s calculated and used, and tips for increasing it (for
instance, by specifying additional customer information parameters to add to the event)

Example: Illustration purposes only.

Conversions API: 12
Direct Integration Playbook

7. Troubleshoot and Optimal Configuration

The Conversions 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

Best practice

Monitor your Conversions API connection by visiting the Diagnostics tab in Events Manager regularly. Hover
over the "!" icon to learn more about an issue and recommendations to improve it.

Common Conversions API diagnostic messages include:

Diagnostic message in
Context Proposed resolution
Events Manager

Missing <EVENT> user 1 or more events are missing

100% of events received
data parameters required user data parameters.
should include required
parameters (refer to
Note: even 1 problem
Event from server missing diagnostic to determine
event can cause a
<KEY> parameter which event is problematic)
diagnostic to appear

Server sending invalid match 1 or more events are missing

key parameters for events required user data parameters. Correct formatting of
parameters (refer to
Note: even 1 problem diagnostic to determine
Event sending invalid
event can cause a which event is problematic)
<KEY> parameter
diagnostic to appear
Conversions API: 13
Direct Integration Playbook

Your server is sending events

Send events as close to
Event delay from server more than 24 hours after the
real-time as possible.
actual event has occurred

Your pixel or server has

Same event ID received for Use unique Event IDs for
used the same Event ID
many event instances each event.
multiple times

Server External ID Not The External ID provided in Use consistent External

Matching to Pixel External the pixel does not match ID across browser &
ID for Event any sent via the Server server events.

Optimal configuration criteria

The portion of browser events that are shared with a “browser +

Event redundancy
server” connection method (ieally, at least 90%)

The portion of redundant events that are effectively identified with

Event deduplication identical event names and event IDs, external IDs or Facebook
Browser IDs (ideally, at least 50%)

How long ago your event occured (ideally, 0 minutes, i.e. real time,
Data freshness
and no longer than 7 days)

A score that indicates how effective your event’s customer

Event Match Quality (EMQ) information may be at matching it to a Facebook account (ideally 6.0
or higher)

Note

See below for additional details about using these criteria for achieving an optimal Conversions API configuration.
Conversions API: 14
Direct Integration Playbook

Optimal configuration
Follow the below recommendations to optimize your configuration, which may improve your ad performance.

Event Redundancy

For the most reliable data connection, we recommend using a “browser + server” connection
method for all events.

Check this by looking at Connection Method:

i. Go to Events Manager > Data Sources > Connection Method:

Example: Illustration purposes only.

Conversions API: 15
Direct Integration Playbook

Event Deduplication

As recommended, events are shared redundantly using a “browser + server connection,” and
therefore, our system must understand that these redundant events describe a single customer
action (event instance) by deduplicating them.

Check this by looking at Event Overview

1. Go to Events Manager > Data Sources > Your Pixel > View Details > Event Overview

Example: Illustration purposes only.

2. Use the Event Breakdown table to monitor your event volume:

i Events Received: The total number of events received from browser (i.e. Pixel) and server (i.e.

Conversions API). Some events may not be counted here due to errors
Events received using Conversions API should be at least equal if not higher than events
received using Browser Pixel
i Events Processed: The number of events received from browsers and servers excluding any

duplicates. These are the events used for measurement and optimization (Events Processed =
Events Received – Events Deduplicated)
i Events Deduplicated: The number of events received and identified as duplicates and therefore

not processed
Conversions API: 16
Direct Integration Playbook

To improve event deduplication, check your

event’s Deduplication Keys

1. Go to Events Manager > Data Sources >

Your Pixel > View Details > Event
Deduplication > Deduplication Keys

The lower portion of the Event Deduplication

window displays:

2. Deduplication Key % (per connection

method):
• In the example, 100% of browser events
from Pixel contain Event ID and 100% of
server events from Conversions API contain
Event ID
• The higher the percentage, the better
• We recommend sending Deduplication
Keys for all of your events (ideally 100%)

3. Overlap %:
• Overlap represents the percentage of
Deduplication Keys received using both
Pixel and Conversions API

4. In this screenshot, 93.79% of events from

Pixel and Conversions API contain identical
Event IDs.

5. For example, if you send 80 purchase

events from Pixel and 100 purchase events Example: Illustration purposes only.

from Conversions API, you would ideally have

100% overlap, or 80 Deduplication Keys: 1 for
each pair of redundant purchase events.
• 100% overlap = 80 unique Deduplication
Keys / 80 pairs of redundant events
• Having low overlap (e.g. for the above
example, if your overlap was 40% )
indicates you aren’t sharing as many
Deduplication Keys as you are sending pairs
of redundant events
40% overlap = 32 unique
Deduplication Keys / 80 pairs of
redundant events
Conversions API: 17
Direct Integration Playbook

Data Freshness

• The delay between the time each event

was shared with Facebook versus the time it
actually occurred is important for how
effectively our system learns and optimizes
delivery for your campaign.

• Check this by looking at Data Freshness.

1. Go to Events Manager > Data
Sources > Your Pixel > View Details >
Data Freshness

2. We recommend as close to Real Time

Example: Illustration purposes only.
as possible

Event Match Quality (EMQ) score

Event Match Quality is scored from 1 to 10,

indicating how effective your server event’s
customer information parameters may be at
matching it to a Facebook account.

Only matched events can be used for ads

attribution and ad delivery optimization, and
the higher the matching quality, the better.

Check this by looking at Event Match Quality

1. Go to Events Manager > Data Sources
> Your Pixel > View Details > Event
Matching
2. Look at each type of customer
Information received and the percentage
of events receiving it: the more types of
customer information received and
higher the percentage of events
Example: Illustration purposes only.
receiving each type, the better
 Conversions API: 18
Direct Integration Playbook

We recommend achieving an EMQ score of 6.0 or

higher by adding as many available customer
information parameters as possible to every server
event.

You’ll see recommendations along the right hand

side of this window for improving your EMQ score.
Typically, adding the following parameters can help
improve your event’s EMQ score:

1. Client user agent (client_user_agent)

2. IP address (client_ip_address)

For example, a business observed an increase in its

event’s EMQ score from 5.0 to 9.0 by simply
adding client user agent and IP address:*

Example of customer information parameters

received from an event with a 5.0 EMQ score:

Email address (em)

Phone number (ph)
First name (fn)
Last name (ln)

Adding client user agent and IP address

increased the event’s EMQ score to 9.0:

Email address (em)

Phone number (ph)
First name (fn)
Last name (ln)
Client user agent (client_user_agent)
IP address (client_ip_address)

*Source: Facebook data, 28k weekly ads campaign that were

optimized for the standard purchase events from Conversions API,
July 2020 - September 2020 (Accessed May 2021)
Conversions API: 19
Direct Integration Playbook

GLOSSARY / ADDITIONAL RESOURCES

Terms of Use
Facebook Business Tools Terms
https://www.facebook.com/legal/terms/businesstools

Adopting Conversions API

About Conversions API
https://www.facebook.com/business/help/AboutConversionsAPI

Decide if Conversions API Is Right for Your Business

https://www.facebook.com/business/help/ConsiderConversionsAPI

Compare Conversions API Setup Options

https://www.facebook.com/business/help/CompareConversionsAPISetups

About Partner Integrations for Web

https://www.facebook.com/business/help/WebPartnerIntegrations

Conversions API Case Studies

https://www.facebook.com/business/success/categories/conversions-api

Best Practices
Best Practices for Conversions API
https://developers.facebook.com/docs/marketing-api/conversions-api/best-practices

Best Practices for Privacy and Data Use for Facebook Business Tools
https://www.facebook.com/business/help/PrivacyBestPractices

Cookie Consent
https://developers.facebook.com/docs/app-events/cookies/
Conversions API: 20
Direct Integration Playbook

Using the Conversions API

Implement Conversions API Using Personalized Instructions in Events Manager
https://www.facebook.com/business/help/ImplementConversionsAPI

Navigate Events Manager for Facebook Pixel and Conversions API

https://www.facebook.com/business/help/EventsManagerforWeb

Using the API > Send requests

https://developers.facebook.com/docs/marketing-api/conversions-api/using-the-api#send

Using the test events tool

https://www.facebook.com/business/help/ServerTestEventsTool

Batch Requests
https://developers.facebook.com/docs/marketing-api/conversions-api/using-the-api#batch-requests

About Deduplication for Facebook Pixel and Conversions API Events

https://www.facebook.com/business/help/WebEventDeduplication

Event Deduplication Options

https://developers.facebook.com/docs/marketing-api/conversions-api/deduplicate-pixel-and-
server-events

Add Parameters for Deduplication

https://developers.facebook.com/docs/marketing-api/conversions-api/guides/end-to-end-implementation#add-
parameters-for-dedup

Deduplicate pixel and server events

https://developers.facebook.com/docs/marketing-api/conversions-api/deduplicate-pixel-and-
server-events#deduplication-best-practices

Recommended and Maximum Delay Times for Web and Offline Events
https://www.facebook.com/business/help/RecommendedDelayTimes

Upload Time versus Event Transaction Time

https://developers.facebook.com/docs/marketing-api/conversions-api/using-the-api#event-tra
nsaction-time

Parameters
https://developers.facebook.com/docs/marketing-api/conversions-api/parameters

Hashing
https://developers.facebook.com/docs/marketing-api/conversions-api/using-the-api#hashing

Connect Your Shopify Account to Facebook

https://www.facebook.com/business/help/ConnectShopify
Conversions API: 21
Direct Integration Playbook

Troubleshooting
Troubleshoot the Facebook Event Setup Tool for Web
https://www.facebook.com/business/help/TroubleshootEventSetupTool

Troubleshoot Facebook Pixel Error and Warning Messages

https://www.facebook.com/business/help/PixelErrors

Rate limiting
https://developers.facebook.com/docs/marketing-apis/rate-limiting

Error codes
https://developers.facebook.com/docs/marketing-api/error-reference

Throttling errors
https://developers.facebook.com/docs/marketing-apis/rate-limiting#throttlingerrors

Dropped events
https://developers.facebook.com/docs/marketing-api/conversions-api/using-the-api#dropped-events

Training
Webinar: How to Use the Conversions API: A Developer's Guide
https://www.facebook.com/business/m/sessionsforsuccess/conversions-api

Facebook Blueprint: Stronger Connections with Conversions API

https://www.facebookblueprint.com/student/path/219717-stronger-connections-with-th
e-conversions-api

Facebook Blueprint: Setup, Implement and Verify the Conversions API

https://www.facebookblueprint.com/student/path/219714-setup-implement-and-verif
y-the-conversions-api

Facebook Blueprint: Troubleshoot the Conversions API

https://www.facebookblueprint.com/student/path/219715-troubleshoot-the-conversions-api

Video Tutorial: Test Your First Conversions API Call

https://developers.facebook.com/docs/marketing-api/conversions-api/using-the-api#video

Support
Developer Support
https://developers.facebook.com/support/

Developer Community Forum

https://developers.facebook.com/community