New Cards Endpoints and Carousel Ads

[AdsAPI]

Today we are announcing a new set of more flexible and powerful Cards endpoints. These Ads API enhancements directly support Twitter’s investment in performance advertising and the new Carousel Ads.

The new JSON-based endpoints allow developers to build Cards using components rather than working with Card-specific resources. Full details can be found in our reference documentation. The new POST accounts/:account_id/cards endpoint fully supports creating Carousel Ads. A detailed usage example can be found in our Carousels Guide.

The new Cards create endpoint also supports creating website and app cards—both image and video. This will replace the following resources, which are expected to sunset with v8, on August 31, 2021:

• Website Cards
• Video Website Cards
• Image App Download Cards
• Video App Download Cards

We plan to migrate previously-created website cards and app cards to this new format in 2021, so no functionality should be lost during the transition to the new endpoints.

Twitter Ads API team

[AdsAPI]

Cards created using the new POST accounts/:account_id/cards endpoint are not available via the GET accounts/:account_id/cards/all endpoint.

We plan on adding additional functionality to the new /cards endpoints. We will share updates here as we have them.

[AdsAPI]

The GET accounts/:account_id/cards endpoint now supports a card_uris request parameter, allowing developers to specify up to 200 card URIs in a single request (example below).

$ twurl -H ads-api.twitter.com "/8/accounts/18ce54d4x5t/cards?card_uris=card://1125912035143716865"
{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "card_uris": [
        "card://1125912035143716865"
      ]
    }
  },
  "next_cursor": null,
  "data": [
    {
      "name": "test",
      "components": [
        {
          "type": "SWIPEABLE_MEDIA",
          "media_keys": [
            "3_1073727809120419840",
            "3_1075096386931052545"
          ]
        },
        {
          "type": "BUTTON",
          "label": {
            "type": "ENUM",
            "value": "INSTALL"
          },
          "destination": {
            "type": "APP",
            "country_code": "US",
            "googleplay_app_id": "com.twitter.android",
            "ipad_app_id": "333903271",
            "iphone_app_id": "333903271"
          }
        }
      ],
      "id": "7bke6",
      "created_at": "2020-09-07T23:55:22Z",
      "card_uri": "card://1125912035143716865",
      "updated_at": "2020-09-07T23:55:22Z",
      "deleted": false,
      "card_type": "UNIFIED"
    }
  ]
}

[AdsAPI]

@AdsAPI

We plan to migrate previously-created website cards and app cards to this new format in 2021, so no functionality should be lost during the transition to the new endpoints.

This work has been completed. To access previously-created website and app cards in the GET accounts/:account_id/cards endpoint, use the include_legacy_cards request parameter with the value set to true. Example below. (The card below is a previously-created video website card from the accounts/:account_id/cards/video_website resource.)

twurl -H ads-api.twitter.com "/9/accounts/18ce54d4x5t/cards?include_legacy_cards=true"
{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "include_legacy_cards": true
    }
  },
  "next_cursor": null,
  "data": [
    {
      "name": "previously-created-card",
      "components": [
        {
          "type": "MEDIA",
          "media_key": "13_1387900674604560386"
        },
        {
          "type": "DETAILS",
          "title": "Twitter",
          "destination": {
            "type": "WEBSITE",
            "url": "https://www.twitter.com"
          }
        }
      ],
      "created_at": "2021-04-29T22:46:45Z",
      "card_uri": "card://1387901195730055172",
      "updated_at": "2021-04-29T22:46:45Z",
      "deleted": false
    }
  ]
}