Creatives
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: |
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: |
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: |
q optional |
An optional query to scope cards by Note: This performs case-insensitive prefix matching. Type: string Example: |
sort_by optional |
Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: |
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: |
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: |
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 imageSWIPEABLE_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: |
url required |
The URL of the website to redirect a user to. Type: string Example: |
App Destination
Name | Description |
---|---|
type required |
The destination type, which determines its schema. Type: enum Possible values: |
country_code required |
The ISO 3166-1 alpha-2 two-letter code for the country where the app is sold. Type: string Example: |
ipad_app_id sometimes required |
The iPad app ID. Note: At least one of following is required: Note: When not specified, this will be set to to the Type: long Example: |
iphone_app_id sometimes required |
The iPhone app ID. Note: At least one of following is required: Type: long Example: |
googleplay_app_id sometimes required |
The Google Play application package name. Note: At least one of following is required: Type: string Example: |
ipad_deep_link optional |
A deep link into the iPad app you're promoting. Note: Can only be used if an Note: When not specified, this will be set to to the Type: string |
iphone_deep_link optional |
A deep link into the iPhone app you're promoting. Note: Can only be used if an Type: string |
googleplay_deep_link optional |
A deep link into the Android app you're promoting. Note: Can only be used if an 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"
}
}