listingsAPIlistingsAPI
Get API keySign in
POST/api/v4/posts

Create an announcement post

Creates an ANNOUNCEMENT social post and publishes it to the chosen sites for one or more locations.

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

Parameters

Body

NameTypeRequiredDescription
postNamestringrequiredInternal name for the campaign (not shown to customers).
locationIdsarray of stringsrequiredBase64-encoded location IDs to publish to (e.g. `TG9jYXRpb246MTgwMDI4OQ==`).
postTypestringrequiredMust be `ANNOUNCEMENT`. One of EVENT, OFFER, ANNOUNCEMENT, COVID19, PRODUCT.
postSitesarray of stringsrequiredSites to publish to: `GOOGLE`, `FACEBOOK`.
postMessagearray of objectsoptionalPer-site body text: `{ site, message }`. Provide one entry per site in `postSites`.
postCtaarray of objectsoptionalOptional call-to-action button per site: `{ site, type, url }`. `type` is one of BOOK, ORDER, SHOP, LEARN_MORE, SIGN_UP, GET_OFFER.
postMediaUrlarray of objectsoptionalOptional media per site: `{ site, url, type }` where `type` is IMAGE or VIDEO.
clientMutationIdstringoptionalOptional client token echoed back in the response for correlation.

Sample request

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

{
  "postName": "Grand Opening Announcement",
  "locationIds": ["TG9jYXRpb246MTgwMDI4OQ=="],
  "postType": "ANNOUNCEMENT",
  "postSites": ["GOOGLE"],
  "postMessage": [
    { "site": "GOOGLE", "message": "We are now open! Visit Jenny Home this week for our grand opening." }
  ],
  "postCta": [
    { "site": "GOOGLE", "type": "LEARN_MORE", "url": "https://jennyhome.example/opening" }
  ],
  "postMediaUrl": [
    { "site": "GOOGLE", "url": "https://cdn.example.com/opening.jpg", "type": "IMAGE" }
  ]
}

Responses

200Post accepted. Publishing runs asynchronously — the returned post starts as INPROGRESS.
{
  "data": {
    "createSocialPost": {
      "clientMutationId": null,
      "success": true,
      "errors": [],
      "socialPost": {
        "id": "U29jaWFsUG9zdDo0NDEyMg==",
        "name": "Grand Opening Announcement",
        "status": "INPROGRESS",
        "type": "ANNOUNCEMENT",
        "createdAt": "2026-06-28",
        "sites": ["GOOGLE"],
        "message": [
          { "site": "GOOGLE", "message": "We are now open! Visit Jenny Home this week for our grand opening." }
        ],
        "cta": [
          { "type": { "value": "LEARN_MORE", "label": "Learn more" }, "url": "https://jennyhome.example/opening", "site": "GOOGLE", "tinyUrl": null }
        ],
        "contextInfo": null,
        "mediaUrl": [
          { "url": "https://cdn.example.com/opening.jpg", "site": "GOOGLE", "type": "IMAGE" }
        ],
        "publishDetails": [
          { "site": "GOOGLE", "status": "PUBLISHING", "createdDate": "2026-06-28", "submissionError": null }
        ],
        "postLinks": [],
        "locationIds": [1800289]
      }
    }
  }
}
401Unauthenticated — missing or invalid API key.

Creates an announcement — the simplest post type. An announcement carries a plain message (and optional CTA and image) with no event dates or offer details. Pass postType: "ANNOUNCEMENT" and one postMessage entry per site in postSites.

Use case — "We're open" across your storefronts. Announce a grand opening or new hours to Google (and Facebook) for a set of locations in one call. Provide a LEARN_MORE CTA linking to your site and an image for a richer card. The call returns immediately with status: INPROGRESS; poll GET /posts/{postId} with the returned socialPost.id until it reads SUCCESS, and read publishDetails[].submissionError if any site fails.

Notes.

  • The request body is sent flat — the fields (postName, locationIds, postType, postSites, …) are top-level, not wrapped in an input object.
  • postSites and each postMessage.site use the site enum (GOOGLE, FACEBOOK); provide a message entry for every site you target.
  • To publish the same announcement to many locations, either pass every ID in locationIds here, or use POST /bulk-posts for large multi-location rollouts.
  • For dated posts use events; for coupons/discounts use offers.

Write operation — not executed against the live account. The request and response shown are built from the API schema; this posts to real Google/Facebook profiles when run.

curl -X POST 'https://listingsapi.com/api/v4/posts' \
  -H "Authorization: API $LISTINGSAPI_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "postName": "<postName>",
    "locationIds": "<locationIds>",
    "postType": "<postType>",
    "postSites": "<postSites>",
    "postMessage": "<postMessage>",
    "postCta": "<postCta>",
    "postMediaUrl": "<postMediaUrl>",
    "clientMutationId": "<clientMutationId>"
  }'
Run in playground