This is documentation for HighLevel API 2021-07-28, which is no longer actively maintained.
For up-to-date documentation, see the latest version (v3).
PostVersion: 2021-07-28
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:
Location ID (also known as Sub-Account ID) for the business location.
Example:ve9EPM428h8vShlRW1KT
Body
application/json
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 20).
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
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.
Example:Hello World! Check out our latest updates. #social #marketing
mediaobject[]
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.
MIME type of the media file. See Platform Limitations Guide for platform-specific format support.
Available optionsimage/jpegimage/jpgimage/pngimage/gifvideo/mp4video/movvideo/webm
Example:image/jpeg
media[].thumbnailstring
Cover image URL for a video media item.
Scope
Applies to the first video in media[]. Values supplied on subsequent video items are ignored.
Has no effect on image-only media items.
Response behavior
After the post is published, the resolved cover image is surfaced on the post-level thumbnail field of the response and is no longer echoed back inside media[]. This represents the post's primary cover image and the cover used for the first video.
Limitations
Per-item thumbnails for multi-video posts are not supported. Each destination network exposes a single cover image per post for the leading video; this matches the behavior of the underlying social platform APIs.
Format
Provide a publicly accessible JPEG or PNG URL. Animated formats and video URLs are not accepted.
Recommended: an image matching the orientation of your video and ≤ 2 MB.
MIME type of the optimized media. May differ from original if format conversion occurred.
Example:image/jpeg
media[].isModifiedboolean
Flag indicating if the media was modified (watermarked, optimized, or processed).
Example:true
media[].altTextstring
Alt text for accessibility. Supported on Instagram, Threads, Pinterest, Bluesky, and LinkedIn image posts (ignored for video and other platforms). Auto-truncated per platform: Pinterest 500, Instagram/Threads 1000, Bluesky 2000, LinkedIn 4086 chars.
Example:A sunset over the ocean with silhouetted palm trees
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
Example:draft
scheduleDatestring
Schedule Date in ISO format. Required when status is scheduled or in_review. Must be at least 1 minute after the current time when creating a post, or when editing a post with statusscheduled; past dates are rejected with a 422.
Example:2024-01-15T10:00:00Z
selectedBestTimestring
Selected Best Time slot for scheduling
Example:2024-01-15T10:00:00Z
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.
Example:65f151c99bc2bf3aaf970d72
followUpCommentstring
Follow-up comment to be posted immediately after the main post is published.
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.
Per-account Pinterest board selection. Each entry binds one connected Pinterest account to a list of boards on that account. Each board produces an independent child post tracked separately for success/failure. Capped at 25 boards per account.
When supplied, this field takes precedence over the deprecated boardIds field.
Pinterest board IDs to publish to on this account. Each board produces an independent child post tracked separately for success/failure. Capped at 25 boards per account.
Reels: Require exactly 1 video, not supported on Groups
Stories: Captions not supported
Available optionspoststoryreel
Example:post
facebookPostDetails.textFormatPresetIdstring
Facebook background preset ID for text-only feed posts. Facebook post only — not story or reel. Ignored when media is attached; metaLink is omitted on publish.
Send Instagram Story via Push Notification instead of direct posting. Only applicable for Story type.
Example:true
instagramPostDetails.publisherNotestring
Note to the publisher for manual posting guidance. Only used when publishViaPushNotification is true.
Example:When publishing, add swipe up link to the landing page so that we can direct them to the sales page
instagramPostDetails.notificationSentCountnumber
Number of push notifications sent for this Instagram Story. Tracks how many notifications have been sent out.
Example:1
instagramPostDetails.postedViastring
Source of where the post was marked as published. Values: "web" (web interface), "mobile" (mobile app), or null.
Available optionswebmobile
Example:web
instagramPostDetails.showOnFeedboolean
Show Reel on profile grid/feed.
✅ Applies to: Reels only
true - Reel appears on your profile grid
false - Reel only appears in Reels tab
Example:true
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
Example
{"title":"Video Title","privacyStatus":"public"}
youtubePostDetails.titlestring
Video title displayed on YouTube.
Max length: 100 characters
Best Practices:
Include relevant keywords
Be descriptive but concise
Avoid clickbait
Example:How to Build a Successful Marketing Strategy in 2024
youtubePostDetails.privacyLevelstring
Video visibility/privacy setting.
Available Values:
public - Anyone can search and view
unlisted - Only people with the link can view
private - Only you can view
Available optionsprivatepublicunlisted
Example:public
youtubePostDetails.typestringrequired
YouTube video format type.
Available Types:
video - Standard YouTube video (landscape, any duration)
short - YouTube Shorts (square or vertical aspect ratio, up to 3 minutes)
Required field.
Available optionsvideoshort
Example:video
communityPostDetailsobject
Community-specific post configuration for Communities.
Required Fields:
title: Post title (max 1,000 characters)
postAsUser: the member to publish as, keyed by Community account ID
Optional Fields:
notifyAllGroupMembers: notify all group members (@everyone broadcast)
Limits:
Max 4 media items
Caption max 100,000 characters
Required whenaccountIds contains a Community account and the post is not a draft.
Example
{"title":"Welcome to our community!","notifyAllGroupMembers":false,"postAsUser":{"aF3KhyL8JIuBwzK3m7Ly_iVrVJ2uoXNF0wzcBzgl5_12554616564525983496":{"id":"YBjxnYiXJKmoyV7WDjjG","name":"Jane Cooper"}}}
communityPostDetails.titlestringrequired
Title of the community post. Displayed as the post headline.
Max length: 1,000 characters
Required: Yes, for all Community posts.
Example:Welcome to Our New Community Feature!
communityPostDetails.notifyAllGroupMembersboolean
Notify every member of the group when the post is published, equivalent to an @everyone broadcast prepended to the post content.
Use Case: Enable for announcements that all members should see.
Default:false
Example:true
communityPostDetails.postAsUserobjectrequired
The Community member each post is published as, keyed by Community account ID.
Structure:{ accountId: { id, name, avatar } }
Key — the Community account ID. This is the same value you pass in accountIds: take it from the id field of a Community account in the Get Accounts API, not the oauthId field.
id (required) — contactId of the member to publish as, from the Get Community Members API.
name (optional) — display name shown as the post author.
avatar (optional) — profile image URL shown against the post.
Required: Yes. Every Community account listed in accountIds must have an entry here, otherwise the request is rejected.
Member eligibility: the member must be an active member of the group and hold a role in it. This is checked again at publish time, so a member who leaves the group or loses access between scheduling and publishing causes that post to fail. Use the Validate Community Member API to confirm a stored member is still eligible before scheduling.
Private channels: list members per account rather than reusing one list across accounts — for a private channel only that channel's members may be posted as.
source must be one of the following values: composer, recurring, csv
Available optionscomposercsvrecurringreviewrsstemplate-librarycategory-queuenative
Example:composer
results.post.locationIdstringrequired
Location Id
Example:ve9EPM428h8vShlRW1KT
results.post.platformstring
platform must be one of the following values: google, facebook, instagram, linkedin, twitter, tiktok
Example:google
results.post.displayDatestring<date-time>
Display date for the post
Example:2023-08-02T00:00:00.000Z
results.post.createdAtstring<date-time>
Date when the post was created
Example:2023-08-02T00:00:00.000Z
results.post.updatedAtstring<date-time>
Date when the post was last updated
Example:2023-08-02T00:00:00.000Z
results.post.accountIdstring
Account Id
Example:w37swmmLbA02zgqKPpxITe
results.post.errorstringrequired
Error
Example:Failed due to auth token
results.post.postIdstring
Platform-specific post identifier
Example:323534534435
results.post.previewLinkstring
Direct link to view the published post on the native platform. Populated once the post is published on a platform that returns a permalink; null for posts that are not yet published (draft, scheduled, failed) or on platforms that do not return a link.
Aggregated engagement metrics for the published post. Populated asynchronously by the insights sync workers for supported platforms (Facebook, Instagram, LinkedIn, YouTube). Absent on posts that have not been synced yet or on platforms where insights are not supported.
results.post.insights.likenumber
Number of likes on the published post
Example:12
results.post.insights.sharenumber
Number of shares of the published post
Example:3
results.post.insights.commentnumber
Number of comments on the published post
Example:5
results.post.publishedAtstring
Date when the post was published
Example:2021-06-22T05:32:49.463Z
results.post.thumbnailstring
Post-level cover image (thumbnail) URL.
For posts that contain a video, this is the resolved cover image used for the first video in media[]. It is set automatically from the thumbnail provided on the first video media item at create/edit time, or auto-generated from the video when one is not supplied. Per-item thumbnails inside media[] are not retained on the response — the primary cover image lives on this field.
MIME type of the media file. See Platform Limitations Guide for platform-specific format support.
Available optionsimage/jpegimage/jpgimage/pngimage/gifvideo/mp4video/movvideo/webm
Example:image/jpeg
results.post.media[].thumbnailstring
Cover image URL for a video media item.
Scope
Applies to the first video in media[]. Values supplied on subsequent video items are ignored.
Has no effect on image-only media items.
Response behavior
After the post is published, the resolved cover image is surfaced on the post-level thumbnail field of the response and is no longer echoed back inside media[]. This represents the post's primary cover image and the cover used for the first video.
Limitations
Per-item thumbnails for multi-video posts are not supported. Each destination network exposes a single cover image per post for the leading video; this matches the behavior of the underlying social platform APIs.
Format
Provide a publicly accessible JPEG or PNG URL. Animated formats and video URLs are not accepted.
Recommended: an image matching the orientation of your video and ≤ 2 MB.
MIME type of the optimized media. May differ from original if format conversion occurred.
Example:image/jpeg
results.post.media[].isModifiedboolean
Flag indicating if the media was modified (watermarked, optimized, or processed).
Example:true
results.post.media[].altTextstring
Alt text for accessibility. Supported on Instagram, Threads, Pinterest, Bluesky, and LinkedIn image posts (ignored for video and other platforms). Auto-truncated per platform: Pinterest 500, Instagram/Threads 1000, Bluesky 2000, LinkedIn 4086 chars.
Example:A sunset over the ocean with silhouetted palm trees
results.post.statusstring
Status must be one of the following values: in_progress, draft, failed, published, scheduled, in_review, notification_sent, pending, deleted
Available optionsin_progressdraftfailedpublishedscheduledin_reviewnotification_sentpendingdeleted
Example:published
results.post.createdBystring
User ID who created the post
Example:Lx1EI6YIgQYMQi0ytFXv
results.post.typestringrequired
Post Type must be one of the following values: post, story, reel, short
Per-account Pinterest board selection. Each entry binds one connected Pinterest account to a list of boards on that account. Each board produces an independent child post tracked separately for success/failure. Capped at 25 boards per account.
When supplied, this field takes precedence over the deprecated boardIds field.
Pinterest board IDs to publish to on this account. Each board produces an independent child post tracked separately for success/failure. Capped at 25 boards per account.
Facebook background preset ID for text-only feed posts. Facebook post only — not story or reel. Ignored when media is attached; metaLink is omitted on publish.
The Community member each post is published as, keyed by Community account ID.
Structure:{ accountId: { id, name, avatar } }
Key — the Community account ID. This is the same value you pass in accountIds: take it from the id field of a Community account in the Get Accounts API, not the oauthId field.
id (required) — contactId of the member to publish as, from the Get Community Members API.
name (optional) — display name shown as the post author.
avatar (optional) — profile image URL shown against the post.
Required: Yes. Every Community account listed in accountIds must have an entry here, otherwise the request is rejected.
Member eligibility: the member must be an active member of the group and hold a role in it. This is checked again at publish time, so a member who leaves the group or loses access between scheduling and publishing causes that post to fail. Use the Validate Community Member API to confirm a stored member is still eligible before scheduling.
Private channels: list members per account rather than reusing one list across accounts — for a private channel only that channel's members may be posted as.