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

Create an event post

Creates an EVENT social post with a title and start/end window, published 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 `EVENT`. One of EVENT, OFFER, ANNOUNCEMENT, COVID19, PRODUCT.
postSitesarray of stringsrequiredSites to publish to: `GOOGLE`, `FACEBOOK`.
postContextInfoobjectoptionalEvent details: `{ title, startDay, startTime, endDay, endTime }`. `title` is required by Google for events; `startDay`/`endDay` are dates, `startTime`/`endTime` are display strings like `10:00am`.
postMessagearray of objectsoptionalPer-site body text: `{ site, message }`. One entry per site in `postSites`.
postScheduledDatesobjectoptionalWhen to publish/expire the post itself: `{ startDatetime, endDatetime, removalSites }`. Distinct from the event's own dates in `postContextInfo`.
postCtaarray of objectsoptionalOptional call-to-action 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": "Summer Sale Kickoff Event",
  "locationIds": ["TG9jYXRpb246MTgwMDI4OQ=="],
  "postType": "EVENT",
  "postSites": ["GOOGLE"],
  "postContextInfo": {
    "title": "Summer Sale Kickoff",
    "startDay": "2026-07-15",
    "startTime": "10:00am",
    "endDay": "2026-07-15",
    "endTime": "06:00pm"
  },
  "postMessage": [
    { "site": "GOOGLE", "message": "Join us for the Summer Sale kickoff — refreshments, giveaways, and up to 40% off in store." }
  ],
  "postCta": [
    { "site": "GOOGLE", "type": "LEARN_MORE", "url": "https://jennyhome.example/summer-event" }
  ],
  "postMediaUrl": [
    { "site": "GOOGLE", "url": "https://cdn.example.com/summer-event.jpg", "type": "IMAGE" }
  ]
}

Responses

200Post accepted. Publishing runs asynchronously — the returned post starts as INPROGRESS.
{
  "data": {
    "createSocialPost": {
      "clientMutationId": null,
      "success": true,
      "errors": [],
      "socialPost": {
        "id": "U29jaWFsUG9zdDo0NDEyMw==",
        "name": "Summer Sale Kickoff Event",
        "status": "INPROGRESS",
        "type": "EVENT",
        "createdAt": "2026-07-01",
        "scheduledStartDate": "2026-07-15",
        "scheduledEndDate": "2026-07-15",
        "sites": ["GOOGLE"],
        "message": [
          { "site": "GOOGLE", "message": "Join us for the Summer Sale kickoff — refreshments, giveaways, and up to 40% off in store." }
        ],
        "cta": [
          { "type": { "value": "LEARN_MORE", "label": "Learn more" }, "url": "https://jennyhome.example/summer-event", "site": "GOOGLE", "tinyUrl": null }
        ],
        "contextInfo": {
          "title": "Summer Sale Kickoff",
          "startDay": "2026-07-15",
          "startTime": "10:00am",
          "endDay": "2026-07-15",
          "endTime": "06:00pm",
          "couponCode": null,
          "redeemUrl": null,
          "termsConditions": null,
          "discount": null,
          "locationType": null
        },
        "mediaUrl": [
          { "url": "https://cdn.example.com/summer-event.jpg", "site": "GOOGLE", "type": "IMAGE" }
        ],
        "publishDetails": [
          { "site": "GOOGLE", "status": "PUBLISHING", "createdDate": "2026-07-01", "submissionError": null }
        ],
        "postLinks": [],
        "locationIds": [1800289]
      }
    }
  }
}
401Unauthenticated — missing or invalid API key.

Creates an event post — a dated announcement with a title and a start/end window that renders as an event card on Google. The event's own schedule lives in postContextInfo (title, startDay, startTime, endDay, endTime); the optional postScheduledDates controls when the post itself is published and retired, which is usually the run-up to the event.

Use case — promote an in-store event. Announce a "Summer Sale Kickoff" for Jenny Home with the event window on July 15 and a LEARN_MORE CTA to the event page. Set postType: "EVENT" and fill postContextInfo.title — Google rejects events without a title. The call returns status: INPROGRESS; confirm with GET /posts/{postId} that it reaches SUCCESS.

Notes.

  • The body is sent flat (top-level fields, no input wrapper).
  • postContextInfo holds the event dates; postScheduledDates holds the publishing dates. Use postScheduledDates.startDatetime/endDatetime to schedule the post ahead of time and auto-expire it after the event.
  • Provide a postMessage entry for each site in postSites.
  • For a plain message with no dates use announcements; 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>",
    "postContextInfo": "<postContextInfo>",
    "postMessage": "<postMessage>",
    "postScheduledDates": "<postScheduledDates>",
    "postCta": "<postCta>",
    "postMediaUrl": "<postMediaUrl>",
    "clientMutationId": "<clientMutationId>"
  }'
Run in playground