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/8/accounts/:account_id/cards

Parameters

Name Description
account_id
required

The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t

count
optional

Specifies the number of records to try and retrieve per distinct request.

Type: int

Default: 200
Min, Max: 1, 1000
cursor
optional

Specifies a cursor to get the next page of results. See Pagination for more information.

Type: string

Example: 8x7v00oow

q
optional

An optional query to scope cards by name. Omit this parameter to retrieve all. Maximum length: 80 characters.

Type: string

Example: dtc

sort_by
optional

Sorts by supported attribute in ascending or descending order. See Sorting for more information.

Type: string

Example: created_at-asc

with_deleted
optional

Include deleted results in your request.

Type: boolean

Default: false
Possible values: true, false

Example Request

GET https://ads-api.twitter.com/8/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"
          }
        }
      ],
      "id": "ang2x",
      "created_at": "2020-10-28T20:47:52Z",
      "card_uri": "card://1321554298900107264",
      "updated_at": "2020-10-28T20:47:52Z",
      "deleted": false,
      "card_type": "UNIFIED"
    }
  ]
}

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/8/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.

Name Description
account_id
required

The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t

components
required

Describes the components to use to create the card. Additional information below.

Note: The order of the components is important.

Type: array of objects

name
required

The name for the card. Maximum length: 80 characters.

Type: string

Example: component based card

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.

Component type Field Value type
MEDIA media_key string
SWIPEABLE_MEDIA media_keys array of strings
DETAILS title
destination
string
object
BUTTON label
destination
object
object

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
Name Description
type
required

The destination type, which determines its schema.

Type: enum

Possible values: WEBSITE

url
required

The URL of the website to redirect a user to.

Type: string

Example: https://twittercommunity.com/c/advertiser-api

App Destination
Name Description
type
required

The destination type, which determines its schema.

Type: enum

Possible values: APP

country_code
required

The ISO 3166-1 alpha-2 two-letter code for the country where the app is sold.

Type: string

Example: US

ipad_app_id
sometimes required

The iPad app ID.

Note: At least one of following is required: ipad_app_id, iphone_app_id, or googleplay_app_id.

Note: When not specified, this will be set to to the iphone_app_id value (if provided).

Type: long

Example: 333903271

iphone_app_id
sometimes required

The iPhone app ID.

Note: At least one of following is required: ipad_app_id, iphone_app_id, or googleplay_app_id.

Type: long

Example: 333903271

googleplay_app_id
sometimes required

The Google Play application package name.

Note: At least one of following is required: ipad_app_id, iphone_app_id, or googleplay_app_id.

Type: string

Example: com.twitter.android

ipad_deep_link
optional

A deep link into the iPad app you're promoting.

Note: Can only be used if an ipad_app_id has been provided.

Note: When not specified, this will be set to to the iphone_deep_link value (if provided).

Type: string

iphone_deep_link
optional

A deep link into the iPhone app you're promoting.

Note: Can only be used if an iphone_app_id has been provided.

Type: string

googleplay_deep_link
optional

A deep link into the Android app you're promoting.

Note: Can only be used if an googleplay_app_id has been provided.

Type: string

Example Request

POST https://ads-api.twitter.com/8/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"
        }
      }
    ],
    "id": "arr4y",
    "created_at": "2020-11-11T05:42:25Z",
    "card_uri": "card://1326399865065238531",
    "updated_at": "2020-11-11T05:42:25Z",
    "deleted": false,
    "card_type": "UNIFIED"
  }
}

Was this document helpful?

Thank you

Thank you for the feedback. We’re really glad we could help!

Thank you for the feedback. How could we improve this document?

Thank you for the feedback. Your comments will help us improve our documents in the future.