Atlas Ads Campaign Management

In this tutorial we will walk you through all necessary steps to create and manage Atlas campaigns using the Atlas API.


  1. Atlas API Quickstart
  2. Build and Manage Campaigns

    # Next Steps

1. Atlas API Quickstart

See the following guides:

  • Atlas API Overview provides basic instructions for all components in Atlas API.

  • Atlas API Getting Started to start using Atlas API. You'll learn how to set up and configure a Facebook App for Atlas, generate access token to use Atlas API.

Permissions

Atlas provides API access to a set of APP IDs for development and testing. You have access to Atlas API when the Atlas organization object associated with your Facebook developer token is on an access list. If you are a partner or agency, Atlas teams manage your API access list for mutual customers as part of the on-boarding process. Please contact your Facebook representative for more information.

Reference: Using Atlas API

2. Build and Manage Campaigns

Create Campaigns

In this step we create a new campaign using the class Campaign, with a list of campaign object definitions as parameters. In our example we:

  1. Campaign Name - Set a name, "My First Campaign".
  2. Campaign Duration - Define when the campaign runs (flight_dates).
  3. Campaign Type - Provide the campaign type (search / display). In the example, we use the default value diaplay. In the example, we use the default value display. For search engines, you use different campaign types, see search partner integration.
  4. Billing Information - Describe who gets billed with billing_entity_id. Note you cannot use Atlas Billing Entity with the API. Please contact your Facebook representative to set it up and get the ID during on-boarding process.
curl \
-F "campaigns=
[{
  'name':'My First Campaign',
  'type':'display',
  'flight_dates':
      {
        'begin_date':'2015-10-22T00:00:00-0400',
        'end_date':'2015-11-01T23:59:59-0500',
        'time_zone':'America/New_York'
      },
  'billing_entity_id': <BILLING_ENTITY_ID>,
}]" \
-F "access_token=<ACCESS_TOKEN>" \
https://graph.atlassolutions.com/v2.5/<ATLAS_ADVERTISER_ID>/campaigns

Verify Campaigns

To verify that your campaign was created, you can check Atlas App campaign list filtered by your ATLAS_ADVERTISER_ID.

Alternatively, you can make a GET call to the Atlas Advertiser Campaigns edge to get all campaigns associated with the advertiser.

GET /<API_VERSION>/<ATLAS_ADVERTISER_ID>/campaigns HTTP/1.1
Host: graph.atlassolutions.com

Using filter_by Parameter You can make read requests with the filter_by parameter to get Atlas campaigns with specific features. For example, to retrieve search campaigns only, you can pass filter_by={"types": ["search"],} as a parameter.

filter_by is a very useful parameter to retrieve camapagins with sepecific features. For example, to retrieve search campaign only, you can pass filter_by={"types": ["search"],} as parameter.

  • The filter rule need to be JSON format.
  • Key of the filter rule should be “types”, value is a string array. [“search”, “display”] would get all campaigns

Response is a list of JSON formatted search campaigns information.

Similarly, you can pass filter_by={"aliases": ["alia_1","alias_2"],} to lookup campaign ID based on campaign alias.

Example Code

GET /<ATLAS_ADVERTISER_ID>/campaigns?filter_by={"types": ["search"],}&summary=count   
  • where we also pass in summary=count to get count of campaigns

Response

{
  "data": [
    {
      "advertiser_id": "<ATLAS_ADVERTISER_ID>",
      "alias": "",
      "billing_entity_id": "0",
      "created_date": "2015-11-19T08:18:27+0000",
      "creator_name": "creator name",
      "default_ad_id": "0",
      "description": "",
      "flight_dates": {
        "begin_date": "2015-11-03T00:51:32-0500",
        "end_date": "2015-11-03T00:51:32-0500",
        "time_zone": "America/New_York"
      },
      "id": "",
      "is_auto_tracked": false,
      "is_favorite": false,
      "last_modified_date": "2015-11-19T08:18:27+0000",
      "name": "<account>campaign_number>",
      "purchase_order_alias": "",
      "type": "search",
      "version": "1"
    },
    {
      "advertiser_id": "<ATLAS_ADVERTISER_ID>",
      "alias": "",
      "billing_entity_id": "0",
      "created_date": "2015-11-19T08:20:15+0000",
      "creator_name": "creator name",
      "default_ad_id": "0",
      "description": "",
      "flight_dates": {
        "begin_date": "2015-11-03T00:51:32-0500",
        "end_date": "2015-11-03T00:51:32-0500",
        "time_zone": "America/New_York"
      },
      "id": "",
      "is_auto_tracked": false,
      "is_favorite": false,
      "last_modified_date": "2015-11-19T08:20:15+0000",
      "name": "<account>campaign_number>",
      "purchase_order_alias": "",
      "type": "search",
      "version": "1"
    }
  ]
  "summary": {
    "count": 2
  }
}

Read an Atlas campaign details

Get details for an Atlas campaign with this API call:

curl -G \
-d "access_token=<ACCESS_TOKEN>" \
https://graph.atlassolutions.com/<API_VERSION>/<atlas_campaign_id>

Which returns a JSON-formatted result:

{
  "advertiser_id": "<ATLAS_ADVERTISER_ID>",
  "alias": "",
  "billing_entity_id": "<BILLING_ENTITY_ID>",
  "created_date": "2015-11-06T18:59:51+0000",
  "creator_name": "Creator Name",
  "default_ad_id": "0",
  "description": "",
  "flight_dates": {
    "begin_date": "2015-10-22T04:00:00-0400",
    "end_date": "2015-11-02T04:59:59-0500",
    "time_zone": "America/New_York"
  },
  "id": "<CAMPAIGN_ID>",
  "is_auto_tracked": false,
  "is_favorite": false,
  "last_modified_date": "2015-11-06T18:59:51+0000",
  "name": "My First Campaign",
  "purchase_order_alias": "",
  "type": "display",
  "version": "1",
}

Update Campaigns

You can update an existing campaign by making an HTTP POST request.

An example of the request and response: Request:

POST <API_VERSION>/<ATLAS_CAMPAIGN_ID>?name=Updated Name HTTP/1.1
Host: graph.atlassolutions.com

Response:

{
  "success": true
}

Then you can simply check by making the same GET request as reading campaign details session.

Tips: Graph API Explorer tool is a handy tool for debugging. You can use it to try requests, get and check your access tokens, and see responses.


Delete an Atlas campaign

You can delete an AtlasCampaign by making a DELETE request to

  • /{atlas_campaign_id}

Reference: Atlas CampaignAtlas Solution AppGraph API Explorer tool