X/Twitter Ads

Promote your posts by making them into X/Twitter ads using Ayrshare's API.

Take your posts to the next level by promoting them as ads using our X/Twitter promoted Tweets API. We currently only support Twitter Promoted Tweets. Additional social networks are coming soon.

Promoting Ads via an API

Promoting a Tweet turns a Tweet into an advertising campaign via the Promote a Tweet API. You can set a budget, target demographics, and more.

In the Twitter Ads Manager you'll create a campaign and ads groups. Tweets added to a group are "promoted" and will automatically run based on the settings of the campaign and group they are contained in.

You can create up to 100 ads groups in a campaign and 200 ads in an ads groups.

After you create the campaign and at least one ads group, you can use the API to promote Tweets. Any Tweet you posted to your account can be promoted, whether it came through Ayrshare or was manually posted.

After submitting the promoted Tweet, it might be in a "pending" state. This means that Twitter is reviewing the ad. Once approved the ad will run.

Activate Ads for X/Twitter

In the Ayrshare Dashboard, go to the Social Accounts page.

Click the "Activate Ads" to enable Twitter Promoted Ads.

Click to enable Promoted Tweets

Choose upgrade and your account will be enabled for promoting Tweets via the API.

Activated Promote Tweets

To deactivate ads, please contact us.

Set Up a Twitter Ads Campaign

The first step is to create a Twitter Ads campaign.

• Log in to Twitter with the handle you want to manage ads.

• Open the Twitter Ads Manager.

• In the upper left corner click "Create Campaign".

• Choose your objective from the selections and click "Next."

Choose Objective

• Complete the campaign settings, including setting a budget. The budget will be used to fund the ads. Click "Next".

Set up campaign

• Create an Ads Group, including a target audience. Click "Next".

Set Up Ads Group

• Once done, "Launch Campaign".

Promote Tweets API

There are three key pieces of information needed to promote a Twitter tweet via the API:

• Campaign ID

• Group ID

• Tweets IDs

/ads/twitter/campaigns

GET https://app.ayrshare.com/api/ads/twitter/campaigns

The list of Ad campaigns associated with your Twitter account. The campaigns field id contains the campaign ID. Note: Twitter sometimes refers to the campaign as the accounts.

Headers

Name	Type	Description
Authorizations	string	Format: Authorization: Bearer API_KEY. See Overview for more information.
Profile-Key	string	Profile Key of a user profile.

200 Return array of campaigns.

{
    "campaigns": [
        {
            "name": "Ayrshare",
            "business_name": null,
            "timezone": "America/New_York",
            "timezone_switch_at": "2020-11-10T05:00:00Z",
            "country_code": "US",
            "id": "18ca55appc1",
            "vat_status": "NOT_REQUIRED",
            "created_at": "2020-11-11T16:22:12Z",
            "updated_at": "2021-04-27T16:18:41Z",
            "industry_type": null,
            "business_id": null,
            "approval_status": "ACCEPTED",
            "deleted": false
        }
    ]
}

/ads/twitter/groups

GET https://app.ayrshare.com/api/ads/twitter/groups

The Ad Groups are the groupings under a given Campaign. The id of an array element is the key information need for the promote Tweet. Note: Twitter sometimes refers to groups as line items.

Path Parameters

Name	Type	Description
id	string	Campaign ID

Headers

Name	Type	Description
Authorization	string	Format: Authorization: Bearer API_KEY. See Overview for more information.
Profile-Key	string	Profile Key of a user profile.

200 Returns an array of groups. Field id for a given element in the array is required for promoting a Tweet.

{
    "id": "18ca55appc1",
    "groups": [
        {
            "advertiser_user_id": 912598959413241900,
            "name": "ad-group-1",
            "placements": [
                "TWITTER_TIMELINE"
            ],
            "start_time": null,
            "bid_amount_local_micro": 1500000,
            "automatically_select_bid": false,
            "advertiser_domain": null,
            "target_cpa_local_micro": null,
            "primary_web_event_tag": null,
            "goal": "LINK_CLICKS",
            "product_type": "PROMOTED_TWEETS",
            "end_time": null,
            "bid_strategy": "TARGET",
            "duration_in_days": null,
            "total_budget_amount_local_micro": null,
            "objective": "WEBSITE_CLICKS",
            "id": "it6bm",
            "entity_status": "ACTIVE",
            "automatic_tweet_promotion": null,
            "frequency_cap": null,
            "android_app_store_identifier": null,
            "categories": [],
            "currency": "USD",
            "pay_by": "LINK_CLICK",
            "created_at": "2021-02-19T23:49:29Z",
            "tracking_tags": [],
            "ios_app_store_identifier": null,
            "updated_at": "2021-02-19T23:56:47Z",
            "campaign_id": "f4o5v",
            "creative_source": "MANUAL",
            "deleted": false
        },
        {
            "advertiser_user_id": 915598958418221000,
            "name": "Social Media More Followers",
            "placements": [
                "ALL_ON_TWITTER"
            ],
            "start_time": null,
            "bid_amount_local_micro": 2250000,
            "automatically_select_bid": false,
            "advertiser_domain": null,
            "target_cpa_local_micro": null,
            "primary_web_event_tag": null,
            "goal": "FOLLOWERS",
            "product_type": "PROMOTED_ACCOUNT",
            "end_time": null,
            "bid_strategy": "TARGET",
            "duration_in_days": null,
            "total_budget_amount_local_micro": null,
            "objective": "FOLLOWERS",
            "id": "iucoy",
            "entity_status": "PAUSED",
            "automatic_tweet_promotion": null,
            "frequency_cap": null,
            "android_app_store_identifier": null,
            "categories": [],
            "currency": "USD",
            "pay_by": "FOLLOW",
            "created_at": "2021-02-25T20:01:14Z",
            "tracking_tags": [],
            "ios_app_store_identifier": null,
            "updated_at": "2021-04-27T16:18:41Z",
            "campaign_id": "f2cf2",
            "creative_source": "MANUAL",
            "deleted": false
        },
        {
            "advertiser_user_id": 915598979413291000,
            "name": "Ads Api Test Group Name",
            "placements": [
                "PUBLISHER_NETWORK",
                "ALL_ON_TWITTER"
            ],
            "start_time": null,
            "bid_amount_local_micro": null,
            "automatically_select_bid": true,
            "advertiser_domain": "ayrshare.com",
            "target_cpa_local_micro": null,
            "primary_web_event_tag": null,
            "goal": "LINK_CLICKS",
            "product_type": "PROMOTED_TWEETS",
            "end_time": null,
            "bid_strategy": "AUTO",
            "duration_in_days": null,
            "total_budget_amount_local_micro": null,
            "objective": "WEBSITE_CLICKS",
            "id": "j2gao",
            "entity_status": "PAUSED",
            "automatic_tweet_promotion": null,
            "frequency_cap": null,
            "android_app_store_identifier": null,
            "categories": [
                "IAB19"
            ],
            "currency": "USD",
            "pay_by": "LINK_CLICK",
            "created_at": "2021-03-31T01:50:19Z",
            "tracking_tags": [],
            "ios_app_store_identifier": null,
            "updated_at": "2021-03-31T02:07:20Z",
            "campaign_id": "fbpyf",
            "creative_source": "MANUAL",
            "deleted": false
        }
    ]
}

400

{
    "id": "18ca55appc1",
    "errors": {
        "action": "ads",
        "status": "error",
        "code": 208,
        "message": "Error getting Twitter Groups. Please check the parameters being sent."
    }
}

/ads/twitter/ids

PUT https://app.ayrshare.com/api/ads/twitter/ids

Set the "campaign" and "group" ids for a given profile. Used in /post for for automatic promoting.

Headers

Name	Type	Description
Authorization	string	Format: Authorization: Bearer API_KEY. See Overview for more information.
Profile-Key	string	Profile Key of a user profile.

Request Body

Name	Type	Description
campaign	string	Campaign ID for use in /post
group	string	Group ID for use in /group

200

{
    "status": "success"
}

{
    "campaign": "19ce59w5t0n",
    "group": "jpe9q"
}

/ads

POST https://app.ayrshare.com/ads

Promote existing Tweets by passing in a Campaign ID, Group ID, and a list of Tweet IDs. Tweets

Headers

Name	Type	Description
Authorization	string	Format: Authorization: Bearer API_KEY. See Overview for more information.
Profile-Key	string	Profile Key of a user profile.

Request Body

Name	Type	Description
ads	array	Array of Tweets to promote. See below for example format.

200

{
    "status": "success",
    "ads": [
        {
            "status": "success",
            "platform": "twitter",
            "ids": [
                "1286598420132356849"
            ],
            "ads": [
                {
                    "promotedTweetId": "6f1jas",
                    "tweetId": "1286598420132356849",
                    "approvalStatus": "ACCEPTED",
                    "entityStatus": "ACTIVE"
                }
            ]
        }
    ]
}

400

{
    "status": "error",
    "ads": [
        {
            "status": "error",
            "platform": "twitter",
            "ids": [
                "1386598427132366849"
            ],
            "result": {
                "action": "request",
                "status": "error",
                "code": 101,
                "message": "Twitter-Ads API Error: Line Item kl09J was not found for Account 18c055pl1co"
            }
        }
    ]
}

ads body parameter format:

{
    "ads": [
        {
            "platform": "twitter",
            "ids": ["1286598420132356849", "4286998420132356848"],
            "campaign": "18ce55allco",
            "group": "6f1jas"
        },
        {
            "platform": "twitter",
            "ids": ["5286998420232356849"],
            "campaign": "18ce55allco",
            "group": "6f1jas"
        }
    ]
}

Tweets can be sent either as individual array elements or listed in the ids field.

• platfrom: "twitter"

• ids: List of Tweet IDs. These can be obtained from the /post response - note, this is the Tweet ID and not the top level post ID. The Tweet does not need to have been sent from Ayrshare. You can use any Tweet you posted to your handle by grabbing from end digits from the Tweet URL: https://twitter.com/AyrShare/status/1384566731180494855

• campaign: CampaignID from /ads/twitter/campaigns

• group: Group ID from /ads/twitter/groups

/ads

DELETE https://app.ayrshare.com/api/ads

Delete promoted Tweets. Note, promoted tweets are technically "paused" and can be "activated" again via the Twitter Ads dashboard..

Headers

Name	Type	Description
Authorization	string	Format: Authorization: Bearer API_KEY. See Overview for more information.
Profile-Key	string	Profile Key of a user profile.

Request Body

Name	Type	Description
ads	string	Array of Tweets to delete. See below for example format.

200

{
    "status": "success",
    "ads": [
        {
            "status": "success",
            "platform": "twitter",
            "ids": [
                "6f0jds"
            ],
            "result": [
                {
                    "status": "success",
                    "id": "6f0jds",
                    "request": {
                        "params": {
                            "promoted_tweet_id": "6s0jes",
                            "account_id": "17ce35almao"
                        }
                    },
                    "data": {
                        "line_item_id": "g3gbo",
                        "id": "6s0jes",
                        "entity_status": "ACTIVE",
                        "created_at": "2021-04-26T22:06:25Z",
                        "updated_at": "2021-04-27T22:06:21Z",
                        "approval_status": "ACCEPTED",
                        "tweet_id": "1386598427132366849",
                        "deleted": true
                    }
                }
            ]
        }
    ]
}

400

{
    "status": "error",
    "ads": [
        {
            "status": "error",
            "platform": "twitter",
            "ids": [
                "6s0jes"
            ],
            "result": {
                "status": "error",
                "data": [
                    {
                        "status": "error",
                        "id": "6s0jes",
                        "action": "ads",
                        "code": 206,
                        "message": "Unable to delete ad. Please check your parameters or contact us. Twitter-Ads API Error: Account 18ce55allco1 was not found"
                    }
                ]
            }
        }
    ]
}

Delete Twitter ads you posted by specifying the follow ads body parameter:

{
    "ads": [
        {
            "platform": "twitter",
            "ids": ["6s0jes"],
            "campaign": "17ce35almao"
        }
    ]
}

Tweets can be deleted either as individual array elements or listed in the ids field.

• platfrom: "twitter"

• ids: List of Promoted Tweet IDs. These can be obtained from the POST /ads response.

• campaign: CampaignID from /ads/twitter/campaigns