Marketing API Version

Getting Started

Upload offline conversion events and see how many customers viewed or clicked on Facebook ads before converting.

For more general information about Facebook's offline conversions capabilities, see the Track Offline Conversions section of our Help Center.

To upload offline events directly through the Offline Conversions API, you will need the following:

1. Marketing API Setup

2. Create, Permission and Track Offline Event Set

3. Normalize, Hash, and Upload Event Data

4. Check Match Rate, Attribution, and Upload Stats

1. Marketing API Setup

The Offline Conversions API is part of the Facebook Marketing API. To access the Marketing APIs as a business, you will need the following:

1. Facebook App

To use any of the Marketing APIs, you must create and use a Facebook App. If you don't already have one, use the Create an Ads App button at the top of the Marketing API documentation.

If you are using Business Manager, you will then need to claim the app as a business.

2. Business Manager System User and Token

Business Manager helps businesses and agencies manage their Facebook Pages, ad accounts, offline event sets, etc. in one place. It's highly recommended business integrations use an access token associated with a Business Manager instead of a personal user access token.

For this purpose, Business Manager has System Users that represent systems or software making calls to the Marketing APIs. To generate a System User and System User Access Token:

Visit Business Manager | Business Settings
Select Users > System Users
Click Add New System User
Check the System Users documentation to help determine whether you would like to create a regular or Admin System User

An access token provides access to Facebook APIs. To create system user access tokens:

Visit Business Manager | Business Settings
Select Users > System Users
Select the system user
Click Generate New Token
Select your app
For scope select ads_management.

If you are not using an admin system user, you need to explicitly grant your system user access to the relevant ad account:

Go to Business Manager | Business Settings
Select Users > System Users
Select the system user
Click Assign Assets
Select your ad account

2. Create, Permission, and Track Offline Event Set

Create an Offline Event Set to upload offline events to. You need specific access to create offline event sets, assign to ad acocunts, and upload or view data for an event set. You must be:

A Business Manager admin, or
An Admin system user who created the offline event set, or
Am Admin on the ad_account connected to the offline event set.

See Offline Conversion Event Set, Reference.

1. Create Offline Event Set

Create Offline Event Sets through Business Manager, or through a POST request:

curl 
-F 'access_token=<SYSTEM_USER_ACCESS_TOKEN>' \
-F 'name=offline_event_set' \
-F 'description="conversion data used for superbowl campaign"'
https://graph.facebook.com/<API_VERSION>/<BUSINESS_MANAGER_ID>/offline_conversion_data_sets

The response includes the event set id:

{
  "id": <OFFLINE_EVENT_SET_ID>
}

Parameters:

Parameter Name	Type	Description	Example
`name`	`string`	Event set name.	`In store purchases`, `Lead registrations`
`description`	`string`	Event set description.	`In store purchases for superbowl campaign`

2. Set Ad Account permissions, and Conversion Tracking on Ads

To track which Facebook ads are associated with an offline conversion, the ads must have the appropriate Offline Event Set in their Tracking Spec. Unless this is properly configured, no ad attributions can be made.

You can set up auto-tracking per ad account in Business Manager, which will automatically set the tracking spec for any ad created in the ad account. Otherwise, you can set it per ad using the API via the following:

Assign tracking and read permissions to an ad account:

Graph API Explorer

POST /<OFFLINE_EVENT_SET_ID>/adaccounts HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/adaccounts

Parameters:

Parameter Name	Type	Description
`business`	`int`	Assign ad account to this business ID.
`account_id`	`int`	ID of ad account with offline tracking enabled.

Set ad tracking manually:

When you update a tracking_spec, we overwrite the previous one. Make sure to do a GET first, then append the associated String for the offline event set to the existing tracking_spec. For example, provide an appropriate tracking spec:

curl \
  -F 'tracking_spec=[{action.type:"offline_conversion", dataset:["123"]}]' \
  -F 'access_token=<SYSTEM_USER_ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/<AD_ID>

Update your ads's tracking spec:

Graph API Explorer

POST /<AD_ID>/?tracking_specs=[{"action.type":"offline_conversion","dataset": <OFFLINE_EVENT_SET_ID>}] HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<AD_ID>/?tracking_specs=[{"action.type":"offline_conversion","dataset": <OFFLINE_EVENT_SET_ID>}]

Parameters:

Parameter Name	Type	Description	Example
`action.type`	`string`	Track this action for the ad group.	`offline_conversion`
`dataset`	`int`	ID for offline event set.	`11111111111`

3. Normalize, Hash, and Upload Event Data

Backfilling and Attribution Window

You may backfill offline events up to 90 days in the past. However, since the maximum attribution window for Facebook is 28 days, backfilled data will only attribute properly up to 62 days in the past.

Normalization and Hashing

It's important to normalize the event data to ensure proper user matching and attribution. The normalization for Offline Events is the same as for Custom Audiences. See Hashing and Normalization for Multi-Key in the Custom Audiences documentation.
For hashing, only SHA256 is supported and the API does not accept unhashed data.

Batching Uploads

To ensure stable uploads, we currently recommend uploading up to 1000 transactions at a time.
upload_tag: To help with debugging potential upload issues, we recommend passing the upload_tag parameter per event upload call. Use the same upload_tag to batch together all the uploads for a session, and a different upload_tag per upload session.

Upload conversion data

Example Call:

curl \
  -F 'access_token=<SYSTEM_USER_ACCESS_TOKEN>' \
  -F 'upload_tag=store_data' \
  -F 'data=[ \
    { 
      match_keys: {"phone": ["<HASH>","<HASH>"], "email": ["<HASH>","<HASH>"]}, 
      currency: "USD", 
      value: 16,
      event_name: "Purchase",
      event_time: 1456870902,
      custom_data: {
        event_source: "in_store"
      },
    }, 
    { 
      match_keys: {"lead_id": "12345"}, 
      event_name: "Lead",
      event_time: 1446336000,
      custom_data: {
        event_source: "email",
        action_type: "<sent|open|click>",
        email_type: "<email_type_code>", 
        email_provider: "<gmail|yahoo|hotmail>",
      }
    }, 
  ]'
  https://graph.facebook.com/<API_VERSION>/<OFFLINE_CONVERSION_DATA_SET_ID>/events

Success response:

Name	Type	Description
`num_processed_entries`	integer	Number of processed entries

On error you see an exception returned with the invalid entries and the reasons. Fix the errors or skip the data rows with errors, and retry the API call.

Data Upload Endpoint and Formatting

Make an HTTP POST:

Graph API Explorer

POST /<OFFLINE_CONVERSION_DATA_SET_ID>/events HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_CONVERSION_DATA_SET_ID>/events

With the following parameters:

Parameter Name	Type	Required Field	Description	Example
`upload_tag`	`string`	`yes`	Track your event uploads.	`monthly, in-store uploads`
`data`	`json array`	`yes`	See data parameters below.	See example
`namespace_id`	`int`	`no`	Scope used to resolve `extern_id` or `tpid`. Can be another data set or data partner id.	12345

`data` Parameters:

Parameter Name	Type	Required Field	Description	Example
`match_keys`	`JSON string`	`yes`	Identifying information used to match transactions to Facebook Users. See match keys below.	`{"phone": ["{HASH}","{HASH}"], "email": ["{HASH}","{HASH}"], "fn": "{HASH}",}`.
`event_time`	`int`	`yes`	The UNIX timestamp of the conversion event.	`1456870055`
`event_name`	`string`	`yes`	Event type. Must be one of nine Standard Events in Facebook Pixel.	`"ViewContent"`, `"Search"`, `"AddToCart"`, `"AddToWishlist"`, `"InitiateCheckout"`, `"AddPaymentInfo"`, `"Purchase"`, `"Lead"`, `"CompleteRegistration"`, `"Other"`
`currency`	`string`	`yes`	Three-letter ISO currency for this conversion event. Required for `Purchase` events.	`"USD"`
`value`	`double`	`yes`	Value of conversion event. Required for `Purchase` event.	`16.00`
`content_type`	`string`	`no` Required for Dynamic Ads	Any valid Dynamic Ad `content-type`.	`"product"`
`content_ids`	`string[]`	`no` Required for Dynamic Ads	List of product identifiers.	`["1234","4567"]`
`custom_data`	`JSON dictionary`	`no`	Information about this conversion event.	`{category: 'ICECREAM', location: 'Jasper's'}`

Match Keys

match_keys are a set of identifiers to match people to Facebook Users for attribution. See Hashing and Normalization for Multi-Key for normalizing and hashing your match data. Only SHA256 hashing is supported, and the API does not accept unhashed data.

Key type, Single and Multi	Key name	Hashing required
Email Address(es)	`email`	YES
Phone Number(s)	`phone`	YES
Gender	`gen`	YES
Date of Birth. YYYY format	`doby`	YES
Date of Birth. MM format	`dobm`	YES
Date of Birth. DD format	`dobd`	YES
Last Name	`ln`	YES
First Name	`fn`	YES
First Name Initial	`fi`	YES
City	`ct`	YES
US States	`st`	YES
Zip codes	`zip`	YES
Country	`country`	YES
Apple Advertising Identifier	`madid`	YES
Android Advertising ID	`madid`	YES
Third-party user id	`extern_id`	Do NOT hash
The lead id from Lead Ads	`lead_id`	Do NOT hash

4. Check Match Rates, Attributions, and Upload Stats

The easiest way to check match rates and attributions as you develop and test your integration is through the 'Offline' section of the Events Manager, in your Business Manager.

For initial upload and user match testing, we recommend creating a test Event Set that is not tracked by any ads. Once ad attributions are made, they can not be removed.

Upload Stats Endpoint

A Business Manager Admin, or System User who created the offline event set, can retrieve upload stats. Any admin on the ad_account which is connected to the offline event set can also read this data.

To view stats about offline event sets such as valid entries and matched entries:

Graph API Explorer

GET /<OFFLINE_EVENT_SET_ID>/uploads HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/uploads

View daily breakdowns of offline events in Events Manager. For more precise breakdowns, make this call:

Graph API Explorer

GET /<OFFLINE_EVENT_SET_ID>/stats HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/stats

Parameters:

Parameter Name	Type	Required Field	Description	Example
`start`	`int`	`no`	The unix timestamp. Query events starting at this time.	`1456870055`
`end`	`int`	`no`	The unix timestamp. Exclude events occuring this time onward.	`1456870056`

Getting Started

1. Marketing API Setup

2. Create, Permission and Track Offline Event Set

3. Normalize, Hash, and Upload Event Data

4. Check Match Rate, Attribution, and Upload Stats

1. Marketing API Setup

1. Facebook App

2. Business Manager System User and Token

2. Create, Permission, and Track Offline Event Set

1. Create Offline Event Set

2. Set Ad Account permissions, and Conversion Tracking on Ads

3. Normalize, Hash, and Upload Event Data

Backfilling and Attribution Window

Normalization and Hashing

Batching Uploads

Upload conversion data

Data Upload Endpoint and Formatting

data Parameters:

Match Keys

4. Check Match Rates, Attributions, and Upload Stats

Upload Stats Endpoint

`data` Parameters: