cards

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.x.com/12/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`
card_types optional	Scope the response to just the desired card types by specifying a comma-separated list of enum values. Type: enum Possible values: `IMAGE_APP`, `IMAGE_CAROUSEL_APP`, `IMAGE_CAROUSEL_WEBSITE`, `IMAGE_MULTI_DEST_CAROUSEL_WEBSITE`, `IMAGE_WEBSITE`, `MIXED_MEDIA_MULTI_DEST_CAROUSEL_WEBSITE`, `MIXED_MEDIA_SINGLE_DEST_CAROUSEL_APP`, `MIXED_MEDIA_SINGLE_DEST_CAROUSEL_WEBSITE`, `VIDEO_APP`, `VIDEO_CAROUSEL_APP`, `VIDEO_CAROUSEL_WEBSITE`, `VIDEO_MULTI_DEST_CAROUSEL_WEBSITE`, `VIDEO_WEBSITE`
card_id optional	Scope the response to just the desired cards by specifying a comma-separated list of identifiers. Up to 200 card IDs may be provided. Type: string Example: `1044294149527166979,1044301099031658496`
card_uris optional	Scope the response to just the desired cards by specifying a comma-separated list of identifiers. Up to 200 card URI values may be provided. Type: string Example: `card://1044294149527166979,card://1044301099031658496`
count optional	Specifies the number of records to try and retrieve per distinct request. Type: int Default: `100` Min, Max: `1`, `200`
cursor optional	Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: `8x7v00oow`
include_legacy_cards optional	Include legacy website and app cards in the response. Legacy cards are those whose resource URL has the following format: accounts/:account_id/cards/:card_type. See this developer forum post for additional context. Type: boolean Default: `false` Possible values: `true`, `false`
q optional	An optional query to scope cards by `name`. Omit this parameter to retrieve all. Maximum length: 80 characters. Note: This performs case-insensitive prefix matching. 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.x.com/12/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",
      "id": "1321554298900107264",
      "updated_at": "2020-10-28T20:47:52Z",
      "deleted": false,
      "card_type": "IMAGE_CAROUSEL_APP"
    }
  ]
}

GET accounts/:account_id/cards/:card_id¶

Retrieve details for a single card associated with the current account.

Resource URL¶

https://ads-api.x.com/12/accounts/:account_id/cards/:card_id

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

card_id
required

The id of the cards.

Type: string

Example: 1044294149527166979

with_deleted
optional

Include deleted results in your request.

Type: boolean

Default: false
Possible values: true, false

Example Request¶

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/1321554298900107264

Example Response¶

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "card_id": "1321554298900107264"
    }
  },
  "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",
      "id": "1321554298900107264",
      "updated_at": "2020-10-28T20:47:52Z",
      "deleted": false,
      "card_type": "IMAGE_CAROUSEL_APP"
    }
  ]
}

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.x.com/12/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`
name required	The name for the card. Maximum length: 80 characters. Type: string Example: `component based card`
components sometimes required	Describes the components to use to create the card. Additional information below. Cannot be specified along with `slides`. Note: The order of the components is important. Type: array of objects
slides sometimes required	Use this array of array to create Multi-Destination Carousels. Describes each card as a grouping of components. Each slide should be a complete representation of a card. Cannot be specified along with `components`. Note: The order of each slide is important. Type: array of array

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

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`

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`
googleplay_app_id sometimes required	The Google Play application package name. Note: At least one of following is required: `ios_app_store_identifier` or `googleplay_app_id`. Type: string Example: `com.twitter.android`
ios_app_store_identifier sometimes required	The iOS app store identifier. Note: At least one of following is required: `ios_app_store_identifier` or `googleplay_app_id`. Type: string Example: `333903271`
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
ios_deep_link optional	A deep link into the iOS app you're promoting. Note: Can only be used if an `ios_app_store_identifier` has been provided. Type: string

Example Request¶

POST https://ads-api.x.com/12/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",
    "id": "1321554298900107264",
    "updated_at": "2020-11-11T05:42:25Z",
    "deleted": false,
    "card_type": "IMAGE_APP"
  }
}

PUT accounts/:account_id/cards/:card_id¶

Update the specified associated with the current account.

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

Resource URL¶

https://ads-api.x.com/12/accounts/:account_id/cards/1321554298900107264

Parameters¶

The JSON POST body must include the parameters that will be updated. The request will replace each field with the parameters specified within the payload. 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 and slides in POST accounts/:account_id/cards.

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`
name optional	The name for the card. Maximum length: 80 characters. Type: string Example: `component based card`
components optional	Describes the components to use to update the card. Additional information below. Cannot be specified along with `slides`. Note: The order of the components is important. Type: array of objects
slides optional	Use this array of array to update Multi-Destination Carousels. Describes each card as a grouping of components. Each slide should be a complete representation of a card. Cannot be specified along with `components`. Note: The order of each slide is important. Type: array of array

Example Request¶

This example updates both the name and removes one of the media_keys from the components field from the example above.

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/1321554298900107264

{
  "name": "changed name",
  "components": [
    {
      "type": "SWIPEABLE_MEDIA",
      "media_keys": [
        "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"
      }
    }
  ]
}

Example Response¶

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "card_id": "1321554298900107264"
    }
  },
  "data": [
    {
      "name": "changed name",
      "components": [
        {
          "type": "SWIPEABLE_MEDIA",
          "media_keys": [
            "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",
      "id": "1321554298900107264",
      "updated_at": "2020-10-29T20:47:52Z",
      "deleted": false,
      "card_type": "IMAGE_CAROUSEL_APP"
    }
  ]
}

DELETE accounts/:account_id/cards/:card_id¶

Delete the specified card belonging to the current account.

Resource URL¶

https://ads-api.x.com/12/accounts/:account_id/cards/:card_id

Parameters¶

Name Description

account_id
required

Type: string

Example: 18ce54d4x5t

card_id
required

The id of the card to be deleted.

Type: string

Example: 1044294149527166979

Example Request¶

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/1321554298900107264

Example Response¶

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "card_id": "1321554298900107264"
    }
  },
  "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",
      "id": "1321554298900107264",
      "updated_at": "2020-10-29T20:47:52Z",
      "deleted": true,
      "card_type": "IMAGE_CAROUSEL_APP"
    }
  ]
}