Marketing API Version

Offline Conversions API

With Facebook's Offline Conversions API you can send your offline conversion events using an offline event API. You can see how many of your customers viewed or clicked on Facebook ads before converting offline.

Requirements

To use this API, you must have:

1. Facebook Business Manager

If you don't have a Facebook business manager, you need to create one.

2. Facebook App

Access to Marketing API requires a Facebook App ID. To create an app:

  • Go to business manager Business Settings,
  • Select Apps option,
  • Click on Add New App button and follow the instructions.

3. Business Manager System User & Token

With system user access, your app can send data to Facebook via API. To create it: - Go to business manager Business Settings - Select System Users - Click Add New System User - Select Admin System User as the role for the system user.

An access token holds the authentication information to permit access to data. To create system user access token:

  • Go to business manager Business Settings
  • Select System Users
  • Select the system user
  • Click Generate New Token
  • Select your app
  • For scope select ads_management.

4. Ad Account

Define your campaign, budget and bid. You need an ad account to run ad campaigns on Facebook. To create one, see Marketing API or Advertiser Help Center, Set up People, Pages & Ad Accounts in Business Manager

5. Grant System User Access to Ad Account

You will need to grant your system user access to your ad account.

  • Go to your business manager Business Settings
  • Select System Users
  • Select the system user
  • Click Assign Assets
  • Select the right ad account

6. Offline Event Set

An uploaded set of files with offline conversion data. When you create an ad, set the tracking spec to point to the offline event set ID, so we correctly attribute events. You can create the event set, view stats on your imports, delete, and modify this data in business manager.

Note with the older implementation, offline event set CRUD operations can be done at the business manager level to share event sets with other objects and entities.

Event Upload API Flow

  1. Create Offline Event Set
  2. Assign Ad Account Permissions
  3. Ad Tracking
  4. Upload Offline Events

1. Create Offline Event Set

To create offline event set, make an authenticated HTTP POST call to:

POST /v2.8/<BUSINESS_MANAGER_ID>/offline_conversion_data_sets HTTP/1.1
Host: graph.facebook.com
curl -X POST \
     -d "" \
        https://graph.facebook.com/v2.8/<BUSINESS_MANAGER_ID>/offline_conversion_data_sets

Response with ID to use later:

{
  "id": <OFFLINE_EVENT_SET_ID>
}

Parameters:

Parameter NameTypeDescriptionExample

name

string

The name of the offline event set

In store purchases, Lead registrations

description

string

The description of the offline event set

In store purchases for superbowl campaign

Only admin users, including admin system users, can create offline event set and inherently will have upload and view permissions on the offline event set. To learn more, see this Offline Conversion Event Set, Reference.

2. Assign Ad Account Permissions

Only business manager admins or admin system users who created the offline event set can make this API call. Also any admin on the ad_account connected to the offline event set can also make this call.

Assign offline event tracking and viewing permissions to an ad account:

POST /v2.8/<OFFLINE_EVENT_SET_ID>/adaccounts HTTP/1.1
Host: graph.facebook.com
curl -X POST \
     -d "" \
        https://graph.facebook.com/v2.8/<OFFLINE_EVENT_SET_ID>/adaccounts

Parameters:

Parameter NameTypeDescription

business

`int``

ID of the business the ad account should belong to

account_id

int

ID of the ad account where offline tracking is enabled

3. Ad Tracking

Note when you update the tracking spec, it is an overwrite not update. So when you update ad tracking, make sure to do GET first, then add the associated String for the offline event set to the existing tracking spec.

To create an ad see Ads Management or use Ads Manager. Then update your ads's tracking spec with this call:

POST /v2.8/<AD_ID>/?tracking_specs=[{"action.type":"offline_conversion","dataset": <OFFLINE_EVENT_SET_ID>}] HTTP/1.1
Host: graph.facebook.com
curl -X POST \
     -d "" \
        https://graph.facebook.com/v2.8/<AD_ID>/?tracking_specs=[{"action.type":"offline_conversion","dataset": <OFFLINE_EVENT_SET_ID>}]

Parameters:

Parameter NameTypeDescriptionExample

action.type

string

The action being tracked for the ad group

offline_conversion

dataset

`int``

The id of the offline event set to receive offline transactions

11111111111

4. Upload Offline Events

To send conversions, make an authenticated HTTP POST call to:

POST /v2.8/<OFFLINE_CONVERSION_DATA_SET_ID>/events HTTP/1.1
Host: graph.facebook.com
curl -X POST \
     -d "" \
        https://graph.facebook.com/v2.8/<OFFLINE_CONVERSION_DATA_SET_ID>/events

Advertisers should upload transaction within 62 days of the conversion.

The parameters needed for the offline event set events end point:

Parameter NameTypeRequired FieldDescriptionExample

upload_tag

string

yes

Upload tag for this event

monthly in store uploads

data

json array

yes

N number of events being uploaded

see example

namespace_id

`int``

no

Scope used to resolve extern_id (tpid), can be another data set or data partner id

12345

data is a JSON array, where you can upload a conversion event per person. You can upload 2,000 events per API call.

upload_tag is a way to track your event uploads. Use the same tag name for all event upload API calls in the same batch as a way to tie them together. This can also help with debugging event uploads, and is a recommended practice for any event upload sessions using more than one API call.

Data Parameters:

Parameter NameTypeRequired FieldDescriptionExample

match_keys

json string

yes

The identifier info used to match people

{"phone": ["<HASH>","<HASH>"], "email": ["<HASH>","<HASH>"], "fn": "<HASH>",}

event_time

`int``

yes

The unix timestamp of the conversion event, seconds since Jan 1, 1970 UTC

1456870055

event_name

string

yes

The type of the event needs to be one of the 9 Standard Events supported by the Facebook Pixel

"ViewContent", "Search", "AddToCart", "AddToWishlist", "InitiateCheckout", "AddPaymentInfo", "Purchase", "Lead", "CompleteRegistration", "Other"

currency

string

yes

3 letter ISO currency used for this conversion event, required for Purchase event.

"USD"

value

double

yes

The value of this conversion event, required for Purchase event

16.00

content_type

string

no but required for Dynamic Product Ads

product or product_group

"product"

content_ids

string array

no but required for Dynamic Product Ads

List of identifiers of products

["1234","4567"]

custom_data

json dictionary

no

Any other information about this conversion event, etc

{category: 'ICECREAM', location: 'Jasper's'}

The match_keys parameter represents the set of identifiers to match people for attribution.

See Custom Audiences from CRM Data for the normalized and hashed format. Only SHA256 is supported. Please note that Facebook does not accept unhashed data.

Key type (single and multi)Key nameHashing required

Email Address(es)

email

YES

Phone Number(s)

phone

YES

Gender

gen

YES

Date of Birth using YYYY format

doby

YES

Date of Birth using MM format

dobm

YES

Date of Birth using 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

The API returns the following:

NameTypeDescription

num_processed_entries

integer

Number of entries that were processed

On errors it throws an exception with error message with invalid entries and reason. Fix the errors or skip the data rows with errors and retry the API call.

View Offline Event Set Upload Stats

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

GET /v2.8/<OFFLINE_EVENT_SET_ID>/uploads HTTP/1.1
Host: graph.facebook.com
curl https://graph.facebook.com/v2.8/<OFFLINE_EVENT_SET_ID>/uploads

A business manager admin or system user who created the offline event set can retrieve upload stats. Also any admin on the ad_account which is connected to the offline event set can read this data.

View Offline Event Stats

View a daily breakdown of offline events in the Offline Events Manager in Business Manager. For more precise breakdowns, make this call:

GET /v2.8/<OFFLINE_EVENT_SET_ID>/stats HTTP/1.1
Host: graph.facebook.com
curl https://graph.facebook.com/v2.8/<OFFLINE_EVENT_SET_ID>/stats

Parameters:

Parameter NameTypeRequired FieldDescriptionExample

start

`int``

no

The unix timestamp for when to start querying data from, seconds since Jan 1, 1970 UTC

1456870055

end

`int``

no

The unix timestamp for when to stop querying data from, seconds since Jan 1, 1970 UTC

1456870056

Create Offline Custom Conversions

For more detailed documentation on creating custom conversions in general and reading them from the API, see the Custom Conversion API documentation.

Please note that Offline Custom Conversions currently do NOT backfill. Event uploads prior to creating the custom conversion will not be attributed. Offline Custom Conversions also cannot be used for optimization.

To create a custom conversion using your offline events, POST the following:

POST /v2.8/act_<ACCOUNT_ID>/customconversions HTTP/1.1
Host: graph.facebook.com
curl -X POST \
     -d "" \
        https://graph.facebook.com/v2.8/act_<ACCOUNT_ID>/customconversions

Parameters:

Parameter NameTypeDescriptionExample

name

string

Name for new custom conversion

Offline purchases over 100 dollars

event_source_id

int

The id of the offline event set you want to track

11111111111

custom_event_type

string

One of the 9 Standard Events supported by the Facebook Pixel

"ViewContent", "Search", "AddToCart", "AddToWishlist", "InitiateCheckout", "AddPaymentInfo", "Purchase", "Lead", "CompleteRegistration", "Other"

rule

JSON encoded string

The operators and data that make up your conversion rule e.g. purchases over $100

{"and":[{"event":{"eq": "Purchase"}},{"value":{"gt":100}}]}

A successful query will return the ID of your new custom conversion:

{
  "id": <CUSTOM_CONVERSION_ID>
}

Custom Data

Offline Custom Conversions also support the custom_data field for rule creation, similar to Offline Custom Audiences.

For example, you can attach a product category to conversions you upload using the custom_data field:

data=[
  {
    match_keys: {"phone": ["<HASH>","<HASH>"], "email": ["<HASH>","<HASH>"]}, 
    currency: "USD", 
    value: 16,
    event_name: "Purchase",
    event_time: 1456870902,
    custom_data: {
        product_category: "ICECREAM",
    },
  },
]

Then access custom_data.<YOUR_CUSTOM_PARAM> to create a Custom Conversion rule:

curl \
  -F 'name=Ice Cream Purchasers' \
    -F 'custom_event_type=Purchase' \
    -F 'event_source_id=<OFFLINE_EVENT_SET_ID>' \
    -F 'rule={"and": [{"event":{"eq":"Purchase"}},{"custom_data.product_category":{"i_contains":"ICECREAM"}}]}' \
    -F 'access_token=<ACCESS_TOKEN>' \

"https://graph.facebook.com/<API_VERSION>/act_<ACCOUNT_ID>/customconversions"

Note that the maximum number of custom conversions you can have per ad account is 40.

Partner API Flow

To attribute offline conversion events to your client's ad, you need to following these steps for the UI or API. The API calls for most of these steps are same as when an advertiser manages its own offline event set and campaign management.

  • Partner - Create offline event set
  • Partner - Share event set with client's business manager
  • Client - Assign ad account offline tracking permission
  • Client - Set offline tracking on ads
  • Partner - Upload offline events, view stats
  • Partner - Display ad insights for client

The steps vary depending on how your partner or agency permissions are set up with client ad accounts:

  • You may own all the ad account, event set or any other asset of your client.
  • You may have permission to your client's assets to perform certain actions.

To setup these permissions, see Business Manager Assets.

Partner - Share event set with client's business manager

Share an offline event set your client. Your client will then will be able to use the event set for their ads tracking.

GET /v2.8/<OFFLINE_EVENT_SET_ID>/agencies HTTP/1.1
Host: graph.facebook.com
curl https://graph.facebook.com/v2.8/<OFFLINE_EVENT_SET_ID>/agencies

Parameters:

Parameter NameTypeDescription

business

int

ID of your client business manager

Client - Assign ad account offline tracking permission

Only BM admin or admin system user who created the offline event set will be able enable tracking for all the ads under and ad account. Also any admin on the ad_account which is connected to the offline event set will be able to do this.

To make this API call, the business in the call has to have access to the offline event set. So you need to make the call to share the offline event set created by the partner to the client.

You can assign offline event tracking and viewing permissions to an adaccount by making following API call:

POST /v2.8/<OFFLINE_EVENT_SET_ID>/adaccounts HTTP/1.1
Host: graph.facebook.com
curl -X POST \
     -d "" \
        https://graph.facebook.com/v2.8/<OFFLINE_EVENT_SET_ID>/adaccounts

Parameters:

Parameter NameTypeDescription

business

int

ID of the business the ad account should belong to

account_id

int

ID of the ad account where offline tracking is enabled

Extern ID

This document explains when to use extern_id.

If you are data partner who already went through a match process, you can use your partner id as the namespace id and extern_id as your tpid.

Only match_keys is specified

match_keys are used to match to a facebook user and the matched data is sent along for further processing, unmatched data is not processed. The namespace_id parameter cannot be specified.

Both match_keys and extern_id are specified

match_keys are used to match to a facebook user and the forward mapping from {dataset_id, extern_id} to {facebook_user_id} is stored for future. The matched data is sent along for further processing, unmatched data is not processed.

The namespace_id parameter cannot be specified.

Only extern_id is specified

In this case the {dataset_id, extern_id} combination is used to retrieve a {facebook_user_id}. This works if some data was sent previously using both match_keys and extern_id. If no match is found, the unmatched data is not processed.

namespace_id parameter is specified for the API call

This is a similar to the previous case, and only extern_id can be specified per row of data.

namespace_id parameter applies to the entire API call. It can be used to refer to another offline event set must be accessible or owned by the business or a partner profile id. In this case the {namespace_id, extern_id} combination is used to retrieve a {facebook_user_id}. This again only works if the forward mapping was stored previously.

Insights and Attribution

You can see the attribution of offline events back to the ad seen or clicked by using the insights API. Here is how the API will work.

GET /v2.8/act_<ADACCOUNT_ID>/insights HTTP/1.1
Host: graph.facebook.com
curl https://graph.facebook.com/v2.8/act_<ADACCOUNT_ID>/insights

Parameters:

Parameter NameTypeDescriptionExample

action_breakdowns

string array

The break down of impression/click/conversion data based on the type of action (offline, online, etc)

["action_type", "placement", "age", "gender", "country", "region"]

fields

string array

The basic ad metrics

["impressions", "clicks", "actions",]

level

string

At what hierarchy the reporting results should be aggregated and deduped

ad or adset or campaign

date_preset

string

The relative date presets used for pulling the metrics

last_n_days (n = 7,14,28) or yesterday or today or last_month or lifetime

Note that offline conversion can be attributed after more than 1 day. This means you need to set your attribution window to 28d_view, or action_attribution_windows=['28d_view']', otherwise you will not see any conversions in reports.

See Insights API and Insights Guide.

The result will look something like this:

{
  "data": [
    {
      "date_start": "2015-12-01",
      "date_stop": "2015-12-01",
      "actions": [
        {
          "action_type": "offline_conversion.purchase",
          "value": 1
        },
        {
          "action_type": "offsite_conversion.lead",
          "value": 3
        },
      ],
      ...
    }
    ]
}

Examples

Create offline event set:

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

Create an ad with 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>

Upload the offline conversion data:

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><OFFLINE_CONVERSION_DATA_SET_ID><OFFLINE_CONVERSION_DATA_SET_ID>/events

View attribution in reporting:

curl -G \
  -d 'access_token=<SYSTEM_USER_ACCESS_TOKEN>' \
  -d 'fields=unique_actions,action_values' \
  https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/insights

The result will look like this:

{
  "data": [
    {
      "unique_actions": [
        {
          "action_type": "link_click",
          "value": 94
        },
        {
          "action_type": "offline_conversion",
          "value": 1
        },
        {
          "action_type": "offline_conversion.purchase",
          "value": 1
        },
        {
          "action_type": "page_engagement",
          "value": 95
        },
        {
          "action_type": "post_engagement",
          "value": 95
        },
        {
          "action_type": "post_like",
          "value": 1
        }
      ],
      "action_values": [
        {
          "action_type": "offline_conversion.purchase",
          "value": 27.5
        },
        {
          "action_type": "offline_conversion",
          "value": 27.5
        }
      ],
      "date_start": "2016-06-06",
      "date_stop": "2016-06-07"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MAZDZD"
    }
  }
}