promotable-users

Promotable Users

GET accounts/:account_id/promotable_users¶

Retrieve details for some or all promotable users associated with the current account.

The promotable user type is either FULL or RETWEETS_ONLY. This controls the type of content that is allowed to be promoted by the account. Advertisers must obtain permission to promote another user's content and contact Twitter to get them added to your account as a RETWEETS_ONLY promotable user.

Provided the permissions are set correctly, you can make requests to the promoted product endpoints that directly reference the Tweet ID of the Tweet you'd like to promote. You can use the POST accounts/:account_id/promoted-tweets endpoint to promote published Tweets and the POST accounts/:account_id/scheduled-promoted-tweets endpoint to promote another Twitter Ads account's Scheduled Tweets.

You do not have to retweet the target Tweet. When you promote a Tweet with this approach, the tweet_id that is returned will be different from the Tweet ID that was provided. Behind the scenes, the Tweet is being retweeted as a nullcasted Tweet and then promoted. The tweet_id that is returned corresponds to this new Tweet.

Resource URL¶

https://ads-api.twitter.com/12/accounts/:account_id/promotable_users

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`
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`
promotable_user_ids optional	Scope the response to just the desired promotable users by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: `l310s`
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 and `cursor` are exclusive. 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/12/accounts/18ce54d4x5t/promotable_users?promotable_user_ids=l310s

Example Response¶

{
  "request": {
    "params": {
      "promotable_user_ids": [
        "l310s"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "user_id": "756201191646691328",
      "id": "l310s",
      "created_at": "2016-07-21T22:42:09Z",
      "updated_at": "2016-07-21T22:42:09Z",
      "deleted": false,
      "promotable_user_type": "FULL"
    }
  ]
}

GET accounts/:account_id/promotable_users/:promotable_user_id¶

Retrieve a specific promotable user associated with the current account.

The promotable user type is either FULL or RETWEETS_ONLY. This controls the type of content that is allowed to be promoted by the account.

Advertisers must obtain permission to promote another user's content. Provided the permissions are set correctly, you can make requests to the promoted product endpoints that directly reference the Tweet ID of the Tweet you'd like to promote.

Resource URL¶

https://ads-api.twitter.com/12/accounts/:account_id/promotable_users/:promotable_user_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

promotable_user_id
optional

A reference to the promotable user you are operating on within the request

Type: string

Example: l310s

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/12/accounts/18ce54d4x5t/promotable_users/l310s

Example Response¶

{
  "request": {
    "params": {
      "promotable_user_id": "l310s",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "user_id": "2417045708",
    "id": "l310s",
    "created_at": "2017-03-10T17:51:24Z",
    "updated_at": "2017-03-10T17:51:24Z",
    "deleted": false,
    "promotable_user_type": "RETWEETS_ONLY"
  }
}