Creatives

Video App Download Cards

Note: card_uri is replacing preview_url. This moves associating a card with a Tweet from the Tweet text to a Tweet parameter. To associate a card with a Tweet, use the card_uri parameter with either the POST accounts/:account_id/tweet, POST statuses/update, or POST accounts/:account_id/scheduled_tweets endpoints. This allows users to use more characters in their Tweets.

GET accounts/:account_id/cards/video_app_download

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

This card is part of our Mobile App Promotion product suite.

Resource URL

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

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_ids
optional

Scope the response to just the desired video app download cards by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: 5a4z3
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: twitter
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
with_total_count
optional

Include the total_count response attribute.

Note: This parameter will be ignored if cursor is specified.

Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes.

Type: boolean

Default: false
Possible values: true, false

Example Request

GET https://ads-api.twitter.com/4/accounts/18ce54d4x5t/cards/video_app_download?card_ids=5a4z3

Example Response

{
  "request": {
    "params": {
      "card_type": "video_app_download",
      "card_ids": [
        "5a4z3"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "name": "video app download",
      "googleplay_app_id": "com.twitter.android",
      "video_url": "https://video.twimg.com/amplify_video/vmap/958231855240589313.vmap",
      "video_owner_id": "756201191646691328",
      "video_content_id": "958231855240589313",
      "preview_url": null,
      "id": "5a4z3",
      "account_id": "18ce54d4x5t",
      "country_code": "US",
      "video_hls_url": "https://video.twimg.com/amplify_video/958231855240589313/pl/vHKJ2aH1tZGKW3bh.m3u8",
      "created_at": "2018-01-30T07:00:24Z",
      "card_uri": "card://958233417929261056",
      "updated_at": "2018-01-30T07:00:24Z",
      "video_poster_url": "https://pbs.twimg.com/amplify_video_thumb/958231855240589313/img/rjhswYG084qYYgF6.jpg",
      "app_cta": "INSTALL",
      "deleted": false,
      "card_type": "VIDEO_APP_DOWNLOAD"
    }
  ]
}

GET accounts/:account_id/cards/video_app_download/:card_id

Retrieve a specific video app download card associated with the current account.

This card is part of our Mobile App Promotion product suite.

Resource URL

https://ads-api.twitter.com/4/accounts/:account_id/cards/video_app_download/: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

A reference to the video app download card you are operating with in the request.

Type: string

Example: 5a4z3
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/4/accounts/18ce54d4x5t/cards/video_app_download/5a4z3

Example Response

{
  "request": {
    "params": {
      "card_type": "video_app_download",
      "card_id": "5a4z3",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "video app download",
    "googleplay_app_id": "com.twitter.android",
    "video_url": "https://video.twimg.com/amplify_video/vmap/958231855240589313.vmap",
    "video_owner_id": "756201191646691328",
    "video_content_id": "958231855240589313",
    "preview_url": null,
    "id": "5a4z3",
    "account_id": "18ce54d4x5t",
    "country_code": "US",
    "video_hls_url": "https://video.twimg.com/amplify_video/958231855240589313/pl/vHKJ2aH1tZGKW3bh.m3u8",
    "created_at": "2018-01-30T07:00:24Z",
    "card_uri": "card://958233417929261056",
    "updated_at": "2018-01-30T07:00:24Z",
    "video_poster_url": "https://pbs.twimg.com/amplify_video_thumb/958231855240589313/img/rjhswYG084qYYgF6.jpg",
    "app_cta": "INSTALL",
    "deleted": false,
    "card_type": "VIDEO_APP_DOWNLOAD"
  }
}

POST accounts/:account_id/cards/video_app_download

Create a new video app download card associated with the current account.

This card is part of our Mobile App Promotion product suite.

Resource URL

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

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
country_code
required

The two-letter ISO code for the country where the app is sold.

Type: string

Example: US
name
required

The name for the card.

Type: string

Example: video app download card
video_id
required

The identifier of a video from the GET accounts/:account_id/media_library endpoint to be included in the card.

Note: An aspect ratio of either 16:9 or 1:1 is required.

Type: string

Example: 13_958231855240589313
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).

Note: This can be retrieved from the Apple App Store URL.

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.

Note: This can be retrieved from the Apple App Store URL.

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
app_cta
optional

The Call-To-Action (CTA) text for the card button.

Type: enum

Possible values: BOOK, CONNECT, INSTALL, OPEN, ORDER, PLAY, SHOP
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 a googleplay_app_id has been provided.

Type: string
image_media_id
optional

Specify a poster image for the video using the media_id of an uploaded image. If not specified, the first frame will be used.

This is a write-only field. In the response, the API will provide a Twitter URL for this image.

Type: long

Example: 882726458191298561

Example Request

POST https://ads-api.twitter.com/3/accounts/18ce54d4x5t/cards/video_app_download?country_code=US&name=video app download&video_id=13_958231855240589313&googleplay_app_id=com.twitter.android

Example Response

{
  "data": {
    "name": "video app download",
    "googleplay_app_id": "com.twitter.android",
    "video_url": "https://video.twimg.com/amplify_video/vmap/958231855240589313.vmap",
    "video_owner_id": "756201191646691328",
    "video_content_id": "958231855240589313",
    "preview_url": null,
    "id": "5a4z3",
    "account_id": "18ce54d4x5t",
    "country_code": "US",
    "video_hls_url": "https://video.twimg.com/amplify_video/958231855240589313/pl/vHKJ2aH1tZGKW3bh.m3u8",
    "created_at": "2018-01-30T07:00:24Z",
    "card_uri": "card://958233417929261056",
    "updated_at": "2018-01-30T07:00:24Z",
    "video_poster_url": "https://pbs.twimg.com/amplify_video_thumb/958231855240589313/img/rjhswYG084qYYgF6.jpg",
    "app_cta": "INSTALL",
    "deleted": false,
    "card_type": "VIDEO_APP_DOWNLOAD"
  },
  "request": {
    "params": {
      "name": "video app download",
      "googleplay_app_id": "com.twitter.android",
      "video_id": "13_958231855240589313",
      "video_url": "https://video.twimg.com/amplify_video/vmap/958231855240589313.vmap",
      "video_stream_content_type": "video/mp4; codecs="avc1.42E01E, mp4a.40.2"",
      "video_owner_id": "756201191646691328",
      "video_content_id": "958231855240589313",
      "account_id": "18ce54d4x5t",
      "country_code": "US",
      "video_hls_url": "https://video.twimg.com/amplify_video/958231855240589313/pl/vHKJ2aH1tZGKW3bh.m3u8",
      "video_poster_url": "https://pbs.twimg.com/amplify_video_thumb/958231855240589313/img/rjhswYG084qYYgF6.jpg",
      "app_cta": "INSTALL",
      "card_type": "VIDEO_APP_DOWNLOAD"
    }
  }
}

PUT accounts/:account_id/cards/video_app_download/:card_id

Update the specified video app download card belonging to the current account.

This card is part of our Mobile App Promotion product suite.

Resource URL

https://ads-api.twitter.com/4/accounts/:account_id/cards/video_app_download/: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

A reference to the video app download card you are operating with in the request.

Type: string

Example: 5a4z3
country_code
optional

The two-letter ISO code for the country where the app is sold.

Type: string

Example: US
app_cta
optional

The Call-To-Action (CTA) text for the card button.

Type: enum

Possible values: BOOK, CONNECT, INSTALL, OPEN, ORDER, PLAY, SHOP
ipad_app_id
optional

The iPad app ID.

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

Note: When the iphone_app_id is specified and this is not, the iPhone app value will be set.

Note: This can be retrieved from the Apple App Store URL.

Type: long

Example: 333903271
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 the iphone_deep_link is specified and this is not, the iPhone deep link value will be set.

Type: string
iphone_app_id
optional

The iPhone app ID.

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

Note: This can be retrieved from the Apple App Store URL.

Type: long

Example: 333903271
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_app_id
optional

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
googleplay_deep_link
optional

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

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

Type: string
image_media_id
optional

Specify a poster image for the video using the media_id of an uploaded image. If not specified, the first frame will be used.

This is a write-only field. In the response, the API will provide a Twitter URL for this image.

Type: long

Example: 882726458191298561
name
optional

The name for the card.

Type: string

Example: aerial card
video_id
optional

The identifier of a video from the GET accounts/:account_id/media_library endpoint to be included in the card.

Note: An aspect ratio of either 16:9 or 1:1 is required.

Type: string

Example: 13_958231855240589313

Example Request

PUT https://ads-api.twitter.com/4/accounts/18ce54d4x5t/cards/video_app_download/5a4z3?name=aerial card

Example Response

{
  "data": {
    "name": "aerial card",
    "video_url": "https://video.twimg.com/amplify_video/vmap/958231855240589313.vmap",
    "video_owner_id": "756201191646691328",
    "video_content_id": "958231855240589313",
    "preview_url": null,
    "id": "5a4z3",
    "account_id": "18ce54d4x5t",
    "video_hls_url": "https://video.twimg.com/amplify_video/958231855240589313/pl/vHKJ2aH1tZGKW3bh.m3u8",
    "created_at": "2018-01-30T07:00:24Z",
    "card_uri": "card://958233417929261056",
    "updated_at": "2018-01-30T07:32:00Z",
    "video_poster_url": "https://pbs.twimg.com/amplify_video_thumb/958231855240589313/img/rjhswYG084qYYgF6.jpg",
    "app_cta": "install",
    "deleted": false,
    "card_type": "VIDEO_APP_DOWNLOAD"
  },
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "card_type": "VIDEO_APP_DOWNLOAD",
      "card_id": "5a4z3",
      "name": "aerial card"
    }
  }
}

DELETE accounts/:account_id/cards/video_app_download/:card_id

Permanently delete the specified video app download card belonging to the current account.

Note: This is a hard delete. As a result, it is not possible to retrieve deleted cards.

This card is part of our Mobile App Promotion product suite.

Resource URL

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

A reference to the video app download card you are operating with in the request.

Type: string

Example: 4hug6

Example Request

DELETE https://ads-api.twitter.com/4/accounts/18ce54d4x5t/cards/video_app_download/4hug6

Example Response

{
  "data": {
    "name": "video app download",
    "id": "4hug6",
    "account_id": "18ce54d4x5t",
    "created_at": "2017-07-05T23:01:42Z",
    "updated_at": "2017-08-23T13:21:40Z",
    "deleted": true,
    "card_type": "VIDEO_APP_DOWNLOAD"
  },
  "request": {
    "params": {
      "card_id": "4hug6",
      "card_type": "video_app_download",
      "account_id": "18ce54d4x5t"
    }
  }
}