Skip to main content
Version: v3

Create post

POST 
/social-media-posting/:locationId/posts

Create posts for all supported platforms. It is possible to create customized posts per channel by using the same platform account IDs in a request and hitting the create post API multiple times with different summaries and account IDs per platform.

The content and media limitations, as well as platform rate limiters corresponding to the respective platforms, are provided in the following reference link:

Link: Platform Limitations

Request​

Version stringrequired

API Version

Available optionsv3
locationId stringrequired

Location ID (also known as Sub-Account ID) for the business location.

application/json

Bodyrequired

    accountIdsstring[]

    Account IDs for the post. Each account ID identifies a connected social media account.

    Get IDs from: Get Accounts API — use the id field from each account.

    One request = one post, shared across every account in this list.

    • All accounts share the same summary and the same media array.
    • summary is trimmed to the strictest character limit among the selected platforms. Adding a Bluesky account (300 chars) therefore trims the caption to 300 for Facebook, Instagram and LinkedIn in that same request.
    • media is capped to each platform's own maximum at publish time (e.g. Bluesky publishes the first 4 items, Instagram the first 10).
    • To keep full-length, platform-specific captions, send one request per platform - one post per platform, each with only that platform's account IDs.

    Validations:

    • Required for non-draft posts
    • Must be a non-empty array
    • All account IDs must be valid connected accounts for the location
    summarystring

    Post content/caption text. Character limits vary by platform.

    Custom Values & Hashtags:

    • You can include custom values/variables in the content (e.g., {{contact.name}})
    • Hashtags: Use #hashtag format. Instagram allows max 30 hashtags.
    • Mentions: Use platform-specific mention format (see mentions field for structured mentions)

    Validations:

    • Instagram/Facebook Story: Caption NOT supported for direct publishing
    • Facebook, LinkedIn, GMB: Content OR media is required (at least one)

    Trimming across multiple platforms: One post carries ONE caption for every account in accountIds, so the caption is silently trimmed to the strictest limit among the selected platforms — not to each platform's own limit.

    • Facebook 63,206 · LinkedIn 3,000 · Instagram / TikTok 2,200 · Google 1,500 · Pinterest 800 · Threads 500 · Bluesky 300
    • Example: accountIds covering Facebook + Instagram + Bluesky trims the caption to 300 characters on all three.
    • Instagram/Facebook Stories without push-notification publishing force the limit to 0, dropping the caption entirely.
    • To keep the full caption on each platform, send one request per platform instead of one request mixing platforms.

    Reference: Platform Limitations Guide

    mediaarray[]

    Post Media Data. Per-platform media limits are listed in the reference link in the API description.

    Across multiple platforms: the same media array is sent to every account in accountIds and capped to each platform's own maximum at publish time — the array is NOT reduced to the strictest limit the way summary is. An 8-item array publishes 8 items to Facebook and the first 4 to Bluesky. Send one request per platform if a platform needs a different set of media.

    statusstring

    Post status indicating the current state of the post.

    Available Status Values:

    • draft - Post saved as draft, not yet ready for publishing
    • scheduled - Post scheduled for future publishing (requires scheduleDate)
    • in_review - Post pending approval (requires scheduleDate and postApprovalDetails)
    • published - Post has been published
    • in_progress - Post is currently being processed
    • pending - Post is awaiting platform processing for Instagram media container creation
    • failed - Post publishing failed
    • notification_sent - Story notification sent (for manual story posting)
    • deleted - Post has been deleted

    Validations:

    • scheduled or in_review status requires scheduleDate to be set
    • Submitting for review (in_review) requires postApprovalDetails.approver; approve/reject actions reuse the stored approver
    • Draft posts skip most validations (accountIds, media requirements)
    Available optionsdraftscheduledin_reviewpublishedin_progresspendingfailednotification_sentdeleted
    scheduleDatestring

    Schedule Date. Required when status is scheduled or in_review.

    selectedBestTimestring

    Selected Best Time slot for scheduling

    createdBystring

    User ID of the creator who is creating/managing the post. Must be a valid 24-character hex ID.

    Get User IDs from: Get User API — use the id field from the user object.

    Validation: Must be a valid 24-character hex ID.

    followUpCommentstring

    Follow-up comment to be posted immediately after the main post is published.

    Supported Platforms: Facebook, Instagram, LinkedIn, Community, Threads, Bluesky, YouTube, TikTok

    NOT Supported: GBP (Google Business Profile), Pinterest

    • TikTok: posted once the video becomes publicly viewable (~1-3 min), not instantly

    • TikTok: only public videos support a follow-up comment. Set privacyLevel to PUBLIC_TO_EVERYONE — friends-only and private videos are not supported

    Use Case: Great for adding hashtags, additional context, or engagement prompts without cluttering the main post.

    • Like summary, the follow-up comment is trimmed to the strictest limit among the post's platforms, not to each platform's own limit — a post that includes Bluesky (300) trims the comment to 300 everywhere. Send one request per platform to keep the full comment on each.

    Reference: Platform Limitations Guide

    ogTagsDetailsobject

    Og Tags Meta Data

    typestringrequired

    Type of post to create. Determines the format and platform requirements.

    Available Types:

    • post - Standard feed post (all platforms)
    • story - Temporary 24-hour story (Instagram, Facebook)
    • reel - Short-form video content (Instagram, Facebook, TikTok, YouTube)

    Customize Per Platform: You can specify different content/types per platform using facebookPostDetails.type, instagramPostDetails.type, etc.

    Validations:

    • Reels require exactly 1 video
    • Stories: Caption not supported for Instagram/Facebook
    • Facebook Groups do not support Reels
    Available optionspoststoryreel
    postApprovalDetailsobject

    Post Approval Details

    scheduleTimeUpdatedboolean

    Flag indicating if the schedule datetime was manually updated. Used for tracking rescheduled posts.

    tagsstring[]

    Array of Tag IDs to associate with the post for organization and filtering.

    Get Tag IDs from: Get Tags API — use the _id field from each tag.

    Validation: All IDs must be valid 24-character hex IDs.

    categoryIdstring

    Category ID to organize the post. Categories help group related posts.

    Get Category IDs from: Get Categories API — use the _id field.

    Validation: Must be a valid 24-character hex ID.

    applyWatermarkboolean

    Apply watermark to media in this post.

    Note: Watermarks are applied to images only. Videos are not watermarked.

    tiktokPostDetailsobject

    Tiktok Post Details

    gmbPostDetailsobject

    GMB Post Details

    userIdstring

    User ID of the user creating/managing the post. Required for OAuth channel posts (non-draft).

    linkedinPostDetailsobject

    LinkedIn-specific post configuration.

    Key Fields:

    • postAsPdf: Set to true to post images as a PDF carousel document
    • pdfTitle: Title for the PDF document (max 100 characters)

    Limits:

    • Max 9 images/videos for regular posts
    • Max 300 pages for PDF carousel
    • Max PDF size: 100 MB

    Reference: Platform Limitations Guide

    pinterestPostDetailsobject

    Pinterest-specific post configuration. Required when posting to Pinterest accounts.

    Required Fields:

    • boardIds: Object mapping account OAuth IDs to Pinterest board IDs

    Optional Fields:

    • title: Pin title (max 100 characters)
    • link: Destination URL for the pin (max 2048 characters)

    Get Board IDs: Use the Pinterest boards API or retrieve from connected account details.

    Limits:

    • Max 1 image/video per pin
    • Caption max 800 characters

    Reference: Platform Limitations Guide

    facebookPostDetailsobject

    Facebook-specific post configuration.

    Key Fields:

    • type: Post type (post, story, reel)

    Restrictions:

    • Facebook Groups do NOT support Reels
    • Reels require exactly 1 video
    • Stories do not support captions

    Reference: Platform Limitations Guide

    instagramPostDetailsobject

    Instagram-specific post configuration.

    Key Fields:

    • type: Post type (post, story, reel)
    • collaborators: Map of account IDs to Instagram usernames for collaboration invites (max 5 per account)
    • showOnFeed: Show reel on profile feed (for reels)

    Collaborators Structure:

    { "accountId": ["username1", "username2"] }

    Where accountId is from Get Accounts API and usernames are Instagram handles without @.

    Restrictions:

    • Media is REQUIRED for all Instagram posts
    • Max 30 hashtags allowed in caption
    • Stories do not support captions
    • Collaborators: Posts/Reels only (NOT Stories)
    • Reels require exactly 1 video

    Reference: Platform Limitations Guide

    youtubePostDetailsobject

    YouTube-specific post configuration.

    Key Fields:

    • title: Video title (max 100 characters)
    • type: Video type (video for regular videos, short for YouTube Shorts)
    • privacyLevel: Video visibility (private, public, unlisted)

    Limits:

    • Max 1 video per post
    • Caption (description) max 5,000 characters

    Requirements:

    • Video is REQUIRED for YouTube posts
    • type field is required
    communityPostDetailsobject

    Community-specific post configuration for platform Communities.

    Required Fields:

    • title: Post title (max 1,000 characters)
    • postAsUser: Map of account IDs to user objects (id, name, avatar)

    Optional Fields:

    • notifyAllGroupMembers: Send notification to all group members

    Limits:

    • Max 4 media items
    • Caption max 100,000 characters
application/json

Successful response

Schema
    successbooleanrequired

    Success or Failure

    statusCodenumberrequired

    Status Code

    messagestringrequired

    Message

    resultsobject

    Requested Results