Identifying Cards

Introduction

Cards are customizable ad formats that use media and that can be associated with a website, an app, or with calls to action to drive certain user engagements, such as starting a Direct Message. They can be appended to Tweets, Scheduled Tweets, or Draft Tweets.

Cards may be referenced in Tweet objects in one of two ways: by the card's card_uri or by its preview_url. Example values for each are presented below.

card_uri preview_url
card://1043282691834048513 https://cards.twitter.com/cards/18ce54d4x5t/68w3s

Note: As of Ads API version 3, only the card_uri is generated and returned in the cards response for newly created cards.

Note: As of Ads API version 4, the preview_url in the cards response is always null.

The type of reference in the Tweet object response will depend on the way the Tweet was created. In other words, if the Tweet was created using the card_uri request parameter, the card URI value will appear in the response. If the preview_url was included as part of the Tweet text, on the other hand, the preview URL will appear in the response.

Identifying Tweets with card_uri

For Tweets created using the card's URI value, the reference in the response depends on the endpoint being used. The following table compares the Ads API's GET accounts/:account_id/scoped_timeline endpoint and the Standard API's GET statuses/show endpoint.

Scoped Timeline Statuses Show*
card["url"] card_uri

* Same as GET statuses/lookup.

Below we show example responses for a single Tweet for both Scoped Timeline and Statuses Show. Note the differences in the location of the card URI value.

Scoped Timeline

$ twurl -H ads-api.twitter.com "/5/accounts/18ce54d4x5t/scoped_timeline?count=1&trim_user=true&scoped_to=none"


{
  "data": [
    {
      "created_at": "Sat Sep 22 17:23:07 +0000 2018",
      "id": 1043551275923591168,
      "id_str": "1043551275923591168",
      "text": "Tracking a card",
      "truncated": false,
      "entities": {
        "hashtags": [],
        "symbols": [],
        "user_mentions": [],
        "urls": []
      },
      "source": "Ads API Internal Test App",
      "in_reply_to_status_id": null,
      "in_reply_to_status_id_str": null,
      "in_reply_to_user_id": null,
      "in_reply_to_user_id_str": null,
      "in_reply_to_screen_name": null,
      "user": {
        "id": 756201191646691328,
        "id_str": "756201191646691328"
      },
      "geo": null,
      "coordinates": null,
      "place": null,
      "contributors": null,
      "retweet_count": 0,
      "favorite_count": 0,
      "favorited": false,
      "retweeted": false,
      "possibly_sensitive": false,
      "scopes": {
        "followers": false
      },
      "card": {
        "name": "promo_website",
        "url": "card://1043282691834048513",
        "card_type_url": "http://card-type-url-is-deprecated.invalid",
        "binding_values": {...}
      },
      "lang": "en"
    }
  ],
  "next_cursor": "AAAAAFvzt_YOxt5lhNTgAA",
  "request": {
    "params": {
      "trim_user": true,
      "count": 1,
      "scoped_to": "none",
      "account_id": "18ce54d4x5t"
    }
  }
}

Statuses Show

$ twurl -H api.twitter.com "/1.1/statuses/show.json?id=1043551275923591168&trim_user=true&include_card_uri=true"


{
  "created_at": "Sat Sep 22 17:23:07 +0000 2018",
  "id": 1043551275923591168,
  "id_str": "1043551275923591168",
  "text": "Tracking a card",
  "truncated": false,
  "entities": {
    "hashtags": [],
    "symbols": [],
    "user_mentions": [],
    "urls": []
  },
  "source": "Ads API Internal Test App",
  "in_reply_to_status_id": null,
  "in_reply_to_status_id_str": null,
  "in_reply_to_user_id": null,
  "in_reply_to_user_id_str": null,
  "in_reply_to_screen_name": null,
  "user": {
    "id": 756201191646691328,
    "id_str": "756201191646691328"
  },
  "geo": null,
  "coordinates": null,
  "place": null,
  "contributors": [
    2417045708
  ],
  "is_quote_status": false,
  "retweet_count": 0,
  "favorite_count": 0,
  "favorited": false,
  "retweeted": false,
  "scopes": {
    "followers": false
  },
  "lang": "en",
  "card_uri": "card://1043282691834048513"
}

When using the Standard API, use include_card_uri=true in the request. This will render a card_uri response attribute if and only if the card was associated with the Tweet using its URI value.

For scheduled and draft Tweet objects, the response will always include card_uri response attribute.

Identifying Tweets with preview_url

For Tweets created by including the preview URL as part of the Tweet's text, the URL can be found in entities["urls"][i]["expanded_url"] (the text field includes a shortened t.co URL), where i is an array index (a Tweet can contain multiple URLs). In cases where the Tweet text is greater than 140 characters, the preview URL will be found in the same location, but only if tweet_mode=extended is specified in the request.

For scheduled and draft Tweet objects, the preview URL will always appear in the text field.

Fetching cards

To retrieve additional information about a specific card, we provide two endpoints: GET accounts/:account_id/cards/all and GET accounts/:account_id/cards/all/:card_id. The former allows a card to be fetched by card_uri and the latter by the card's ID. The card's ID is found at the end of the preview_url. In the example above, the ID is 68w3s.