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

application/json

Bodyrequired

    accountIdsstring[]required

    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.

    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)
    • Content is automatically trimmed to platform limits

    Reference: Platform Limitations Guide

    mediaobject[]

    Post Media Data The limitations of media as per the platforms is provided through the reference link in API description

    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
    • Draft posts skip most validations (accountIds, media requirements)
    Available optionsdraftscheduledin_reviewpublishedin_progresspendingfailednotification_sentdeleted
    scheduleDatestring

    Schedule Date

    selectedBestTimestring

    Selected Best Time slot for scheduling

    createdBystring

    User ID of the creator who is creating/managing the post. Must be a valid MongoDB ObjectId.

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

    Validation: Must be a valid MongoDB ObjectId.

    followUpCommentstring

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

    Supported Platforms: Facebook, Instagram, LinkedIn, YouTube

    NOT Supported: TikTok, Google My Business (GMB), Pinterest

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

    • Follow-up comment is automatically trimmed to platform limits

    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 MongoDB ObjectIds.

    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 MongoDB ObjectId.

    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

    userIdstringrequired

    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
application/json

Successful response

Schema
    successbooleanrequired

    Success or Failure

    statusCodenumberrequired

    Status Code

    messagestringrequired

    Message

    resultsobject

    Requested Results