Ads

Promote your posts by making them into ads.
Take your or your users' posts to the next level my promoting them as ads. We currently only support Twitter Promoted Tweets, but additional networks are coming soon.
How It Works
Promoting a Tweet is making an advertising campaign out of an existing Tweet. You can set up 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. Twitter is reviewing the ad and once approved it will run.
Set Up a Twitter Ads Campaign
The first step is to create a Twitter Ads campaign.
Login 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 tweet:
Campaign ID
Group ID
Tweets IDs
get
/ads/twitter/campaigns
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: The campaign is sometimes referred to as the accounts.
Request
Response
Request
Headers
Authorizations
required
string
Format: Authorization: Bearer API_KEY. See Overview for more information.
Response
200: OK
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
        }
    ]
}
get
/ads/twitter/groups
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: groups is sometimes referred to as line items.
Request
Response
Request
Path Parameters
id
required
string
Campaign ID
Headers
Authorization
required
string
Format: Authorization: Bearer API_KEY. See Overview for more information.
Response
200: OK
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: Bad Request
{
    "id": "18ca55appc1",
    "errors": {
        "action": "ads",
        "status": "error",
        "code": 208,
        "message": "Error getting Twitter Groups. Please check the parameters being sent."
    }
}
put
/ads/twitter/ids
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.
Request
Response
Request
Headers
Authorization
required
string
Format: Authorization: Bearer API_KEY. See Overview for more information.
Body Parameters
campaign
required
string
Campaign ID for use in /post
group
required
string
Group ID for use in /group
Response
200: OK
{
    "status": "success"
}
{
    "campaign": "19ce59w5t0n",
    "group": "jpe9q"
}
post
/ads
https://app.ayrshare.com/ads
Promote  existing Tweets by passing in a Campaign ID, Group ID, and a list of Tweet IDs. Tweets
Request
Response
Request
Headers
Authorization
required
string
Format: Authorization: Bearer API_KEY. See Overview for more information.
Body Parameters
ads
required
array
Array of Tweets to promote. See below for example format.
Response
200: OK
{
    "status": "success",
    "ads": [
        {
            "status": "success",
            "platform": "twitter",
            "ids": [
                "1286598420132356849"
            ],
            "ads": [
                {
                    "promotedTweetId": "6f1jas",
                    "tweetId": "1286598420132356849",
                    "approvalStatus": "ACCEPTED",
                    "entityStatus": "ACTIVE"
                }
            ]
        }
    ]
}
400: Bad Request
{
    "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
delete
/ads
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.. 
Request
Response
Request
Headers
Authorization
required
string
Format: Authorization: Bearer API_KEY. See Overview for more information.
Body Parameters
ads
required
string
Array of Tweets to delete. See below for example format.
Response
200: OK
{
    "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: Bad Request
{
    "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"
                    }
                ]
            }
        }
    ]
}
ads body parameter format:
{
    "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