Post API Overview

Schedule posts, auto hashtag, auto-post schedule, and more

Available on Basic, Premium, Business, Enterprise plans.

The post endpoint allows you to publish posts to the social networks: Facebook Pages, Google Business Profile, Instagram, LinkedIn, Pinterest, Reddit, Telegram, TikTok, X/Twitter, and YouTube. There are many options to customize your post, such as scheduling posts, adding auto hashtag, auto-post schedule, and more.

Start publishing posts with the /post POST endpoint.

Approval Workflow

If your workflow requires approval before sending a post, set the requiresApproval field to true. This is a common workflow for agencies, for example.

The post will have a status of “awaiting approval” until the approved parameter is set to true via the /post PATCH endpoint.

1

Publish with parameters

Publish your post using the /post endpoint with the requiresApproval field as true. You may also including standard parameters such as scheduleDate.

2

Status is awaiting approval

The post will be in a status of “awaiting approval” and will be held until approval is granted.

3

Approve the post

Update the post with the /post PUT operation setting the approved field as true. The post will now be sent at the scheduled time.

4

Use notes

Optional: Set notes on the post for reference, such as who needs to approve the post.

{
  "requiresApproval": true,
  "notes": "need approval by John Smith" // optional
}

Auto Hashtags

Add the most relevant hashtags to your post.

autoHashtag is an object, or Boolean - see below, with the following parameters:

• max: (optional) Integer of hashtags to add, range 1-10. 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.

A paid plan is required.

{
  "hashtags": {
    "max": 3, // optional: Integer range 1-10
    "position": "auto" // optional: String "auto" or "end"
  }
}

If you do not want to send any of the above options, pass the Boolean value true instead of an object.

{
  "autoHashtag": true
}

First Comment

Automatically add in a first comment immediately after publishing the post. Posting the first comment on your own social media post can help kickstart engagement and set the tone for the discussion that follows.

{
  "firstComment": {
    "comment": "My first comment", // required
    "mediaUrls": ["https://..."] // Facebook and X/Twitter only
  }
}

Idempotent Posts

Idempotency is a feature that ensures a request is only executed once, even if it is accidentally sent multiple times. When posting content using the API, you can include an optional idempotencyKey parameter in the request body to uniquely identify the operation. This allows you to safely retry the post request without the risk of creating duplicate posts.

To use idempotency, add the idempotencyKey parameter to the JSON body of the /post POST request:

{
  "idempotencyKey": "Unique Key"
}

The value of idempotencyKey should be a unique string per User Profile. If a request is made with the same idempotencyKey for a given User Profile, regardless of the post’s state (success, error, pending, or deleted), an error will be returned, indicating that a duplicate key was found.

The API must first accept and process the POST request to store the idempotency key and check for duplicates. However, if multiple POST requests with the same idempotencyKey are sent simultaneously or scheduled for the same posting time, the API may not detect the duplicate keys. This is because the API processes these concurrent or simultaneously scheduled requests in parallel, before it has a chance to register the idempotency key from any single request. As a result, there’s no guarantee that duplicate idempotent keys will be caught in these scenarios of simultaneous submission or execution of scheduled posts.

Using idempotency helps prevent accidental creation of duplicate posts when retrying failed requests or handling network issues. However, it’s still recommended to implement appropriate error handling and retry mechanisms in your application to handle potential failures gracefully.

Image & Video Requirements

Posting images and videos have different requirements for each network, but don’t worry. Our system verifies your post before sending, so you’ll get an error response if something is wrong. See the below link of details on image and video guidelines.

Image & Video Guidelines

Valid URL

Be sure your media URL(s) are valid and directly access the media. A first test is trying the URL in a browser. If the image will not load or cannot be downloaded in a browser it will likely fail.

Spaces & Special Characters

We recommend to avoid the following in your media URLs:

• Spaces in the URL.
• URL encoded spaces in the URL.
• Special characters in the URL even if they are url encoded, such as accent marks é.

For example:

https://img.ayrshare.com/012/test .webp

This URL fails because of the space test .webp. We also don’t recommend using URL encoded spaces, such as %20 in the URL - this can also cause issues with some social networks.

And this Unsplash image:

https://unsplash.com/photos/a-house-in-the-middle-of-a-field-with-trees-in-the-background-znbmh2-cIj0

This Unsplash image fails because it isn’t directly accessing the image, but showing a web app.

Sanitize File Names & URLs

You can sanitize your file names with a regular express such as /[^a-z0-9\/\.]/gi.

const sanitizeFileName = (url) => url.replace(/[^a-z0-9\/\.]/gi, "_");
sanitizeFileName("tést .webp"); // t_st_.webp

or sanatize a URL

const sanitizeUrl = (url) => {
  const [protocol, rest] = url.split("://");
  const [domain, ...path] = rest.split("/");
  const sanitizedPath = path.join("/").replace(/[^a-z0-9\/\.]/gi, "_");
  return `${protocol}://${domain}/${sanitizedPath}`;
};

// Output: https://img.ayrshare.com/012/t_st_.webp
sanitizeUrl("https://img.ayrshare.com/012/tést .webp");

Additional Information:

• If you’re self hosting, make sure the URL can be externally accessed and doesn’t require special permissions.

• See below the how to handle videos with unknown extensions, often signed URLs such as AWS S3.

• If you are using a signed URL, such as S3, we recommend to set the URL expiration to at least 7 days. This allows our team to assist with any questions you have on publishing the post.

• Test if the media URL exists with our verify media tools.

Download Speed

Be sure the your media hosting has a fast connection, especially download speed. You can test your media hosting performance at pingdom. We recommend at least a B rating.

Larger Videos

The app.ayrshare.com domain has a 60 second timeout. If the social network takes an extended period to process a video, an HTTP 500 response may be returned - the video will still be published if no errors occur.

For file uploads greater than 10 MB, obtain a presigned URL to upload a file.

Video Extension

If your URL does not end in a known video extension such as mp4, you can use the isVideo: true field in the post to specify the mediaUrl is a video . Ayrshare will try to determine the file type, such as MOV. However, we recommend explicitly ending your video file with a known extension, such as mp4, since this has a higher success rate with the social networks.

Image or Video Only

A few social networks support sending media without post text. If you do not want post text included send and empty String post: ""

The following social networks support no post/blank text: Facebook, Instagram, LinkedIn, TikTok, and X/Twitter.

Testing Images and Videos

Consider using the generate random text and random image or video to speed up your testing. Stop trying to think up something different for each of your test posts!

Line Breaks

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.

We also recommend trying in Postman to see how the new line break is translated in your language of choice. For example, PHP often only uses a \n

Some social networks do not currently support line breaks in the post text.

Multi-Platform Posts and Media

This feature allows you to customize your post content and media for different social networks within a single API call. You can specify unique text and/or images for each platform by using objects for the post and mediaUrls fields.

1. Use an object structure for post and/or mediaUrls fields.
2. Specify platform-specific content using platform names as keys.
3. Include a default key for content to be used on platforms not explicitly specified.

{
  "post": {
    "instagram": "Great IG pic!",
    "facebook": "Great FB pic!",
    "default": "Great default pic!"
  },
  "platforms": ["instagram", "facebook", "linkedin"],
  "mediaUrls": {
    "instagram": "https://img.ayrshare.com/012/gb.jpg",
    "linkedin": "https://img.ayrshare.com/012/gb.jpg",
    "default": "https://img.ayrshare.com/012/gb.jpg"
  }
}

In the example above:

• Instagram will use its specific text and image URL.
• Facebook will use its specific text and the default image URL.
• LinkedIn will use the default text and its specific image URL.

If you need to post multiple images to different platforms, create separate posts for each platform instead of using this multi-platform structure.

Profile Keys

Post to on behalf of user by providing users’ Profile Keys a a body parameter and the additional data in the response. Business or Enterprise Plan required.

Profiles

Rich Text Posts

You can add rich text such as ”𝓗𝓮𝓵𝓵𝓸, how about a little 𝗯𝗼𝗹𝗱 𝘁𝗲𝘅𝘁 and 𝘪𝘵𝘢𝘭𝘪𝘤𝘴 𝘵𝘦𝘹𝘵 and an x₂?”. You can use rich text on networks such as Twitter, Facebook, LinkedIn, Telegram, and Instagram. If posting to Reddit, please use Reddit-flavored Markdown formatting.

HTML elements are used to specify the type of rich text, which is translated into unicode. For example:

{
    "post": "<var>Hello</var>, how about a little <b>bold text</b> and <i>italics text</i> and an x<sub>2</sub>?"
    "platforms": ["twitter"]
}

HTML Elements

HTML	Example
<b>Nice One!</b>	Nice One!
<strong>Hello, world!</strong>	Hello, world!
<em>World</em>	World
normal <i>italics <b>bold italics</b></i>	normal italics bold italics
`<b>Hello</b>, world!`	Hello, world!
`<b>Hello</b>, world!`	Hello, world!
<samp>123</samp>	𝟷𝟸𝟹
<var>Hello</var>	𝓗𝓮𝓵𝓵𝓸
x<sub>2</sub>	x₂
x<sup>2</sup>	x²

CSS Codes

Code	Example	Result
\u00B0	It’s 25\u00B0C today!	It’s 25°C today!
\u2063\n	This is a new\u2063\nline.	This is a new line.

Schedule Posts

Create Scheduled Posts

You can schedule future posts by specifying the scheduleDate parameter with the datetime in Zulu/UTC. Zulu Time, also known as Coordinated Universal Time (UTC), is the world standard for time.

For example, use format YYYY-MM-DDThh:mm:ssZ and send as 2023-07-08T12:30:00Z.

"scheduleDate": "2023-07-08T12:30:00Z"

Please see https://www.utctime.net/

Note: If the scheduled datetime is in the past, the post will immediately be sent.

If a mediaUrl is included with a scheduled post, the media must be available at the scheduled publication time. For example, if the post is scheduled to be published on March 1, the media must be available on March 1.

Check a Scheduled Post Status

You can check the status of a scheduled post several ways:

• Set up the Webhook Scheduled Action to automatically receive the status of the scheduled post. This is available for the Business plan and is the recommended method.

• Get the status of a scheduled post with the GET call with the post ID.

• Check the status in the Ayrshare Dashboard. First switch to the User Profile the post as published under, then go to “Posts” page and search using the Ayrhare Post ID.

Pause Scheduled Posts

You may paused scheduled posts that have not yet been published. Pausing a scheduled post will prevent it from being published until the post has been unpaused.

Use the PATCH call to pause or unpause the scheduled post. Please note if a post is unpaused and the scheduleDate is in the past the post will immediately be published. Consider updating the scheduleDate before unpausing.

Shorten Links

Links in a post can be shortened using the Ayrshare link shortner. You can turn on the automatic link shortening with the shortenLinks parameter when sending a post. Max Pack required.

{
  "shortenLinks": true
}

Unsplash Images

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; e.g. [“HubtZZb2fCM”] of image https://unsplash.com/photos/HubtZZb2fCM

"unsplash": "random"
"unsplash": "search term"           // unsplash: "money"
"unsplash": ["unsplash image ID"]   // unsplash: ["HubtZZb2fCM"]

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.