Attribution API

Provides measurement metrics to external API callers through its reporting API. External callers can create, schedule, and download reports using this API. You can query relevant IDs to create reports at additional API endpoints.

This API is available on a limited basis to white-listed partners and advertisers. Contact your Facebook representative if you want to use this API.

Set-Up

Setting up and using this API mainly self-serve. There are six required steps below. The first five steps you can do on your own. The final sixth step requires a Facebook representative to approve and grant API access.

Step 1: Create an App

If you do not have an App in Business Manager, you need to create one and submit it for approval.

Step 2: API Basic Access

The app needs to be approved for Marketing API Basic Access. See:

Step 3: Grant App business_management permission

A Business Manager admin needs to explicitly login the app to grant business_management permission. Create manual login URI for the app ID and permission. See Build a Login Flow. You can also do this in Business Manager.

The Business Manager that grants business_management permission to the app is the one where the app is added as an asset. You can only add an app to one Business Manager.

Step 4: Add yourself to Line of Business in Business Manager

To send Marketing API requests, you must have access to the Line of Business (LoB). You can add yourself to the LoB in Business Manager Settings. See Business Manager Settings.

Step 5: Generate access token

You must generate an access token with the external app ID. Long-live access tokens are available for use for up to 60 days after initial generation. See Access Token, Expiration and User Access Tokens

API Access

APIs should be connected to your Line of Business (LoB). This allows all of the following objects to be queried from the LoB as a starting point. You can find the LoB ID in Business Manager Settings, or in the URL to LoB. We support Graph API version v2.8 and above.

To read a LoB:

curl -G \
  -d 'access_token=...' \
  "https://graph.facebook.com/<VERSION_ID>/<LOB_ID>"

Read-only fields are

id - ID of the LoB.
name - Name of the LoB.

Listing Reports

To list reports under a LoB:

curl -G \
  -d 'access_token=...' \
  'https://graph.facebook.com/<VERSION_ID>/<LOB_ID>/reports'

To read a single report by ID:

curl -G \
  -d 'access_token=...' \
  'https://graph.facebook.com/<VERSION_ID>/<REPORT_ID>'

To create new Reach effectiveness report:

curl \
  -F 'access_token=...' \
  -F 'reports=
  [{
    "name": "Sample reach effectiveness report",
    "description": "Sample reach effectiveness report",
    "file_format": "json",
    "is_email_enabled": true,
    "email_addresses": ["test@tfbnw.net"],
    "email_suffix": "sample report",
    "email_report_attachment": "attached",
    "definition": {
      "report_type": "reach_effectiveness",
      "column_definitions": [
        {
          "key": "campaign_name",
          "name": "Campaign Name"
        }
      ],
      "date_range": {
        "type": "relative",
        "date_unit": "month",
        "quantity": "1",
        "time_zone": "America/Los_Angeles"
      },
      "filters": {
        "campaign_ids": [
          "<CAMPAIGN_ID>"
        ]
      }
    }
  }]' \
  'https://graph.facebook.com/<VERSION_ID>/<LOB_ID>/reports'

To create a new Conversion Attribution report:

curl \
  -F 'access_token=...' \
  -F 'reports=
  [{
    "name": "Sample MTA report",
    "description": "Sample MTA report",
    "file_format": "json",
    "is_email_enabled": true,
    "email_addresses": ["test@tfbnw.net"],
    "email_suffix": "sample report",
    "email_report_attachment": "attached",
    "definition": {
      "report_type": "mta",
      "column_definitions": [
        {
          "aggregation_usage": "dimension",
          "area": "serving",
          "category": "standard",
          "key": "device_type",
          "name": "Ad Device Type"
        },
        {
          "additional_params": {},
          "aggregation_usage": "metric",
          "area": "serving",
          "attribution_model": "last_touch",
          "category": "standard",
          "key": "net_media_cost",
          "name": "Net Media Cost"
        },
        {
          "additional_params": {
            "attribution_time_exponential_decay_param_half_life": "7",
            "selected_metrics": "conversions,mta_revenue,conversions_per_1000,cost_per_conversion"
          },
          "aggregation_usage": "metric",
          "attribution_model": "time_exponential_decay",
          "category": "attribution",
          "key": "time_decay_1",
          "name": ""
        }
      ],
      "date_range": {
        "type": "relative",
        "date_unit": "month",
        "quantity": "1",
        "time_zone": "America/Los_Angeles"
      },
      "filters": {
        "campaign_ids": [
          "<CAMPAIGN_ID>"
        ],
        "fb_conversion_event_filters": [
          {
            "fb_conversion_event_id": "<CONVERSION_EVENT_ID>"
          }
        ],
      }
    }
  }]' \
  'https://graph.facebook.com/<VERSION_ID>/<LOB_ID>/reports'

To update an existing report:

curl \
  -F 'access_token=...' \
  -F 'reports=
  [{
    "id": "<REPORT_ID>",
    "name": "Sample reach effectiveness report",
    "description": "Sample reach effective report",
    "file_format": "json",
    "is_email_enabled": true,
    "email_addresses": ["test@tfbnw.net"],
    "email_suffix": "sample report",
    "email_report_attachment": "attached",
    "definition": {
      "report_type": "reach_effectiveness",
      "column_definitions": [
        {
          "key": "campaign_name",
          "name": "Campaign Name"
        }
      ],
      "date_range": {
        "type": "relative",
        "date_unit": "month",
        "quantity": "1",
        "time_zone": "America/Los_Angeles"
      },
      "filters": {
        "campaign_ids": [
          "<CAMPAIGN_ID>"
        ]
      }
    }
  }]' \
  'https://graph.facebook.com/<VERSION_ID>/<LOB_ID>/reports'

API requests to update and create are similar. You only need an existing id field to get results. Fields in a report include:

id - ID of a report. Omitted in creation.
name - Name of a report.
description - Description of a report. Optional.
file_format - File format of the report that will be available for download. Supported file formats are: json and xlsx.
is_email_enabled - Whether email should be sent when scheduled report run completes. Optional.
email_addresses- List of email addresses that will receive a scheduled report run completion email. Optional.
email_suffix - Text appended to scheduled report run completion email. Optional.
email_report_attachment - attached or not_attached. When attached, the scheduled report run file will be attached to the email. A download link is included in the completion email in either case. The default is not_attached. Optional.
definition - Report definition. This is a JSON structure that has a number of fields inside.
- report_type - Type of the report. Two types are supported: mta and reach_effectiveness.
- column_definitions - Columns to be shown in report results. Fields should be copied from report_columns edge, described below. However an attribution report column could have additional_params.
  - category - Copied from report_columns edge.
  - key - Copied from report_columns edge.
  - aggregation_usage - Copied from report_columns edge.
  - attribution_model - Copied from report_columns edge.
  - additional_params - Additional column parameters. Applicable to only attribution report columns. It should be left unset or empty otherwise.
    - identity_matching_type - STRONGEST or COOKIE.
    - selected_metrics - List of metrics to be included in report. Copy column keys from report_columns edge.
    - attribution_position_based_param_first_touch_percentage - Percent given to first touch point credit. Applicable only to positional_based attribution_model.
    - attribution_position_based_param_last_touch_percentage - Percent given to last touch point credit. Applicable only to positional_based attribution_model.
    - attribution_time_exponential_decay_param_half_life - Number of days for half life decay. Applicable only to time_exponential_decay attribution_model.
- date_range - Date range of the report.
  - type - One of absolute, relative, or lifetime
  - date_unit - Applicable only to relative date range. One of day, week, month, quarter, year
  - quantity - Applicable only to relative date range. A numerical value relevant to the date_unit. If date_unit is week and quantity is 2, it means the last 2 completed weeks, ending at the nearest end of week.
  - time_zone - Time zone of the time range as a TZ time zone string.
  - begin_date - Applicable only to absolute date range. Begin date of the report in ISO 8601.
  - end_date - Applicable only to absolute date range. End date of the report in ISO 8601 format (https://en.wikipedia.org/wiki/ISO_8601).
- filters - Report filters. A dictionary of lists of IDs to be included in the report. Supported types of IDs are:
  - campaign_ids - List of campaign IDs. Can be fetched from campaigns edge.
  - publisher_ids - List of publisher IDs. Can be fetched from campaign/publishers edge. Applicable only to mta reports.
  - fb_conversion_event_filters - Conversion event filters. Applicable to only mta reports. It should contain the following field:
    - fb_conversion_event_id - Conversion event ID. Can be fetched from fb_conversion_events edge.
- attribution_config - Attribution configuration associated with the report. Applicable only to mta report.
  - date_range_option - One of conversions or contributors. conversions aggregate conversions that occurred during the report date range, contributors aggregate conversions that occurred based on when the touchpoints occurred.

Report Runs

A report run represents one instance of report generation. Creating a new report run starts a new report generation.

To list report runs under a report:

curl -G \
  -d 'access_token=...' \
  'https://graph.facebook.com/<VERSION_ID>/<REPORT_ID>/report_runs'

Reading a single report run:

curl -G \
  -d 'access_token=...' \
  'https://graph.facebook.com/<VERSION_ID>/<REPORT_RUN_ID>'

Read-only fields are:

id - ID of the report run
status - One of scheduled, running, error, size_exceeded, timeout, completed. When state becomes completed, the report run is eligible for download.

To download a completed report run:

curl -GL \
  -d 'access_token=...' \
  -d 'filename=test_run' \
  'https://graph.facebook.com/<VERSION_ID>/<REPORT_RUN_ID>/data'

Notice that -L is needed, because the initial request will respond with a HTTP 304 redirect.

To create a new report run:

curl \
  -F 'access_token=...' \
  -F 'report_runs=
  [{
    "name": "Sample report run",
    "email_addresses": ["test@tfbnw.net"],
    "email_suffix": "sample report",
    "email_report_attachment": "attached",
  }]' \
  'https://graph.facebook.com/<VERSION_ID>/<REPORT_ID>/report_runs'

name - Name of the report run.
email_addresses - List of email addresses that will receive a report run completion email. Optional.
email_suffix - Text to be appended to report run completion email. Optional.
email_report_attachment - attached or not_attached. When attached, the report run file will be attached to the email. A download link is included in the completion email in either case. Default not_attached. Optional.

Report Schedules

You can only create one report schedule can be created per report. You may want to use the report schedule's recurrence value to run the report at a desired frequency.

To list report schedule under a report:

curl -G \
  -d 'access_token=...' \
  'https://graph.facebook.com/<VERSION_ID>/<REPORT_ID>/report_schedules'

To read a single report schedule:

curl -G \
  -d 'access_token=...' \
  'https://graph.facebook.com/<VERSION_ID>/<REPORT_SCHEDULE_ID>'

To create a report schedule:

curl \
  -F 'access_token=...' \
  -F 'report_schedules=
  [{
    "is_active": true,
    "recurrence_type": "weekly",
    "recurrence_values": [1,3],
    "minute_of_day": 240,
    "date_range": {
      "time_zone": "America/Los_Angeles",
      "begin_date": "2017-06-01T00:00:00",
      "end_date": "2017-08-31T23:59:59"
     }
  }]' \
  'https://graph.facebook.com/VERSION_ID/REPORT_ID/report_schedules'

is_active - Explicitly activates or deactivates report schedule.
recurrence_type - One of once, daily, monthly, weekly.
recurrence_values - List of numerical values specifying represent when a report runs within the granularity from recurrence_type. If recurrence_type is weekly, recurrence_values can be 1 to 7 where 1 is Monday. If recurrence_type is monthly, recurrence_values can be between 1 to 31. Otherwise recurrence_values must not be set or empty.
minute_of_day - A numerical value that will represent when report will be prepared within a day. Report will be ready by the scheduled time at best effort. Value be between 0 to 1339. eg. 240 means report will prepared by 4 am.
time_zone - Time zone of the report schedule as a TZ time zone string.
begin_date - Begin date of when schedule should be activated in ISO 8601 format.
end_date - Begin date of when schedule should be deactivated in ISO 8601 format.

Reporting on Campaigns

Campaigns are read only. To access information:

curl -G \
  -d 'access_token=...' \
  'https://graph.facebook.com/<VERSION_ID>/<LOB_ID>/campaigns'

To read a single campaign:

curl -G \
  -d 'access_token=...' \
  'https://graph.facebook.com/<VERSION_ID>/<CAMPAIGN_ID>'

Read only fields are:

id - ID of a campaign.
name - Name of a campaign.
alias - External ID of a campaign.
type - One of display or search, where display campaigns are synced from external sources and search campaigns are synced from search partners.

To filter campaigns:

curl -G \
  -d 'access_token=...' \
  -d 'filter_by={"types":["display"],"name_filter":{"filter_strings":["a"],"string_query_type":"contains"}}' \
  'https://graph.facebook.com/<VERSION>/<CAMPAIGN_ID>/campaigns'

filter_by - Filter param is a JSON structure.
- types - Search by type field. List of display or search
- name_filter - Search by name field
  - filter_string - List of string to search
  - string_query_type - String search type. Either contains or exact_match
- alias_filter - Search by alias field
  - filter_string - List of string to search
  - string_query_type - String search type. Either contains or exact_match
- name_or_alias_filter - Search by name or alias field
  - filter_string - List of string to search
  - string_query_type - String search type. Either contains or exact_match

Publishers

Publishers are read only. These reports list publishers associated with a campaign.

curl -G \
  -d 'access_token=...' \
  'https://graph.facebook.com/<VERSION_ID>/<CAMPAIGN_ID>/publishers'

Reading a publisher:

curl -G \
  -d 'access_token=...' \
  'https://graph.facebook.com/<VERSION_ID>/<PUBLISHER_ID>'

Read only fields are:

id - ID of a publisher.
name - Name of a publisher.

Filtering publishers:

curl -G \
  -d 'access_token=...' \
  -d 'filter_by={"name_filter":{"filter_strings":["a"],"string_query_type":"contains"}}' \
  'https://graph.facebook.com/<VERSION_ID>/<CAMPAIGN_ID>/publishers'

filter_by - Filter params are a JSON structure.
- name_filter - Search by name field
  - filter_string - List of string to search
  - string_query_type - String search type. Either contains or exact_match

Conversion Events

Facebook conversion events are read only.

curl -G \
  -d 'access_token=...' \
  'https://graph.facebook.com/<VERSION_ID>/<LOB_ID>/fb_conversion_events'

Reading a single FB conversion event:

curl -G \
  -d 'access_token=...' \
  'https://graph.facebook.com/<VERSION_ID>/<FB_CONVERSION_EVENTS_ID>'

Read only fields are:

id - ID of a conversion event.
name - Name of a conversion event.

Filtering conversion events:

curl -G \
  -d 'access_token=...' \
  -d 'filter_by={"name_filter":{"filter_strings":["a"],"string_query_type":"contains"}}' \
  'https://graph.facebook.com/<VERSION_ID>/<LOB_ID>/fb_conversion_events'

filter_by - Filter params are a JSON structure.
- name_filter - Search by name field
  - filter_string - List of string to search
  - string_query_type - String search type. Either contains or exact_match

Report Columns

These are read-only. These are the available report columns that can be used in reports under a LoB.

curl -G \
  -d 'access_token=...' \
  'https://graph.facebook.com/<VERSION_ID>/<LOB_ID>/report_columns'

Sample response:

{
  "data": [
    {
      "aggregation_usage": "dimension",
      "area": "serving",
      "category": "standard",
      "description": "The name of the campaign.",
      "incompatibilities": [
        {
          "category": "standard",
          "key": "action_requests"
        },
        {
          "category": "standard",
          "key": "url_without_params"
        }
      ],
      "key": "campaign_name",
      "name": "Campaign Name"
    },
    ...
  ]
}

From this JSON structure, only key needs to be put into report definition. The rest of the fields are meta data of the column.