Atlas API Changelog

This changelog covers what's changed in Atlas APIs.

The v2.3 is the first versioned release for the Atlas API. Developers using the Atlas API should update their apps to call v2.3 before July 19th, 2015. After that date, all calls not using the version number will break and return error.

The most recent version of the API is Version 2.7, which was introduced on July 13, 2016.

Atlas product continues to evolve at fast pace. To ensure developers continue to take advantage of this progress, note few things regarding versioning:

  • The Atlas API will introduce a new version every 90 days starting with the v2.4 release. Given API version will be live for 180 days before it stops working.
  • If there has been no API change in the new version, you can continue to use the old version in the call and Atlas backend will automatically bump the version to the latest.
  • If there is change introduced for an API call in the new version, you will have to implement the changes on your client side before the old format is deprecated.

Versions:

VersionPathDate IntroducedAvailable Until

v2.7

/v2.7/{object}

July 13, 2016

TBD

v2.6

/v2.6/{object}

April 12th, 2016

Oct 2016

v2.5

/v2.5/{object}

October 7th, 2015

July 13, 2016

v2.4

/v2.4/{object}

July 8th, 2015

April 11th, 2016

v2.3

/v2.3/{object}

May 15th, 2015

July 19th, 2015

April 12th, 2016 - API version 2.6

Changes

Reduced Default Fields

Atlas APIs will return a reduced set of default fields. Use the fields param to explicitly ask for the set of fields you want. If you ask for an explicit set of fields, the response will not contain any extra fields that you did not ask for.

GET /v2.6/<ATLAS_COMPANY_ID>

Response

{
    "id": "<COMPANY_ID>",
    "name": "My Company",
}

Removal of Duplicate Cost Package Fields

We deprecate units and cost basis fields on cost package with v2.6 in favor of the cost basis and quantity fields on cost periods.

Posts to Atlas Cost Packages will no longer honor date ranges, units, or cost basis. You can continue to post these fields to the associated Cost Periods.

We will also be deprecating the units and cost basis fields from Cost Package reads. You can continue to read the date range field on Cost Package which will be inferred from the associated cost periods.

  • https://graph.atlassolutions.com/v2.6/<COST_PACKAGE_ID>?fields=units
{
  "error": {
    "message": "(#12) units field is deprecated for versions v2.6 and higher",
    "type": "OAuthException",
    "code": 12,
  }
}

Replacement of _id Fields by Edge Objects

Atlas APIs will no longer expose id of edge object as <object>_id fields. Instead, that data can be accessed via the edge object. E.g. ?fields=<object>{id}.

For example, in v2.5

GET /v2.5/<CAMPAIGN_ID>?fields=billing_entity_id

returns

{
   "billing_entity_id": "11182200774273",
   "id": "11002200634421"
}

However, in v2.6, it returns error

{
   "error": {
      "message": "Tried accessing nonexisting field (billing_entity_id) on node type (AtlasCampaign)",
      "type": "FacebookApiException",
      "code": 100,
   }
}

Instead, you need to call

GET /v2.6/<CAMPAIGN_ID>?fields=billing_entity{id}

Disable Returning Indirectly Shared Action Tag / Multi Action Tag

Atlas edges that return Action Tag and Multi Action Tag objects will no longer include indirectly shared objects. That is: if an Action Tag is explicitly shared to an advertiser, but the parent Multi Action Tag is not explicitly shared. The Action Tag will continue to be included but the Multi Action Tag will not. That Multi Action Tag will continue to be accessible by its ID.

GET /v2.6/<ATLAS_ADVERTISER_ID>?fields=action_tags

Validation on Default Ad Event

We add validate on default Ad Event such that an Ad associated with Ad Events has one and only one default Ad Event.

If you try to create a new ad event and accociate to an ad which already has a default ad event

curl -F 
"ad_events=
[{
    'name':'2nd Default Ad Event',
    'click_through_id': '<CLICK_THROUGH_ID>',
    'is_default_ad_event':true,
},
]" 
-F "access_token=<ACCESS_TOKEN>"
"https://graph.atlassolutions.com/v2.6/<AD_ID>/ad_events"

The request will fail with error

{
  "data":[{
      "error":{
          "type":"Exception",
          "message":"Invalid Params passed, most likely caused by malformed inputs or empty inputs.",
          "code":1763006
        },
      "success":false
  }]
}

October 7th, 2015 - Atlas API version 2.5

Changes

New domain for Atlas API calls

All calls to the Atlas API should go through https://graph.atlassolutions.com instead of https://graph.facebook.com. Calls to https://graph.facebook.com will be supported until the 4th of April, 2016.

Delete prevention on nodes with reporting data

You will receive an error message in your reponse when you try to delete nodes of the following type that have reporting data associated with them

The name change of columns field on Report Definition

The old columns field is replaced with column_definitions. Please check here about details of reporting concepts.

New Features

User API

Add permissions edge to Atlas User endpoint to show permissions associated with the user. Use following edge call to check user's permissions:

  • https://graph.atlassolutions.com/v2.5/<atlas-user-id>/permissions

Permission API

A new endpoint that defines permissions for an Atlas User by associating a role (role_id) and defining the scope (resource_id: company/branch/client/advertiser ID.).

You can make a POST request to permissions edge from the following paths with JSON format parameter permissions:

  • https://graph.atlassolutions.com/v2.5/<atlas_user_id>/permissions?permissions=[{ resource_id:<resource_id>, atlas_user_id:<atlas_user_id>, role_id:<role_id> }]

When posting to this edge, an AtlasPermission will be created. Details see here

Role API

A role defines the type of access available for various data. A list of Atlas roles can be query by calling roles edge on company endpoint

  • https://graph.atlassolutions.com/v2.5/<atlas-company-id>/roles

Campaign API

You can now query creative sets associated with a campaign. A list of creative sets can be retrieved by calling the edge or the field. The API call examples are shown below:

  • https://graph.atlassolutions.com/v2.5/<campaign_id>/creative_sets
  • https://graph.atlassolutions.com/v2.5/<campaign_id>?fields=creative_sets

Audience API

You can now query campaigns associated with an audience. The audience details can be retrieved by calling the edge or the field. The API call examples are shown below:

  • https://graph.atlassolutions.com/v2.5/<audience_id>/campaigns
  • https://graph.atlassolutions.com/v2.5/<audience_id>?fields=campaigns

Advertiser API

Additional link_token field on the advertiser node, which shows generated token for Atlas Advertiser.

Placement API

Additional search_click_url_template field on the placement node, which shows sample tracking URL for Search Tracking.

ActionTag API

Additonal can_edit field on the action tag node.

Additional property branch_name on the advertiser_profile field of the action tag node.

MultiActionTag API

Additional can_edit field on the multi action tag node.

Additional owning_advertiser_profile field on the multi action tag node, which shows details (including branch_name, client_name, name and id) of owning advertiser profile for cross-advertiser action.

Additional property in_app_tag to the trafficking_tags field of the multi action tag node.

July 8th, 2015 - Atlas API version 2.4

Version 2.3 will be available until Oct 7th, 2015. Before that date, you should migrate your API calls to v2.4.

Changes

The flight_dates field validation on Placement node

When creating display placements, if no non-zero date range is specified an error with code 1763026 and message Invalid date range specified will be thrown.

The cumulative_edited_date field will not be part of default fields

If you have hard coded to expect this field in your code base, you will have to remove that logic. Otherwise, this should not break your implementation.

The owner_id field removal from ActionTag node

If you have hard coded to expect this field in your code base, you will have to remove that logic. Otherwise, this should not break your implementation.

New Features

Publisher API

You can now query action tags associated with a publisher. The action tags details can be retrieved by calling the edge or the field. The API call example is shown below:

  • https://graph.facebook.com/v2.4/<publisher_id>/shared_action_tags
  • https://graph.facebook.com/v2.4/<publisher_id>?fields=shared_action_tags

You can now list the atlas users associated with a publisher. The atlas user details can be retrieved by calling the edge or the field. The API call example is shown below:

  • https://graph.facebook.com/v2.4/<publisher_id>/atlas_users
  • https://graph.facebook.com/v2.4/<publisher_id>?fields=atlas_users

Company API

You can now list the atlas users associated with a publisher. The atlas user details can be retrieved by calling the edge or the field. The API call example is shown below:

  • https://graph.facebook.com/v2.4/<company_id>/atlas_users
  • https://graph.facebook.com/v2.4/<company_id>?fields=atlas_users

Audience API

You can now get the campaigns associated with a publisher. The campaign details can be retrieved by calling the edge or the field. The API call example is shown below:

  • https://graph.facebook.com/v2.4/<audience_id>/campaigns
  • https://graph.facebook.com/v2.4/<audience_id>?fields=campaigns

Campaign API

You can now get mixins used in the campaign. The mixins can be retrieved by calling the edge or the field. The API call example is shown below:

  • https://graph.facebook.com/v2.4/<campaign_id>/mixins
  • https://graph.facebook.com/v2.4/<campaign_id>?fields=mixins

Additional field is_auto_tracked field on the campaign node. For automatically created tracking campaigns, there will be a new field called is_auto_tracked with value true to denote the type of the campaign.

These tracking campaigns are automatically created when the campaign is mirrored from other publishers. Hence this change should not affect rest of the developers and campaign creation flow. For these developers when pulling the details on a campaign, you will see this field value being set to false.

Ad API

You can now get trafficking data associated with an ad. It can be retrieved by calling the edge or the field. The API call example is shown below:

  • https://graph.facebook.com/v2.4/<ad_id>/trafficking_data
  • https://graph.facebook.com/v2.4/<ad_id>?fields=trafficking_data

July 19th, 2015 - Atlas API version 2.3

Un-versioned calls will no longer be supported

In order to better support changes in the future, we are adding a version to each request. This means that all future requests will need to be versioned, allowing you to stay on older versions, while we build new versions, without interrupting your application. As the newer versions are ready, you'll be able to move to them.

Use following structure:

https://graph.facebook.com/v2.3/<campaign_id>/click_throughs
or 
https://graph.facebook.com/v2.3/<campaign_id>

Instead of the following structure:

https://graph.facebook.com/<campaign_id>/click_throughs
or 
https://graph.facebook.com/<campaign_id>

Response result changes for created_by and last_modified_by fields

Notice that responses will have change over the version. created_by and last_modified_by are no longer an ID in the new version, but an object.

You will see following data in the response:

"created_by": {
    "id": "824722617545798", 
  "name": "Liubov Zvereva"
}, 

Rather than following data in the reponse:

"created_by": "824722617545798", 

Any edge name prefixed by atlasXXXXX will no longer be supported

We recommend that you switch to the unprefixed versions of the API. Example:

Use following:

https://graph.facebook.com/v2.3/<campaign_id>/click_throughs

Insead of:

https://graph.facebook.com/<campaign_id>/atlasclickthroughs

In general, the param names and params didn't change from the prefixed to the unprefixed names. You will only need to change the edge name and add a version to it to update. We recommend that version be made a constant in your system such that it can be changed globally.

Field Expansion suppport

Version 2.3 also includes support for field expansions. To learn more about field expenstion, read Nested Requests of the Graph API doc.

Post request result changes

The response of a post no longer includes the object, only the ID of the object is included. If you still want the object, please issue a separate request for it. Or, use graph batch to request for the object that was created. More documentation is available here: https://developers.facebook.com/docs/graph-api/making-multiple-requests

Any edge that extends from a user will no longer be supported with exceptions

Starting from the breaking change date, only the following edge will remain working:

https://graph.facebook.com/v2.3/me/companies
https://graph.facebook.com/v2.3/<user_id>/companies

Note that /me is a shortcut for the user who is logged into this session. The id of this user is retrieved from the access token.

Other requests such as the following will no longer work:

https://graph.facebook.com/me/atlasreports
https://graph.facebook.com/<user_id>/atlasreports

To get the reports, retrieve it as connection object from company. For example:

https://graph.facebook.com/v2.3/<company_id>/reports 
and 
https://graph.facebook.com/v2.3/<company_id>/report_runs

Report and ReportRun owner_id field is no longer required

The owner_id field is no longer required and is ignored. You can choose to exclude it in your next request.