v1Resources/Posts/postCreate a post
Create a post
Creates a post for a location or client and submits it to the selected platforms. This publishes real content: unless scheduledFor is set or draft is true, the post goes live on its target platforms immediately. A requested platform with no active connection, or a post missing a field required to go live, never fails the call — the content is saved as a draft instead; see the response schema for how that's reported.
post
posts:write/api/v1/postsRequest body
locationIdstringoptional
The location to post to. Provide this or clientId.
clientIdstringoptional
The client to post to at brand level. Provide this or locationId.
namestringrequired
Internal name/label for the post. Required, non-empty.
postTypestring (announcement | event | offer)optional
Post type. event and offer are Google-only.
platformsarray of string (google | facebook | instagram | x | linkedin | pinterest | mastodon | bluesky | threads | tiktok | youtube | reddit | medium | substack | vimeo | dailymotion)optional
Target platforms. Send this or connectionIds. Each platform publishes through the location's connection for it (or the client's, for a brand-level post).
connectionIdsarray of stringoptional
Exact targets: the connection ids to publish to, from GET /api/v1/locations/{id}/publish-targets. Use a location's own connection or its client's brand-level page; a Google account-level connection, an archived one, or one from another location or client is rejected with 422. When sent, the post goes to exactly these and platforms is taken from them. On update, the list replaces the post's targets.
linkUrlstringoptional
The post's main link, used by every platform that shows one.
linkCtaKeystringoptional
The button shown with linkUrl, e.g. learn_more, book or shop.
utmobjectoptional
UTM tags (source, medium, campaign, term) added to linkUrl.
sourcestringoptional
mediumstringoptional
campaignstringoptional
termstringoptional
linkOverrideobjectoptional
Per-platform link settings keyed by platform: a different url, button, title, description or utm for that platform.
linkAppendobjectoptional
Whether to add linkUrl to the end of the caption on X and Mastodon, which have no link field.
xbooleanoptional
mastodonbooleanoptional
ctaUrlFacebookstringoptional
Facebook-only button URL, when it should differ from ctaUrl.
xThreadbooleanoptional
On X, split a caption longer than one post into a thread.
scheduleLocalTimestringoptional
Schedule by local wall-clock time, "YYYY-MM-DDTHH:mm" with no zone. Use instead of scheduledFor for zone-aware scheduling.
scheduleZoneModestring (target_local | fixed_zone)optional
How scheduleLocalTime is read: target_local publishes at that time in each target's own time zone; fixed_zone uses scheduleTimeZone for every target.
scheduleTimeZonestringoptional
IANA time zone for fixed_zone scheduling, e.g. "America/New_York".
timeZoneModestring (target_local | fixed_zone)optional
Same as scheduleZoneMode.
articleTitlestringoptional
Article fields for Medium and Substack: title, subtitle and HTML body.
articleSubtitlestringoptional
Article fields for Medium and Substack: title, subtitle and HTML body.
articleBodyHtmlstringoptional
Article fields for Medium and Substack: title, subtitle and HTML body.
canonicalUrlstringoptional
Original URL of an article published elsewhere, so the platform credits the source.
videoCoverUrlstringoptional
Video options: a cover image URL, and a captions file URL with its language.
videoCaptionsUrlstringoptional
Video options: a cover image URL, and a captions file URL with its language.
videoCaptionsLanguagestringoptional
Video options: a cover image URL, and a captions file URL with its language.
facebookCaptionstringoptional
A Facebook-only option: caption override, button type, first comment, publish format (default, reel, carousel, suppress_link), carousel cards, or audience targeting.
facebookCtaTypestringoptional
A Facebook-only option: caption override, button type, first comment, publish format (default, reel, carousel, suppress_link), carousel cards, or audience targeting.
facebookFirstCommentstringoptional
A Facebook-only option: caption override, button type, first comment, publish format (default, reel, carousel, suppress_link), carousel cards, or audience targeting.
facebookPublishAsstring (default | reel | carousel | suppress_link)optional
A Facebook-only option: caption override, button type, first comment, publish format (default, reel, carousel, suppress_link), carousel cards, or audience targeting.
facebookCarouselCardsarray of objectoptional
A Facebook-only option: caption override, button type, first comment, publish format (default, reel, carousel, suppress_link), carousel cards, or audience targeting.
headlinestringoptional
descriptionstringoptional
linkstringoptional
facebookTargetCountrystringoptional
A Facebook-only option: caption override, button type, first comment, publish format (default, reel, carousel, suppress_link), carousel cards, or audience targeting.
facebookTargetGenderstringoptional
A Facebook-only option: caption override, button type, first comment, publish format (default, reel, carousel, suppress_link), carousel cards, or audience targeting.
facebookTargetAgeMinstringoptional
A Facebook-only option: caption override, button type, first comment, publish format (default, reel, carousel, suppress_link), carousel cards, or audience targeting.
facebookTargetAgeMaxstringoptional
A Facebook-only option: caption override, button type, first comment, publish format (default, reel, carousel, suppress_link), carousel cards, or audience targeting.
facebookTargetRelationshipstringoptional
A Facebook-only option: caption override, button type, first comment, publish format (default, reel, carousel, suppress_link), carousel cards, or audience targeting.
instagramFirstCommentstringoptional
An Instagram-only option: first comment or image alt text.
instagramAltTextstringoptional
An Instagram-only option: first comment or image alt text.
xReplySettingsstring (everyone | following | mentioned)optional
An X-only option: who can reply.
linkedinVisibilitystring (anyone | connections | followers)optional
A LinkedIn-only option: visibility or first comment.
linkedinFirstCommentstringoptional
A LinkedIn-only option: visibility or first comment.
pinterestTitlestringoptional
A Pinterest-only option: pin title, board, destination link or alt text.
pinterestBoardIdstringoptional
A Pinterest-only option: pin title, board, destination link or alt text.
pinterestBoardNamestringoptional
A Pinterest-only option: pin title, board, destination link or alt text.
pinterestLinkstringoptional
A Pinterest-only option: pin title, board, destination link or alt text.
pinterestAltTextstringoptional
A Pinterest-only option: pin title, board, destination link or alt text.
tiktokPrivacyLevelstring (PUBLIC_TO_EVERYONE | MUTUAL_FOLLOW_FRIENDS | SELF_ONLY)optional
A TikTok-only option: privacy level, whether duets, stitches and comments are allowed, or branded content.
tiktokDisableDuetbooleanoptional
A TikTok-only option: privacy level, whether duets, stitches and comments are allowed, or branded content.
tiktokDisableStitchbooleanoptional
A TikTok-only option: privacy level, whether duets, stitches and comments are allowed, or branded content.
tiktokDisableCommentbooleanoptional
A TikTok-only option: privacy level, whether duets, stitches and comments are allowed, or branded content.
tiktokBrandContentbooleanoptional
A TikTok-only option: privacy level, whether duets, stitches and comments are allowed, or branded content.
mastodonVisibilitystring (public | unlisted | private | direct)optional
A Mastodon-only option: visibility, content warning, or sensitive media.
mastodonSpoilerTextstringoptional
A Mastodon-only option: visibility, content warning, or sensitive media.
mastodonSensitivebooleanoptional
A Mastodon-only option: visibility, content warning, or sensitive media.
blueskyLanguagestringoptional
A Bluesky-only option: post language or who can reply.
blueskyReplyGatingstring (everyone | mentioned | following | nobody)optional
A Bluesky-only option: post language or who can reply.
threadsReplyControlstring (everyone | accounts_you_follow | mentioned_only)optional
A Threads-only option: who can reply.
redditSubredditstringoptional
A Reddit-only option: subreddit, title, post type, link or flair.
redditTitlestringoptional
A Reddit-only option: subreddit, title, post type, link or flair.
redditPostTypestring (text | link | image | video)optional
A Reddit-only option: subreddit, title, post type, link or flair.
redditUrlstringoptional
A Reddit-only option: subreddit, title, post type, link or flair.
redditFlairstringoptional
A Reddit-only option: subreddit, title, post type, link or flair.
mediumTagsstringoptional
A Medium-only option: tags or publish status.
mediumPublishStatusstring (public | unlisted | draft)optional
A Medium-only option: tags or publish status.
substackSendEmailbooleanoptional
A Substack-only option: whether to email subscribers.
vimeoTitlestringoptional
A Vimeo-only option: title, description, thumbnail or privacy.
vimeoDescriptionstringoptional
A Vimeo-only option: title, description, thumbnail or privacy.
vimeoThumbnailUrlstringoptional
A Vimeo-only option: title, description, thumbnail or privacy.
vimeoPrivacystring (anybody | unlisted)optional
A Vimeo-only option: title, description, thumbnail or privacy.
dailymotionTitlestringoptional
A Dailymotion-only option: title, description, thumbnail, category, made-for-kids flag or privacy.
dailymotionDescriptionstringoptional
A Dailymotion-only option: title, description, thumbnail, category, made-for-kids flag or privacy.
dailymotionThumbnailUrlstringoptional
A Dailymotion-only option: title, description, thumbnail, category, made-for-kids flag or privacy.
dailymotionCategorystringoptional
A Dailymotion-only option: title, description, thumbnail, category, made-for-kids flag or privacy.
dailymotionIsForKidsbooleanoptional
A Dailymotion-only option: title, description, thumbnail, category, made-for-kids flag or privacy.
dailymotionPrivacystring (public | private)optional
A Dailymotion-only option: title, description, thumbnail, category, made-for-kids flag or privacy.
messageGooglestringoptional
Caption for Google. Required when google is selected, unless draft.
messageFacebookstringoptional
Shared caption for the social platforms (Facebook, Instagram, X, LinkedIn and the others). Required when any of them is selected, except a TikTok-only or YouTube-only selection, unless the post is a draft. Not used by Google, which takes messageGoogle.
captionOverridesobjectoptional
Captions that replace the shared caption on one network only, keyed by network: facebook, instagram, linkedin, x, bluesky, mastodon, threads, pinterest (the pin description), tiktok and youtube (the video description). Each is checked against its own network's limit. On update, only the networks you name change; send null or an empty string for one to go back to the shared caption, or null for the whole field to clear them all. Other networks are refused, because they publish the shared caption.
facebookstringoptional
instagramstringoptional
linkedinstringoptional
xstringoptional
blueskystringoptional
mastodonstringoptional
threadsstringoptional
pintereststringoptional
tiktokstringoptional
youtubestringoptional
ctaTypestring (learn_more | sign_up | order_online | book | buy | call_now)optional
Call-to-action type.
ctaUrlstringoptional
Call-to-action destination URL.
mediaUrlsarray of objectoptional
Media to attach, one entry per platform attachment.
urlstringoptional
platformstringoptional
typestring (image | video)optional
eventTitlestringoptional
Event or offer title. Required for a Google event/offer, unless draft.
eventStartAtstringoptional
Event or offer start time, as an ISO 8601 timestamp. Required for a Google event/offer, unless draft.
eventEndAtstringoptional
Event or offer end time, as an ISO 8601 timestamp. Must be after the start.
offerTermsstringoptional
Offer terms.
offerCouponCodestringoptional
Offer coupon code.
offerRedeemUrlstringoptional
Offer redemption URL.
scheduledForstringoptional
Publish at this future ISO 8601 timestamp instead of immediately.
draftbooleanoptional
Save without publishing. Skips required-field checks; structural checks (limits, media rules) still apply.
Response
dataobjectoptional
A requested platform with no active connection, or a required field the post needs before it can go live, never fails this call — the post is still saved. When either gap exists, status is "no_connection" or "incomplete" and the post rides underneath as post.{id,status}; on a clean publish the top-level id/status describe the post directly.
idstringoptional
Unique identifier for the post.
statusstringoptional
Lifecycle status of the post: draft, scheduled, paused, publishing, active, partial (live on some platforms, failed on others), error, deleted, or expired.
missingFieldsarray of stringoptional
Fields still needed before this post can go live, if any.
missingPlatformsarray of stringoptional
Requested platforms with no active connection, if any.
scopestring (location | client)optional
Whether the connection/field gap applies at the location or client level.
postobjectoptional
The post that was created or updated.
idstringoptional
Unique identifier for the post.
statusstringoptional
Lifecycle status of the post: draft, scheduled, paused, publishing, active, partial (live on some platforms, failed on others), error, deleted, or expired.
targetsarray of objectoptional
One entry per destination of the post, with its own status.
connectionIdstringoptional
The connection this destination publishes through.
platformstringoptional
The destination's platform.
statusstringoptional
Status of this platform submission: pending, publishing, action_required (the platform needs the user to act), active, error, deleted, or expired.
errorobjectoptional
Present when this destination failed: Synup's error code and message.
codestringoptional
messagestringoptional
Errors
400The request is missing a required parameter or is otherwise malformed.
401Missing, invalid, expired, or revoked API key.
403The key lacks the required scope, or isn't authorized for this client/location.
422The request is missing a required parameter or is otherwise malformed.
429Too many requests. Retry after the number of seconds in the Retry-After header.
post/api/v1/posts
Your API key
Request body*
{
"data": {
"id": "cm_post_abc123",
"status": "scheduled"
}
}Guides that use this endpoint
- How to Add Local Marketing Features to Your SaaSAdd listings management, reviews, Google posts, profile analytics, rank tracking and AI visibility to a SaaS product with the Synup API, tenant by tenant.
- How to Add Local Marketing Functionality to Vertical SaaSAdd local marketing to a vertical SaaS by mapping existing customers to clients and locations, and shipping only the features your niche needs.
- How to Publish Google Business Profile Posts ProgrammaticallyPublish announcements, offers and events to Google Business Profile via API, schedule them, handle the missing-connection draft, and measure post performance.
- Publish a Google Business Profile Post via APIPublish an announcement, offer or event to a location's connected platforms, and handle the draft returned when a platform is not connected.