Cards

Note: To associate a card with a Tweet, use the card_uri parameter with either the POST accounts/:account_id/tweet, POST statuses/update, POST accounts/:account_id/scheduled_tweets, or the POST accounts/:account_id/draft_tweets endpoints.

GET accounts/:account_id/cards¶

Retrieve details for some or all cards associated with the current account.

Note: This only returns cards that were created using the POST accounts/:account_id/cards endpoint. Cards created using other endpoints are not returned.

Resource URL¶

https://ads-api.twitter.com/9/accounts/:account_id/cards

Parameters¶

Example Request¶

GET https://ads-api.twitter.com/9/accounts/18ce54d4x5t/cards?count=1

Example Response¶

{
  "request": {
    "params": {
      "count": 1,
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": "8wzvldqtc",
  "data": [
    {
      "name": "deep link",
      "components": [
        {
          "type": "SWIPEABLE_MEDIA",
          "media_keys": [
            "3_1073727809120419840",
            "3_1075096386931052545"
          ]
        },
        {
          "type": "BUTTON",
          "label": {
            "type": "ENUM",
            "value": "OPEN"
          },
          "destination": {
            "type": "APP",
            "country_code": "US",
            "googleplay_app_id": "com.twitter.android",
            "googleplay_deep_link": "twitter://user?screen_name=apimctestface"
          }
        }
      ],
      "created_at": "2020-10-28T20:47:52Z",
      "card_uri": "card://1321554298900107264",
      "updated_at": "2020-10-28T20:47:52Z",
      "deleted": false,
    }
  ]
}

POST accounts/:account_id/cards¶

Create a new card associated to the specified account.

Card create requests only accept JSON POST bodies. The Content-Type must be set to application/json.

See our Carousels Guide for a detailed usage example.

Resource URL¶

https://ads-api.twitter.com/9/accounts/:account_id/cards

Parameters¶

The JSON POST body must include a card name and an array of components. Components are represented as objects and describe the advertiser-facing attributes of the card.

The following example shows the general structure of the payload (but includes non-working information).

{
  "name": "some name",
  "components": [
    {
      "type": "TYPE_ENUM",
      "key": "value"
    }
  ]
}

Additional information on components below.

Components¶

Every component must include a type field which determines the object's schema. The Ads API supports the following component types, grouped into media- and description-based components.

• Media:
  • MEDIA: single video or image
  • SWIPEABLE_MEDIA: between 2-6 videos or images
• Description:
  • DETAILS
  • BUTTON

Each component has a set of required fields (in addition to the type key). These are listed in the following table.

The following is an example of a BUTTON component in the context of the components array (intentionally omitting the name key). (The ellipses indicate places where more information would need to be specified.)

{
  "components": [
    {
      "type": "BUTTON",
      "label": {
        ...
      },
      "destination": {
        ...
      }
    }
  ]
}

The order in which the component objects are specified defines the top-to-bottom order in which they will be rendered. Cards must be created using one media-based component and either a DETAILS or BUTTON component. Description-based components are rendered under media and have associated destinations, either URLs or mobile apps.

Label

Labels define the text shown on buttons and, therefore, only apply to the BUTTON component. Label objects have two required keys: type and value. The type must be set to ENUM and the value can be one of: BOOK, CONNECT, INSTALL, OPEN, ORDER, PLAY, or SHOP.

Building on the previous example, the following shows the label object within the BUTTON component.

{
  "components": [
    {
      "type": "BUTTON",
      "label": {
        "type": "ENUM",
        "value": "INSTALL"
      },
      "destination": {
        ...
      }
    }
  ]
}

Destination

Destinations are where advertisers intend to take users. They are always required within DETAILS or BUTTON components. There are two destination types: WEBSITE or APP.

Note: Website destinations can only be used with DETAILS components and app destinations can only be used with BUTTON components.

Website Destination

App Destination

Example Request¶

POST https://ads-api.twitter.com/9/accounts/18ce54d4x5t/cards

{
  "name": "components create cards",
  "components": [
    {
      "type": "MEDIA",
      "media_key": "3_1323490622599176192"
    },
    {
      "type": "BUTTON",
      "label": {
        "type": "ENUM",
        "value": "INSTALL"
      },
      "destination": {
        "type": "APP",
        "country_code": "US",
        "googleplay_app_id": "com.twitter.android"
      }
    }
  ]
}

Example Response¶

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "components create cards",
    "components": [
      {
        "type": "MEDIA",
        "media_key": "3_1323490622599176192"
      },
      {
        "type": "BUTTON",
        "label": {
          "type": "ENUM",
          "value": "INSTALL"
        },
        "destination": {
          "type": "APP",
          "country_code": "US",
          "googleplay_app_id": "com.twitter.android"
        }
      }
    ],
    "created_at": "2020-11-11T05:42:25Z",
    "card_uri": "card://1326399865065238531",
    "updated_at": "2020-11-11T05:42:25Z",
    "deleted": false,
  }
}