This document refers to an outdated version of Marketing API. Please use the latest version.
Marketing API Version

Offline Conversions

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

Setup

To use this API, you need:

1. Facebook Business Manager

If you don't have one, create one.

2. Facebook App ID

For access to Marketing API. To create an app:

  • Visit Business Manager | Business Settings,
  • Select Apps option,
  • Click on Add New App and follow the instructions.

3. Business Manager System User and Token

With system user access, your app can send data to Facebook via API. To create it:

  • Visit 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 provides access to Facebook data. To create system user access tokens:

  • Visit 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

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

Grant your system user access to your ad account.

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

6. Offline Event Set

These are uploaded files with offline conversion data. When you create an ad, set tracking_spec to the offline event set ID to correctly attribute events. You can then create event sets, view stats on your imports, delete, and modify this data in Business Manager.

Note with older implementations, you could do offline event set CRUD operations at the Business Manager level to share event sets with other objects and entities.

Upload Event Data

You need specific access to create offline event sets, upload or view data for an event set. You also need this access if you want to assign these permissions to an ad account. You must be:

  • Business Manager admin, or
  • Admin system user who created the offline event set, or
  • 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 set, for example:

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

Make a HTTP POST:

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

The response includes an event set id:

{
  "id": <OFFLINE_EVENT_SET_ID>
}

Parameters:

Parameter NameTypeDescriptionExample

name

string

Event set name.

In store purchases, Lead registrations

description

string

Event set description.

In store purchases for superbowl campaign

2. Assign Ad Account Permissions

To assign tracking and read permissions to an ad account:

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

Parameters:

Parameter NameTypeDescription

business

int

Assign ad account to this business ID.

account_id

int

ID of ad account with offline tracking enabled.

3. Set Ad Tracking

When you update tracking_spec, we overwrite it. Make sure to do GET first, then append the associated String for the offline event set to the existing tracking_spec. See Ads Management or use Ads Manager. 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>

To update your ads's tracking spec:

POST /v2.9/<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.9/<AD_ID>/?tracking_specs=[{"action.type":"offline_conversion","dataset": <OFFLINE_EVENT_SET_ID>}]

Parameters:

Parameter NameTypeDescriptionExample

action.type

string

Track this action for the ad group.

offline_conversion

dataset

int

ID for offline event set.

11111111111

4. Upload Offline Events

You should upload transaction within 62 days of the conversion. Upload the 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>/events

To send conversions, make a HTTP POST:

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

Parameters include:

Parameter NameTypeRequired FieldDescriptionExample

upload_tag

string

yes

Track your event uploads.

monthly, in-store uploads

data

json array

yes

Includes number of events being uploaded. Upload a conversion event per person up to 2,000 events per API call.

see example

namespace_id

int

no

Scope used to resolve extern_id or tpid. Can be another data set or data partner id.

12345

Use the same upload_tag for all event upload API calls in the same batch to group them. This helps you debug event uploads, and you should use this for any event uploads made in 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.

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 is a set of identifiers to match people for attribution. See Custom Audiences from CRM Data for normalizing and hashing your data. Only SHA256 is supported and we do not accept unhashed data.

Key type, Single and MultiKey nameHashing 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

The response:

NameTypeDescription

num_processed_entries

integer

Number of processed entries

On errors you see an exception including invalid entries and the reason. Fix the errors or skip the data rows with errors and retry the API call.

View Upload Stats

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.

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

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

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

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

Parameters:

Parameter NameTypeRequired FieldDescriptionExample

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

Create Offline Custom Conversions

Offline Custom Conversions currently do not backfill. We do not attribute data from event uploads made before you created the custom conversion. You cannot use offline custom conversion data for ads delivery optimization. See Custom Conversion, Reference.

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

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

Parameters:

Parameter NameTypeDescriptionExample

name

string

New custom conversion name.

Offline purchases over 100 dollars

event_source_id

int

Offline event set ID to track.

11111111111

custom_event_type

string

One of nine Facebook Pixel standard events.

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

rule

JSON-encoded string

Operators and data for your conversion rule. See Custom Conversion, Reference. Example: purchases over $100.

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

The response, on success:

{
  "id": <CUSTOM_CONVERSION_ID>
}

Measure with Custom Data

You can use the custom_data field to create rules that later determine if a conversion counts or not. This is similar to Offline Custom Audiences. The maximum number of custom conversions you can have per ad account is 40.

For example, include product category in uploads with custom_data:

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 use 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"

Offline Conversions for Partners

To attribute offline conversion events to your client's ad, follow these steps. The API calls for most of these steps are same as when someone manages their own offline event set and campaign management.

  1. Partner - Create offline event set
  2. Partner - Share event set with client's Business Manager
  3. Client - Assign ad account offline tracking permission
  4. Client - Set offline tracking on ads
  5. Partner - Upload offline events, view stats
  6. Partner - Display ad insights for client

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

  • You may own all ad accounts, event sets or any other assets 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

Share the event set your client's Business Manager. Your client can then use the event set for ads tracking.

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

Parameters:

Parameter NameTypeDescription

business

int

ID of your client business manager

Client - Assign Ad Account Offline Tracking Permission

Share offline event sets created by a partner with their client. You need to be the Business Manager admin or admin system user who created the offline event set to enable tracking for ads under and ad account. If you are an admin on the ad account connected to the offline event set, you can also can do this. To make this API call, the business in the call has to have access to the offline event set.

You can assign offline event tracking and viewing permissions to an ad account with this call:

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

Parameters:

Parameter NameTypeDescription

business

int

Assign ad account to this business ID

account_id

int

Ad account ID with offline tracking enabled

Providing External IDs

There may be scenarios where you provide your own external ID to represent a customer and match them to someone on Facebook. To do this, use extern_id following these guidelines.

Data partners who went through the match process can use partner id as the namespace id and extern_id as your tpid.

Provide only match_keys

We use match_keys to find someone on Facebook and send on matched data for further processing. We do not process or store unmatched data. You cannot also provide a namespace_id parameter.

Provide both match_keys and extern_id

We use match_keys to find people on Facebook and forward mappings from {dataset_id, extern_id} to {facebook_user_id}. We send matched data onward for further processing; and delete unmatched data.

You cannot also provide namespace_id.

Provide only extern_id

If you already sent data with match_keys and extern_id, Facebook uses {dataset_id, extern_id} to retrieve a {facebook_user_id}. If no match is found, the unmatched data is not processed.

Provide namespace_id

namespace_id parameter applies to the entire API call. You can use it to refer to another offline event set that is accessible or owned by a business or a partner profile ID. If you already sent data with match_keys and extern_id, Facebook uses {namespace_id, extern_id} to retrieve a {facebook_user_id}. You should only provide one extern_id per row of data.

Insights and Attribution

See offline events attributed to an ad someone viewed or clicked. We attribute offline conversions 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.

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

Parameters:

Parameter NameTypeDescriptionExample

action_breakdowns

string[]

Break down of impression, click, or conversion data. Grouped by type of action: offline, online, and so on

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

fields

string[]

The basic ad metrics.

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

level

string

Aggregate or de-duplicate data at this level of reporting results

ad or adset or campaign

date_preset

string

Relative timeframes to query metrics

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

Results look 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
        },
      ],
      ...
    }
  ]
}

For example, to view attribution:

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 looks like this:

{
  "data": [
    {
      "unique_actions": [
        {
          "action_type": "link_click",
          "value": 94
        },
        {
          "action_type": "offline_conversion",
          "value": 1
        },
        {
          "action_type": "offline_conversion.purchase",
          "value": 1
        },
        {
....
          "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"
    }
  }
}