post
Post to social networks and set an auto-post schedule. Please see our Packages if you use Node.js, Python, Bubble.io, or Airtable.
Click the β€Ί in the endpoint to view details.
post
https://app.ayrshare.com/api
/post
Send a Post

Request Examples

cURL
Node.js
Python
PHP
Go
C#
1
curl \
2
-H "Authorization: Bearer API_KEY" \
3
-H 'Content-Type: application/json' \
4
-d '{"post": "Today is a great day!", "platforms": ["twitter", "facebook", "fbg", "instagram", "linkedin"], "mediaUrls": ["https://images.ayrshare.com/imgs/GhostBusters.jpg"]}' \
5
-X POST https://app.ayrshare.com/api/post
Copied!
1
const fetch = require("node-fetch");
2
const API_KEY = "API_KEY";
3
​
4
fetch("https://app.ayrshare.com/api/post", {
5
method: "POST",
6
headers: {
7
"Content-Type": "application/json",
8
"Authorization": `Bearer ${API_KEY}`
9
},
10
body: JSON.stringify({
11
post: "Today is a great day!", // required
12
platforms: ["twitter", "facebook", "fbg", "instagram", "linkedin"], // required
13
mediaUrls: ["https://images.ayrshare.com/imgs/GhostBusters.jpg"], //optional
14
}),
15
})
16
.then((res) => res.json())
17
.then((json) => console.log(json))
18
.catch(console.error);
Copied!
1
import requests
2
​
3
payload = {'post': 'Today is a great day!',
4
'platforms': ['twitter', 'facebook', 'fbg', 'instagram', 'linkedin'],
5
'mediaUrls': ['https://images.ayrshare.com/imgs/GhostBusters.jpg']}
6
headers = {'Content-Type': 'application/json',
7
'Authorization': 'Bearer API_KEY'}
8
​
9
r = requests.post('https://app.ayrshare.com/api/post',
10
json=payload,
11
headers=headers)
12
13
print(r.json())
Copied!
1
<?php
2
require 'vendor/autoload.php'; // Composer auto-loader
3
​
4
$client = new GuzzleHttp\Client(); // Use the HTTP library of your choice
5
$res = $client->request(
6
'POST',
7
'https://app.ayrshare.com/api/post',
8
[
9
'headers' => [
10
'Content-Type' => 'application/json',
11
'Authorization' => 'Bearer API_KEY'
12
],
13
'json' => [
14
'post' => 'Today is a great day!', // required
15
'platforms' => ['twitter', 'facebook', 'fbg', 'instagram', 'linkedin'], // required
16
'mediaUrls' => ['https://images.ayrshare.com/imgs/GhostBusters.jpg'], // optional
17
]
18
]
19
);
20
​
21
echo json_encode(json_decode($res->getBody()), JSON_PRETTY_PRINT);
Copied!
1
package main
2
​
3
import (
4
"bytes"
5
"encoding/json"
6
"log"
7
"net/http"
8
)
9
​
10
func main() {
11
message := map[string]interface{}{
12
"post": "Today is a great day!",
13
"platforms": []string{"twitter", "facebook", "fbg", "instagram", "linkedin"},
14
"mediaUrls": []string{"https://images.ayrshare.com/imgs/GhostBusters.jpg"}
15
}
16
​
17
bytesRepresentation, err := json.Marshal(message)
18
if err != nil {
19
log.Fatalln(err)
20
}
21
​
22
req, _ := http.NewRequest("POST", "https://app.ayrshare.com/api/post",
23
bytes.NewBuffer(bytesRepresentation))
24
​
25
req.Header.Add("Content-Type", "application/json; charset=UTF-8")
26
req.Header.Add("Authorization", "Bearer API_KEY")
27
​
28
res, err := http.DefaultClient.Do(req)
29
if err != nil {
30
log.Fatal("Error:", err)
31
}
32
​
33
res.Body.Close()
34
}
Copied!
1
using System;
2
using System.Net;
3
using System.IO;
4
​
5
namespace PostPOSTRequest_charp
6
{
7
class Post
8
{
9
static void Main(string[] args)
10
{
11
string API_KEY = "API_KEY";
12
string url = "https://app.ayrshare.com/api/post";
13
​
14
var httpWebRequest = WebRequest.CreateHttp(url);
15
httpWebRequest.ContentType = "application/json";
16
httpWebRequest.Method = "POST";
17
httpWebRequest.Headers.Add("Authorization", "Bearer " + API_KEY);
18
​
19
using (var streamWriter = new StreamWriter(httpWebRequest.GetRequestStream()))
20
{
21
string json = "{\"post\" : \"Today is a great day!\","
22
+ "\"platforms\" : [ \"twitter\", \"facebook\", \"fbg\", \"instagram\", \"linkedin\" ],"
23
+ "\"mediaUrls\" : [ \"https://images.ayrshare.com/imgs/GhostBusters.jpg\" ]}";
24
​
25
streamWriter.Write(json);
26
streamWriter.Flush();
27
}
28
​
29
var httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();
30
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
31
{
32
var response = streamReader.ReadToEnd();
33
Console.WriteLine(response);
34
}
35
}
36
}
37
}
Copied!

Additional Endpoint Examples

Instagram

Post images or videos directly to Instagram.
Instagram has the following requirements and restrictions:
    Business Instagram Account connected with a Facebook Page - see here.
    Only 25 Instagram posts are allowed over a 24 hour period - around 750 posts a month. See below for usedQuota
    The post text may contain up to 30 hashtags (e.g. #wildtimes) and 20 username mentions (e.g. @natgeo).
    @Mentioned Instagram users will receive a notification.
    Maximum 2,200 post characters, 30 hashtags, and 20 @ tags.
    Multi-image posts are not supported.
    Delete not supported using the /delete endpoint.
Note: The aspect ratio of images & videos and the duration of video are very important to successfully post to Instagram. If they do not meet the requirements, the post will be rejected.
Please see the Instagram section of Image and Video Guidelines:
​

Instagram Business Account

Your Instagram account must be a Business Account and connected with a Facebook Page. The setup is free and easy.
See here for detailed instructions:
​

Additional Post Parameters - User Tags & Location, Instagram Auto Image Resize

User Tags & Locations
The Instagram user will be notified when you use their username in a post. Please be cautious to not spam users or post with their username repeatedly. If you do, Instagram will suspend or deactivate your account.
An image can be tagged with Instagram users and images/videos can be tagged with a location, for a given Facebook Page Id, using the instagramOptions parameter.
In the following example, a location is specified by a locationId, which is a Facebook Page Id of the Guggenheim Museum.
Users are specified by a userTags containing an Array of objects with an Instagram username and x/y coordinates on the image.
    Usernames must be public Instagram accounts.
    x and y values must be float numbers that originate from the top-left of the image, with a range of 0.0–1.0.
Instagram Auto Image Resize
Enterprise Plans required.
Images are automatically resized to 1080 x 1080 px to work with Instagram with the autoResize parameter.
1
{
2
"post": "Let it go!",
3
"platforms": [
4
"instagram"
5
],
6
"mediaUrls": [
7
"https://images.ayrshare.com/imgs/GhostBusters.jpg"
8
],
9
"instagramOptions": {
10
"autoResize": true,
11
"locationId": 7640348500,
12
"userTags": [
13
{
14
"username": "ayrshare",
15
"x": 0.5,
16
"y": 0.5
17
},
18
{
19
"username": "ayrshare",
20
"x": 0.3,
21
"y": 0.2
22
}
23
]
24
}
25
}
Copied!

Post Response

The Instagram response will include the current usedQuota for the number of Instagram posts done over a rolling 24-hours period. Only 25 Instagram posts are permitted by Instagram in a 24-rolling-hour period.
1
{
2
"status": "success",
3
"errors": [],
4
"postIds": [
5
{
6
"status": "success",
7
"id": "17823977408036085",
8
"usedQuota": 15,
9
"platform": "instagram"
10
}
11
],
12
"id": "l4FaPHSXWJNdmMfm3dIE"
13
}
Copied!
If the quota has been reached, an error message will be returned.

Facebook Pages

Post Facebook Carousel images through Ayrshare's API with the carousel body parameter.
1
{
2
"faceBookOptions": {
3
"carousel": {
4
"link": "URL of See More At...",
5
"items": [
6
{
7
"name": "Image name",
8
"link": "URL when image clicked",
9
"picture": "URL of image"
10
},
11
{
12
"name": "Image name",
13
"link": "URL when image clicked",
14
"picture": "URL of image"
15
}
16
]
17
}
18
}
19
}
Copied!
The top-level link parameter is the URL at the end of the carousel.
The items is an array of object containing the picture URL, link URL when the image is clicked, and name of the image displayed in each image card. At least two object must be present in the items array.
Note: Do not use the media_urls with carousel. If media_urls is used, carousels will be ignored.
Please see our Facebook Carousel Blog Post for more information.

Facebook Media Captions

Set a caption for each Facebook media image posted.
Accepts an array of string caption text. Each array must correspond to a media url. E.g. ["This is my best pic", "πŸ˜ƒ here is the next one"] refers to the 1st and 2nd urls in mediaUrls.
1
{
2
"faceBookOptions": {
3
"mediaCaptions": ["This is my best pic", "πŸ˜ƒ here is the next one"]
4
}
5
}
Copied!

Facebook Video Thumbnail

Set a thumbnail for a video. Send a remote URL of a PNG or JPG file that is the same dimensions as the video and less than 10 MB. URL should end in .png or .jpg.
1
{
2
"faceBookOptions": {
3
"thumbNail": "https://octodex.github.com/images/Fintechtocat.png"
4
}
5
}
Copied!

Facebook Page Mentions

You can mention another Facebook Page by including the following in the post text. Note, Premium or Business Plan required for mentions.
@[page-id]
An example post text: "This is the best post by @[109905187950644]".
The Facebook Page ID will resolve to the matching page and notify the other Page of mention.
Use Page mentioning with caution by only mentioning Pages you are associated with and never spam.
When you mention a Page, the owner of the Page will be notified. If several Pages complain about you mentioning them, Facebook could possibly ban your account.
The Facebook Page being mentioned must have allow other Pages to mention enabled in the Page settings.
To find your own Page ID:
    1.
    From News Feed, click Pages in the left side menu.
    2.
    Click your Page name to go to your Page.
    3.
    Click About at the top of your Page. If you don't see it, click More
    .
    4.
    Scroll down to find your Page ID below MORE INFO.
or if you want to find the ID of a page your don't own:
    If the Facebook Page has a URL such ashttps://www.facebook.com/ayrshare-1234567890 then the ID is 1234567890.
    If the Facebook Page has a URL such as:
    https://www.facebook.com/pages/ayrshare/123466789203 then the Page ID is the number at the end, such as 123466789203.
You can test that the Page ID is correct by going to https://facebook.com/page-id and it will resolve to the Page.
You can also try a 3rd party Facebook Page look up tool such as: https://lookup-id.com/​

Facebook Groups

Facebook Groups requires the Facebook Ayrshare App to be enabled for the Group. Please see here for instructions:

YouTube

YouTube posting requires your YouTube account to have at least one Channel. To create a YouTube Channel, click on you profile in the YouTube Dashboard and choose "Create a Channel".
The following are required body parameters. Please see the comments for requirements.
Note: The title must be 100 characters or less.
Premium or Business Plan required.
1
{
2
post: "YouTube Description", // required: Video description
3
platforms: ["youtube"], // required
4
mediaUrls: ["https://images.ayrshare.com/imgs/test-video-1.mp4"], // required: URL of video, 1 allowed
5
youTubeOptions: {
6
title: "YouTube Title", // required: Video Title, max 100 characters
7
youTubeVisibility: "private", // optional: "public", "unlisted", or "private" - default "private"
8
/** Important Thumbnail information below **/
9
thumbNail: "https://images.ayrshare.com/imgs/GhostBusters.jpg", // optional: URL of a JPEG or PNG and less than 2MB
10
playListId: "PLrav6EfwgDX5peD7Ni-pOKa7B13WjLyUB" // optional: Playlist ID to add the video
11
}
12
}
Copied!

​

YouTube Thumbnail Requirements

Thumbnails and other features, such as uploading 15 minute videos, require verification of your phone number. Thumbnails must be less than 2 MB in size.
In "YouTube Studio" go to "Setting" -> "Channel". Select "Feature Eligibility" and click "Features that require phone verification". Enter your phone number to enable.
YouTube Verify Phone

​

Video: Posting to YouTube via the API

​

Google My Business (GMB)

There are four types of GMB posts. In the below example, the post text is the summary of the GMB update. Find out more about Google My Business.
You must claim your Google My Business page before linking it with Ayrshare. Be sure to choose the Google account that is an admin of your GMB page during link authorization.
You can access your GMB manage console at https://business.google.com/​
Product posts cannot be created via the Google My Business API at this time.

Image or Video

An image or video can be added to your GMB location. Only one image or video is allowed per post. Note, the post text is not used, but required by the endpoint. For example, a restaurant can make a post to promote a new menu item.
These posts will appear in the "Photos" section in the GMB management console.
1
{
2
"post": "What an image!",
3
"platforms": ["gmb"],
4
"mediaUrls": ["https://images.ayrshare.com/imgs/ayrshare-code-ex.jpg"] // required
5
}
Copied!

Events

Promote an event at your business. Events require a title, start and end dates, and can include a video. For example, a real estate agent may advertise an open house showing signing.
Include an image with the mediaUrls parameter. Videos are not supported for Events.
These posts will appear in the "Posts -> Events" section in the GMB management console.
1
{
2
"post": "A great event!",
3
"platforms": ["gmb"],
4
"mediaUrls": ["https://images.ayrshare.com/imgs/ayrshare-code-ex.jpg"], // optional
5
"gmbOptions": {
6
"event": {
7
"title": "Check this event out.", // required
8
"startDate": "2021-08-12T20:17:46.384Z", // required
9
"endDate": "2021-09-12T20:17:46.384Z" // required
10
}
11
}
12
}
Copied!

Call to Action

Provide general information about your business. You can include a photo or video, a description, and an action button. For example, a website might promote a learn more about our SaaS platform.
Include an image with the mediaUrls parameter. Videos are not supported for Call to Actions.
These posts will appear in the "Posts -> What's New" section in the GMB management console.
1
{
2
"post": "Take this action!",
3
"platforms": ["gmb"],
4
"mediaUrls": ["https://images.ayrshare.com/imgs/ayrshare-code-ex.jpg"], //optional
5
"gmbOptions": {
6
"callToAction": {
7
"actionType": "order", // required
8
"url": "https://www.ayrshare.com" // required
9
}
10
}
11
}
Copied!
The actionType is displayed as a button on the post. Possible values are:
    book: Prompts a user to book an appointment, table, or something similar.
    order: Prompts a user to order something.
    shop: Prompts a user to browse a product catalog.
    learn_more: Prompts a user to see additional details on a website.
    sign_up: Prompts a user to register, sign up, or join something.
    call: Prompts a user to call a business.
The url parameter is the URL the user will be directed to upon clicking.

Offers

Provide promotional sales or offers from your business. Offers require a title as well as start and end dates and times. A "View offer" action button is automatically added to the post. You can also include a photo, video, description, coupon code, link, and terms and conditions with the post. For example, a toy store may advertise 20% off all beanie babies for a week.
Include an image with the mediaUrls parameter. Videos are not supported for Offers.
These posts will appear in the "Posts -> Offers" section in the GMB management console.
1
{
2
"post": "A great offer for everyone!",
3
"platforms": ["gmb"],
4
"gmbOptions": {
5
"offer": {
6
"title": "Great Sale.", // required
7
"startDate": "2021-08-12T20:17:46.384Z", // required
8
"endDate": "2021-09-12T20:17:46.384Z", // required
9
"couponCode": "BOGO-JET-CODE", // required
10
"redeemOnlineUrl": "https://www.ayrshare.com", // required
11
"termsConditions": "Offer only valid if you can prove you are a time traveler" // required
12
}
13
}
14
}
Copied!

Reddit

The following are required body parameters for posting to Reddit. Please be sure the subreddit allows automated posting.
1
{
2
post: "Reddit post", // required
3
platforms: ["reddit"], // required
4
redditOptions: {
5
title: "Reddit Post Title", // required
6
subreddit: "test", // required (no "/r/" needed)
7
reddit_link: "https://www.website.com", // optional: post a link
8
}
9
}
Copied!
    subreddit: The subreddit to send the post. Please be sure to follow the subreddit's posting guidelines. A good subreddit to use for testing is /r/test/
    reddit_link: If posting to Reddit and you want to post a link instead of text to the subreddit.
​

Profile Keys

Post to on behalf of user by providing users' Profile Keys a a body parameter. Please see here for details. Business Plan required.
​

Image and Video Requirements

Posting images and videos have different requirements for each network. See below for details, but don't worry. Our system verifies your post before sending, so you'll get an error response if something is wrong.
​

Auto Hashtags

Adds the the post relevant hashtags. Takes into account real-time hashtag popularity.
autoHashtag is an object, or Boolean - see below, with the following parameters:
    max: (optional) Integer of hashtags to add, range 1-5. Default 2.
    position: (optional) String "auto" or "end". Auto adds the hashtags within the post or to the end. "end" adds hashtags just to the end.
Post max length 1,000 characters, else hashtags will not added.
Premium or Business Plan required.
1
{
2
max: 3, // optional: Integer range 1-5
3
position: "auto" // optional: String "auto" or "end"
4
}
Copied!
If you do not want to send any of the above options, pass the Boolean value trueinstead of an object.
1
"autoHashtag": true
Copied!

Unsplash

Auto add Unsplash Image Parameters

The following fields are available for the unsplash body parameter:
    Random Image: random returns a random Unsplash image.
    Search Based Image: value String search term ; e.g. money will select a random image based on money.
    Image IDs: value Array of Ids [ids]; e.g. ["HubtZZb2fCM"] of image https://unsplash.com/photos/HubtZZb2fCM​
1
unsplash: "random"
2
unsplash: "search term" // unsplash: "money"
3
unsplash: ["unsplash image ID"] // unsplash: ["HubtZZb2fCM"]
Copied!
If copying an Unsplash URL to post in mediaUrls, please be sure to copy the image address and not just the URL. Please see this example for more information.

​

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.
1
{
2
"post": "Today is a great day!",
3
"platforms": [
4
"twitter"
5
],
6
"ads": {
7
"twitter": {
8
"campaign": "19ce55aplcy",
9
"group": "it9bm"
10
}
11
}
12
}
Copied!
Promoting a post as an add requires two parameters: campaign and group ids. When the post successfully is sent, it will be promoted as an ad in the given campaign and group.
If the campaign and group ids were preset with the PUT /ads/twitter/ids endpoint, use the createAd parameter to automatically promote the post.
1
{
2
"post": "Today is a great day!",
3
"platforms": [
4
"twitter"
5
],
6
"ads": {
7
"twitter": {
8
"createAd": true
9
}
10
}
11
}
Copied!
Please see the ads docs for more details:

Use Pre-Set Campaign and Group Ids

Preset the campaign and group ids with the /ads/twitter/ids endpoint and automatically use these ids when posting and promoting a Tweet with the createAd boolean parameter. You do not need to send the campaign or group ids.
1
{
2
"post": "Today is a great day!",
3
"platforms": [
4
"twitter"
5
],
6
"ads": {
7
"twitter": {
8
"createAd": true
9
}
10
}
11
}
Copied!

Additional Info

If you want to line breaks, new lines, in a post, use the invisible line break \u2063\n.For example, This is a new\u2063\nline
​
delete
https://app.ayrshare.com/api
/post
Delete a Post

Request Examples

cURL
Node.js
Python
PHP
C#
1
curl \
2
-H "Authorization: Bearer API Key" \
3
-H 'Content-Type: application/json' \
4
-d '{"id": "Post ID"}' \
5
-X DELETE https://app.ayrshare.com/api/post
Copied!
1
const fetch = require("node-fetch");
2
const API_KEY = "API_KEY";
3
const id = "Post ID";
4
​
5
fetch("https://app.ayrshare.com/api/post", {
6
method: "DELETE",
7
headers: {
8
"Content-Type": "application/json",
9
"Authorization": `Bearer ${API_KEY}`
10
},
11
body: JSON.stringify({ id }),
12
})
13
.then((res) => res.json())
14
.then((json) => console.log(json))
15
.catch(console.error);
Copied!
1
import requests
2
​
3
payload = {'id': 'Post ID'}
4
headers = {'Content-Type': 'application/json',
5
'Authorization': 'Bearer API_KEY'}
6
​
7
r = requests.delete('https://app.ayrshare.com/api/post',
8
json=payload,
9
headers=headers)
10
11
print(r.json())
Copied!
1
<?php
2
require 'vendor/autoload.php'; // Composer auto-loader
3
​
4
$client = new GuzzleHttp\Client();
5
$res = $client->request(
6
'DELETE',
7
'https://app.ayrshare.com/api/post',
8
[
9
'headers' => [
10
'Content-Type' => 'application/json',
11
'Authorization' => 'Bearer API_KEY'
12
],
13
'json' => [
14
'id' => ['7NFVK0QIXET5rCUS9tmf'] // top-level id from post request
15
]
16
]
17
);
18
​
19
echo json_encode(json_decode($res->getBody()), JSON_PRETTY_PRINT);
Copied!
1
using System;
2
using System.Net;
3
using System.IO;
4
​
5
namespace DeletePOSTRequest_charp
6
{
7
class Delete
8
{
9
static void Main(string[] args)
10
{
11
string API_KEY = "API_KEY";
12
string url = "https://app.ayrshare.com/api/post";
13
​
14
var httpWebRequest = WebRequest.CreateHttp(url);
15
httpWebRequest.ContentType = "application/json";
16
httpWebRequest.Method = "DELETE";
17
httpWebRequest.Headers.Add("Authorization", "Bearer " + API_KEY);
18
​
19
using (var streamWriter = new StreamWriter(httpWebRequest.GetRequestStream()))
20
{
21
string json = "{\"id\" : \"Post ID\"}";
22
​
23
streamWriter.Write(json);
24
streamWriter.Flush();
25
}
26
​
27
var httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();
28
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
29
{
30
var response = streamReader.ReadToEnd();
31
Console.WriteLine(response);
32
}
33
}
34
}
35
}
Copied!
Instagram and Facebook Groups do not support delete via an API. Please go to instagram.com or facebook.com to delete the posts.

Delete Profile Posts

Delete a post for a particular user profile by passing the profileKeys parameter as a body parameter.
Available for Business Plan users only.
1
const fetch = require("node-fetch");
2
const API_KEY = "API_KEY";
3
const PROFILE_KEY = "PROFILE_KEY";
4
const id = "Post ID";
5
​
6
fetch("https://app.ayrshare.com/api/post", {
7
method: "DELETE",
8
headers: {
9
"Content-Type": "application/json",
10
"Authorization": `Bearer ${API_KEY}`
11
},
12
body: JSON.stringify({
13
profileKeys: PROFILE_KEY, // a single Profile Key passed as a String
14
id
15
}),
16
})
17
.then((res) => res.json())
18
.then((json) => console.log(json))
19
.catch(console.error);
Copied!
​
post
https://app.ayrshare.com/api
/post/bulk
Bulk Post

Request Examples

A multipart form-data containing a CSV file of posts will schedule them for a future date.
1
curl \
2
-H "Authorization: Bearer API_KEY" \
3
-H 'Content-Type: multipart/form-data' \
4
-F '[email protected]"./Ayrshare CSV Template.csv"' \
5
-X POST https://app.ayrshare.com/api/post/bulk
Copied!
The CSV file contains the following fields (template below):
    post: The post text.
    platforms: Comma separated list of platforms, e.g. "twitter, facebook, instagram".
    mediaUrls: URL of media, such as an image or video to include in the post.
    scheduleDate: Datetime to schedule the post. Formate MM/DD/YYYY h:m. E.g. 5/23/2021 14:34. Times are in UTCβˆ’08:00.
Don't send duplicate posts less than three days apart.
If the scheduleDate of two posts with the exact same text are less than three days apart, the second post will be rejected when the scheduleDate occurs. This is done to protect your account at the networks; they often suspend or shadow-ban accounts with frequent duplicate posts.

CSV Template

Download the template and save as a .csv file.
Ayrshare CSV Template.csv
188B
Text
Ayrshare CSV Template
​
Last modified 12d ago