Listings APIListings API
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
inputobjectrequiredWrapper object. Every field below is a property of `input`, the entire body must be nested under it.
input.postNamestringrequiredInternal name for the campaign (not shown to customers).
input.locationIdsarray of stringsrequiredBase64-encoded location IDs to publish to (e.g. `TG9jYXRpb246MTgwMDI4OQ==`).
input.postTypestringrequiredMust be `ANNOUNCEMENT`. One of EVENT, OFFER, ANNOUNCEMENT, COVID19, PRODUCT.
input.postSitesarray of stringsrequiredSites to publish to: `GOOGLE`, `FACEBOOK`.
input.postMessagearray of objectsoptionalPer-site body text: `{ site, message }`. Provide one entry per site in `postSites`.
input.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.
input.postMediaUrlarray of objectsoptionalOptional media per site: `{ site, url, type }` where `type` is IMAGE or VIDEO.
input.clientMutationIdstringoptionalOptional client token echoed back in the response for correlation.

Sample request

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

Request body
{  "input": {    "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.
Response
{  "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]      }    }  }}
400Bad request, the body was not wrapped in `input` (GraphQL: `Variable "$input" of required type "CreateSocialPostMutationInput!" was not provided`).
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 must be wrapped in an input object: every field (postName, locationIds, postType, postSites, …) is a property of input. A flat, unwrapped body is rejected with an HTTP 400 (Variable "$input" of required type "CreateSocialPostMutationInput!" was not provided).
  • 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.

Request
curl -X POST 'https://listingsapi.com/api/v4/posts' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "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"        }      ]    }  }'
Run in playground