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.

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 5, the preview_url in the cards response is no longer returned.

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, find the reference to the card in the card_uri response attribute. The example response below uses the GET accounts/:account_id/tweets endpoint.

$ twurl -H ads-api.x.com "/9/accounts/18ce54d4x5t/tweets?trim_user=true&tweet_type=PUBLISHED&tweet_ids=1043551275923591168"
{
  "request": {
    "params": {
      "tweet_ids": [
        "1043551275923591168"
      ],
      "tweet_type": "PUBLISHED",
      "trim_user": true,
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "coordinates": null,
      "retweeted": false,
      "source": "Ads API Internal Test App",
      "entities": {
        "hashtags": [],
        "symbols": [],
        "user_mentions": [],
        "urls": []
      },
      "display_text_range": [
        0,
        15
      ],
      "favorite_count": 0,
      "in_reply_to_status_id_str": null,
      "geo": null,
      "id_str": "1043551275923591168",
      "scopes": {
        "followers": false
      },
      "in_reply_to_user_id": null,
      "truncated": false,
      "retweet_count": 0,
      "scheduled_status": null,
      "id": 1043551275923591168,
      "in_reply_to_status_id": null,
      "nullcast": true,
      "created_at": "Sat Sep 22 17:23:07 +0000 2018",
      "place": null,
      "scheduled_at": null,
      "tweet_type": "PUBLISHED",
      "favorited": false,
      "card_uri": "card://1043282691834048513",
      "full_text": "Tracking a card",
      "lang": "en",
      "contributors": [
        2417045708
      ],
      "in_reply_to_screen_name": null,
      "in_reply_to_user_id_str": null,
      "user": {
        "id": 756201191646691328,
        "id_str": "756201191646691328"
      },
      "tweet_id": "1043551275923591168"
    }
  ]
}

If using the Standard API, use include_card_uri=true in the request.

Regardless of which endpoint is used, the card_uri response attribute will only be rendered if the Tweet was created using a card URI.

For scheduled and draft Tweet objects, the response will always include the 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).

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.