Marketing API Version

Development guide overview

This documentation provides a detailed walkthrough of integration with Atlas Reporting API. The following steps are required to gain API access:

The following sections talk about reporting concepts, types and workflow"

Once API access is in place, development of the following items is required:

API permission management

Atlas Solutions Consultant team will take following steps to setup a proper object model for you.

  • When your company or agency signs up with Atlas, our account team will help you identify your needs and recommends the best way to organize your account and campaigns.
  • Account team will then create service user for the top level company and assigns permission from the user to the resources under that company.
  • Finally they will associate the service user to the app you created and gives your app Atlas API access.

After this point, you can use the token generation API to get the token for each user for your comapny and make API call as the service user to the resources they have access to.

Creating an FB app and getting an access token

To have API access, you are required to create a Facebook app, which will be provisioned to make Atlas API calls using the Facebook Graph API Platform.

To generate an FB App ID, go to https://developers.facebook.com/apps and select “Create a new app"

Access tokens are required to access data or make changes to objects via the Atlas API. When API access has been granted to your app, your app is authorized to act on behalf of certain users. You can get the access token of the app's users by making an HTTP GET request.

An example of the request:

https://graph.facebook.com/<API_VERSION>/<APP_ID>?access_token=<APP_ID>|<CLIENT SECRET>&fields=manageable_users{name,access_token} 

Response:

{
   "manageable_users": {
      "data": [
         {
            "id": "123456789",
            "name": "User Name"
            "access_token": "<ACCESS TOKEN>"
         }
      ],
      "paging": {
         "cursors": {
            "before": "MTQwOTk3NDU5OTI5MjkyOQ==",
            "after": "MTQwOTk3NDU5OTI5MjkyOQ=="
         }
      }
   },
   "id": "<APP ID>"
}

If you get unknown error from the API, it is because your app is still in sandbox box. Go to the app settings and make the app public from the status section.

Reporting Concepts

A Report contains metadata information of a report. It is possible to programmtically email reports to people. See Report API to view all the fields. Example fields:

The Report Definition includes a columns parameter which is used to configure the data columns to be included in the Report. The report columns have incompatibility restrictions imposed by business rules which do not let you choose certain combination of report columns. See Report Definition API to view all the fields. Example fields:

The Report Column Definition represents what each column in the report means. See Report Column Definition API to view all the listed fields. Example fields:

The Report definition filters on report definition field provides way to filter report data results. For example, you can provide advertiser_id or client_id as filters for report definition. The fiters will refine the report and provide data specific to that advertiser and/or client. See Report defintition filters for all details. Enum types for the filtering:

A Report Run is an instance of the report. A Report must be explicitly executed in order to generate a report run. Every report run is associated with a report. It is possible to schedule a report to execute on a future date in which case the status of report run would be 'scheduled'. See Report Run API to view all report run fields.

  • See Report Schedule API to view the report schedule fields.
  • Report run has different status associated with it. When the report is executed, report run has a running status. When the status of report run changes to completed, you can download the report data from the report run edge.

There are certain business rules regarding incompatibility between some report columns. This means that you cannot create report definitions with certain combinations of report columns. You can use the reporting api to get the list of columns and incompatibility details.

Reporting Types

You can create different report types within atlas. To do that:

  • Specify the desired report_type value within the report definition.
  • Specify the available columns for column_definition. To see which columns are available for which report types, see the following table
report_typenamedescription

column_determinded

Column Determined

These types of reports allow you to pull ad delivery, audience and performance data.

data_pass_back

Data passback

These types of reports give you raw data for events and conversions. These reports are cookie based.

mapping

Mapping

These types of reports let you export all of the names and IDs associated with your campaigns.

reach_overlap

Reach overlap

These types of reports help you understand how your audience overlaps across clients, advertisers, campaigns, publishers and sites.

publisher

Publisher

These types of reports allows a publisher to see impression, click, conversion data across its affiliated sites within Atlas.

reach_frequency

Reach and Frequency

These types of reports help you to get an understanding of how many people have seen your ads and how often.

Reporting Workflow

The workflow involves the following steps:

  • Creating a report definition - This object may include report type, report definition filters, report column definition, report schedule objects. Some of these objects may depend on other objects for their creation.
  • Execute the report to get a report run - This step would include actually running a report to get results.
  • Check report run status - Some reports may take a while to complete and you can check the status of a report run.
  • Read report run data - After the report run is completed, you can read the report run data.

Create Report

It is recommended to use the User Interface to create reports because of the complex nature of this API operation.

Create report by making an HTTP POST request to company or atlas user end points. The post request will create a Report object and returns the Report Object ID in the response.

  • View Report API definition for all the fields and edges.

Example Request:


https://graph.facebook.com/<API_VERSION>/<COMPANY_ID>/reports? reports=[ { "name": "Test Report", "version": 1, "description": "", "definition": { "report_type": "column_determined", "column_definitions": [ { "area": "serving", "category": "standard", "key": "ad_id", "name": "Ad ID", "attribution_model": "null", "aggregation_usage": "dimension" }, { "area": "serving", "category": "standard", "key": "ad_name", "name": "Ad Name", "attribution_model": "null", "aggregation_usage": "dimension" }, { "area": "serving", "category": "standard", "key": "advertiser_id", "name": "Advertiser ID", "attribution_model": "null", "aggregation_usage": "dimension" }, { "area": "serving", "category": "standard", "key": "advertiser_name", "name": "Advertiser Name", "attribution_model": "null", "aggregation_usage": "dimension" }, { "area": "attribution", "attribution_model": "last_touch", "category": "standard", "key": "counters_clicks", "name": "Clicks", "aggregation_usage": "metric" }, { "area": "attribution", "attribution_model": "last_touch", "category": "standard", "key": "clickthrough_rate", "name": "Clickthrough Rate %", "aggregation_usage": "metric" } ], "date_range": { "type": "relative", "date_unit": "day", "quantity": "0", "time_zone": "America/New_York" }, "time_zone": "America/New_York", "crosstab_columns": [], "action_tag_ids": [ "11002202715842" ], "filters": { "advertiser_ids": [ "11077200770662" ], "branch_ids": [ "11077200629234" ], "campaign_ids": [ "11077201127917" ], "client_ids": [ "11077200629235" ], "company_ids": [ "11077200629233" ], "publisher_ids": [ "11182200774314" ], "site_ids": [ "11182200828329" ] } }, "file_format": "xlsx", "is_email_enabled": false, "email_addresses": [], "email_suffix": "" } ]

Example Response:

{
  "data": [
    {
      "id": "11182201008254", 
      "success": true
    }
  ]
}

Generate ad hoc report runs

You can generate ad hoc report runs for a company by making an HTTP POST request to company report_run edge.

Refer to the Atlas Report Run API Reference Document to get all the field definition.

Example POST request to generate report run:

https://graph.facebook.com/<API_VERSION>/<COMPANY_ID>/report_runs?
report_runs=[
    {
        "name": "Test Report",
        "version": 1,
        "description": "",
        "definition": {
            "report_type": "column_determined",
            "column_definitions": [
                {
                    "area": "serving",
                    "category": "standard",
                    "key": "ad_id",
                    "name": "Ad ID",
                    "attribution_model": "null",
                    "aggregation_usage": "dimension"
                },
                {
                    "area": "serving",
                    "category": "standard",
                    "key": "ad_name",
                    "name": "Ad Name",
                    "attribution_model": "null",
                    "aggregation_usage": "dimension"
                },
                {
                    "area": "serving",
                    "category": "standard",
                    "key": "advertiser_id",
                    "name": "Advertiser ID",
                    "attribution_model": "null",
                    "aggregation_usage": "dimension"
                },
                {
                    "area": "serving",
                    "category": "standard",
                    "key": "advertiser_name",
                    "name": "Advertiser Name",
                    "attribution_model": "null",
                    "aggregation_usage": "dimension"
                },
                {
                    "area": "attribution",
                    "attribution_model": "last_touch",
                    "category": "standard",
                    "key": "counters_clicks",
                    "name": "Clicks",
                    "aggregation_usage": "metric"
                },
                {
                    "area": "attribution",
                    "attribution_model": "last_touch",
                    "category": "standard",
                    "key": "clickthrough_rate",
                    "name": "Clickthrough Rate %",
                    "aggregation_usage": "metric"
                }
            ],
            "date_range": {
                "type": "relative",
                "date_unit": "day",
                "quantity": "0",
                "time_zone": "America/New_York"
            },
            "time_zone": "America/New_York",
            "crosstab_columns": [],
            "action_tag_ids": [
                "11002202715842"
            ],
            "filters": {
                "advertiser_ids": [
                    "11077200770662"
                ],
                "branch_ids": [
                    "11077200629234"
                ],
                "campaign_ids": [
                    "11077201127917"
                ],
                "client_ids": [
                    "11077200629235"
                ],
                "company_ids": [
                    "11077200629233"
                ],
                "publisher_ids": [
                    "11182200774314"
                ],
                "site_ids": [
                    "11182200828329"
                ]
            }
        },
        "file_format": "xlsx",
        "is_email_enabled": false,
        "email_addresses": [],
        "email_suffix": ""
    }
]

Generate scheduled report runs

You can schedule reports to execute at a future date and time. It can be set up as a recurring event with values like daily, weekly, monthly or once and you can specify the minute of the day when the report is supposed to execute. You can also set the schedule to active or inactive.

Refer to the Atlas Report Schedule API Reference Document to get all the field definition.

Example Request for weekly scheduled report:

https://graph.facebook.com/<API_VERSION>/<REPORT_ID>/report_schedules?report_schedules=[{
  "is_active":true,
  "date_range":{
    "begin_date":"2015-8-11 0:0:0",
    "end_date":"2015-8-26 0:0:0",
    "time_zone":"America/Los_Angeles"
  },
  "recurrence_type":"weekly",
  "recurrence_value":2,
  "minute_of_day":420
}]

Example Request for once scheduled report:

https://graph.facebook.com/<API_VERSION>/<REPORT_ID>/report_schedules?report_schedules=[{
  "is_active":true,
  "date_range":{
    "begin_date":"2015-8-11 0:0:0",
    "end_date":"2015-8-26 0:0:0",
    "time_zone":"America/Los_Angeles"
  },
  "recurrence_type":"once",
  "recurrence_value":0,
  "minute_of_day":420
}]

Response:

{
  "data": [
    {
      "id": "11002200631900", 
      "success": true
    }
  ]
}

Retrieve the report data

Retrieve report run ids

Example GET request,

https://graph.facebook.com/<API_VERSION>/<REPORT_ID>/report_runs?fields=id

The response will look something like this:

{
  "data": [
    {
      "id": "11182201008255"
    },
    {
      "id": "11182201008259"
    },
    {
      "id": "11182201008267"
    },
    {
      "id": "11182201008279"
    },
    {
      "id": "11182201020624"
    },
    {
      "id": "11182201020648"
    },
    {
      "id": "11182201020670"
    }
  ]
}

Check report run status

Once the report starts executing, you can check the completion status of the report run using the report_id you retrieved from the above API request. The possible status types for reports can be: scheduled, running, completed, error, and timeout. This is particularly useful for reports running for long periods of time.

To retrieve the report run status, get the status field for report run node.

Example request:

https://graph.facebook.com/<API_VERSION>/<REPORT_RUN_ID>?fields=status

Response:

{
  "status": "completed",
  "id": "11182200967788"
}

ReportRunStatus is the enumerated type for current status of report run.

ValueDescription

ReportRunStatus.Scheduled

Refers to scheduled status of report run

ReportRunStatus.Running

Refers to running status of report run

ReportRunStatus.Completed

Refers to completed status of report run

ReportRunStatus.Error

Refers to error status of report run

ReportRunStatus.Timeout

Refers to timeout status of report run

Download the data

You can download the report run data through the download url provided by the API. The report can be generated in a csv or xlsx format. There are different download urls for Standard and Data Pass Back Reports.

The report run ids can be retrieved by the API explained in Ad hoc report runs or Scheduled report runs section of this document.

Example request:

https://graph.facebook.com/<API_VERSION>/<REPORT_RUN_ID>/data?filename=data&access_token=<ACCESS_TOKEN>

Response:

The response will be a file download generated named data.csv

A sample custom report may look like below: