Announcement: Draft campaigns now accessible via the API

[AdsAPI]

Today we are announcing the ability to view, edit, and delete draft campaigns via the API.

With this change, we’re introducing the boolean draft_only parameter as well as the entity_status attribute in our response objects for campaigns and line items. In addition, it will be possible to access entities, such as promoted tweets, that are part of a draft campaign. Note that it will not be possible to create or activate draft campaigns via the API.

The draft_only parameter will be accepted when making requests to the following endpoints:

• GET accounts/:account_id/campaigns
• GET accounts/:account_id/line_items
• GET accounts/:account_id/targeting_criteria
• GET accounts/:account_id/promoted_tweets
• GET accounts/:account_id/promoted_accounts
• GET accounts/:account_id/media_creatives
• GET accounts/:account_id/preroll_call_to_actions

Examples using the draft_only parameter:

$ twurl -H ads-api.twitter.com "/1/accounts/18ce54d4x5t/line_items?draft_only=true" | jq
{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "draft_only": true
    }
  },
  "data": [
    {
      "bid_type": "MAX",
      "advertiser_user_id": 756201191646691300,
      "name": "Untitled",
      "placements": [
        "TWITTER_PROFILE",
        "TWITTER_TIMELINE"
      ],
      "start_time": null,
      "bid_amount_local_micro": 2000000,
      "automatically_select_bid": false,
      "advertiser_domain": null,
      "target_cpa_local_micro": null,
      "primary_web_event_tag": null,
      "charge_by": "ENGAGEMENT",
      "product_type": "PROMOTED_TWEETS",
      "end_time": null,
      "bid_unit": "ENGAGEMENT",
      "total_budget_amount_local_micro": null,
      "objective": "TWEET_ENGAGEMENTS",
      "id": "6ll9a",
      "entity_status": "DRAFT",
      "paused": false,
      "account_id": "18ce54d4x5t",
      "optimization": "DEFAULT",
      "categories": [],
      "currency": "USD",
      "created_at": "2016-10-27T23:53:09Z",
      "tracking_tags": [],
      "updated_at": "2016-10-27T23:53:09Z",
      "include_sentiment": "POSITIVE_ONLY",
      "campaign_id": "6aian",
      "creative_source": "MANUAL",
      "deleted": false
    }
  ],
  "data_type": "line_item",
  "total_count": 1,
  "next_cursor": null
}

$ twurl -H ads-api.twitter.com "/1/accounts/18ce54d4x5t/targeting_criteria?line_item_id=6ll9a&draft_only=true" | jq
{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "line_item_id": "6ll9a",
      "draft_only": true
    }
  },
  "data": [
    {
      "line_item_id": "6ll9a",
      "name": "United States",
      "id": "afypqh",
      "account_id": "18ce54d4x5t",
      "location_type": "COUNTRY",
      "created_at": "2016-10-27T23:53:09Z",
      "targeting_value": "96683cc9126741d1",
      "updated_at": "2016-10-27T23:53:09Z",
      "deleted": false,
      "targeting_type": "LOCATION"
    }
  ],
  "data_type": "targeting_criterion",
  "total_count": 1,
  "next_cursor": null
}

Given that it’s not possible to activate draft campaigns, the following error will be thrown when attempting to update the paused attribute (to either true or false):

$ twurl -X PUT -H ads-api.twitter.com "/1/accounts/18ce54d4x5t/campaigns/6aian?paused=true" | jq
{
  "errors": [
    {
      "code": "INVALID_PARAMETER",
      "message": "Draft entities can only be activated or paused via the Twitter Ads UI",
      "parameter": "paused"
    }
  ],
  "request": {
    "params": {
      "campaign_id": "6aian",
      "paused": true,
      "account_id": "18ce54d4x5t"
    }
  }
}

Twitter Ads API Team

[AdsAPI]

[AdsAPI]