POST/api/v4/social/posts

Create a social post

Creates a draft, scheduled or immediately published post on a brand's connected Facebook, Instagram, X, LinkedIn and Pinterest accounts.

Requires an API key. See Authentication for header format and key rotation.

Parameters

Body

Name	Type	Required	Description
input	object	required	Wrapper object. Every field below is a property of `input`, the entire body must be nested under it.
input.socialProfileId	string	required	UUID of the brand publishing the post, the same value used as the `brandId` path token elsewhere. Every platform in `platforms` must already have a connection on this brand.
input.name	string	required	Internal name for the post (not shown to the audience). Used to find it again in lists.
input.platforms	array of strings	required	Platforms to publish to: `FACEBOOK`, `INSTAGRAM`, `TWITTER` (X), `LINKEDIN`, `PINTEREST`.
input.content	string	required	The post body, published to every platform in `platforms`.
input.action	string	required	`DRAFT` to save without publishing, `SCHEDULE` to publish at a future time (requires a schedule), or `PUBLISH` to publish now.
input.mediaUrls	array of strings	optional	Public https image URLs to attach. Instagram and Pinterest require at least one.
input.videoUrls	array of strings	optional	Public https video URLs to attach.
input.link	string	optional	Link to attach to the post where the platform supports one.
input.scheduledAt	string	optional	Publish time as an ISO-8601 timestamp with an offset, e.g. `2026-10-02T09:30:00-04:00`. Required when `action` is `SCHEDULE` unless you send `scheduleDate` + `scheduleTime`. Never send both forms.
input.scheduleDate	string	optional	Publish date as `YYYY-MM-DD`, interpreted in the brand's timezone. Must be sent together with `scheduleTime`.
input.scheduleTime	string	optional	Publish time as `HH:MM` (24-hour), interpreted in the brand's timezone. Must be sent together with `scheduleDate`.
input.connectedChannelIds	array of strings	optional	Restrict publishing to specific connections by their `id` from the connections list. Defaults to the brand's active connection for each platform in `platforms`.
input.clientReference	string	optional	Your own identifier for this post, stored and echoed back. Use it to reconcile the post against your own records without holding onto the returned UUID.

Sample request

Ready-to-paste body. Replace placeholder IDs and values with yours.

Request body

{  "input": {    "socialProfileId": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",    "name": "Autumn collection launch",    "platforms": ["INSTAGRAM", "FACEBOOK", "LINKEDIN"],    "content": "Our autumn collection lands today. Solid oak, hand-finished, made two blocks from the shop. Come see it in person this weekend.",    "mediaUrls": ["https://cdn.example.com/social/autumn-collection.jpg"],    "link": "https://jennyhome.example/autumn",    "action": "SCHEDULE",    "scheduleDate": "2026-10-02",    "scheduleTime": "09:30",    "clientReference": "campaign-4471-slot-01"  }}

Responses

200Post accepted. Publishing runs asynchronously, poll GET /social/posts/{postId} for per-channel status.

Response

{  "data": {    "createSimpleSocialMediaPost": {      "success": true,      "error": [],      "socialPostId": "c47a1e58-2b93-4f10-a6d7-58e0c9b12345",      "status": "SCHEDULED"    }  }}

200Validation failed. Nothing was created. The status is still 200: read `success` and the `error` array.

Response

{  "data": {    "createSimpleSocialMediaPost": {      "success": false,      "error": [        {          "message": "SY95045: No connected channel for PINTEREST on this brand",          "code": "SY95045",          "contextInfo": [{ "key": "platform", "value": "PINTEREST" }]        },        {          "message": "SY95046: scheduleTime must be HH:MM in the brand's timezone",          "code": "SY95046",          "contextInfo": null        }      ],      "socialPostId": null,      "status": null    }  }}

401Unauthenticated, missing or invalid API key.

404No brand with that ID on this account (`SY95043`).

Creates one post for one brand across one or more of its connected social accounts. The same call covers all three lifecycles: save a DRAFT, queue a SCHEDULE, or PUBLISH immediately.

Use case: scheduling a campaign from your own calendar. Your app already knows what a client wants to say and when. For each slot, call this endpoint with action: "SCHEDULE" and either scheduledAt or scheduleDate + scheduleTime, and pass your own slot identifier as clientReference so you can reconcile without storing the returned UUID. Show the entry as pending until GET /social/posts/{postId} reports every channel live, and offer a cancel button wired to POST /social/posts/cancel.

Publishing is asynchronous

action: "PUBLISH" does not publish before it answers. The call accepts the post, returns a socialPostId, and hands it to the publishing pipeline. To find out what actually happened, poll GET /social/posts/{postId} and read the per-channel channels[] array: each entry's status is that one platform's outcome. A post can succeed on Instagram and fail on LinkedIn in the same request, so channels[] is the truth and the post-level status is a summary.

Choosing a schedule

action: "SCHEDULE" requires exactly one of two forms, never both:

Form	Fields	Interpreted in
Absolute instant	`scheduledAt`, ISO-8601 with an offset (`2026-10-02T09:30:00-04:00`)	The offset you sent
Local wall-clock	`scheduleDate` (`YYYY-MM-DD`) and `scheduleTime` (`HH:MM`)	The brand's timezone

Sending both, sending scheduleDate without scheduleTime, or sending a scheduledAt with no offset is rejected with SY95046. DRAFT and PUBLISH must not carry a schedule at all.

Notes.

The request body must be wrapped in an input object.
Check success, not the HTTP status. Validation failures come back as HTTP 200 with success: false and one entry in the error array per problem. Nothing is created when success is false.
The brand is identified in the body as socialProfileId. brandId is only ever a URL path token, never a body field.
Every platform in platforms must already have a connection on the brand. A platform with no live channel fails with SY95045; read the brand's connections first, and send the user through a connection link for anything missing.
Platform values are the uppercase enum names FACEBOOK, INSTAGRAM, TWITTER, LINKEDIN, PINTEREST. TWITTER is X; the value kept its old name, and a lowercase value is rejected.
Instagram and Pinterest will not accept a text-only post: supply at least one mediaUrls entry when either is in platforms.
Post IDs are plain UUIDs, not the Base64 relay IDs used by location posts.
For more than a handful of posts in one go, use POST /social/bulk-posts, which takes the same row shape and validates the whole batch up front.

Write operation: not executed against the live account. The request and response shown are built from the API schema; this publishes to real social accounts when run.

Request

curl -X POST 'https://listingsapi.com/api/v4/social/posts' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "socialProfileId": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",      "name": "Autumn collection launch",      "platforms": [        "INSTAGRAM",        "FACEBOOK",        "LINKEDIN"      ],      "content": "Our autumn collection lands today. Solid oak, hand-finished, made two blocks from the shop. Come see it in person this weekend.",      "mediaUrls": [        "https://cdn.example.com/social/autumn-collection.jpg"      ],      "link": "https://jennyhome.example/autumn",      "action": "SCHEDULE",      "scheduleDate": "2026-10-02",      "scheduleTime": "09:30",      "clientReference": "campaign-4471-slot-01"    }  }'

Run in playground