Listings APIListings API
Accedi
POST/api/v4/bulk-posts

Crea un post in blocco

Crea un unico post social e lo pubblica su più sedi con una sola richiesta.

Richiede una chiave API. Consulta Autenticazione per il formato dell’header e la rotazione delle chiavi.

Parametri

Corpo

Un campo annidato contrassegnato come obbligatorio si applica solo quando invii il campo padre. Se il padre è facoltativo e lo ometti, i suoi campi figli obbligatori non si applicano.

NomeTipoObbligatorioDescrizione
inputobjectobbligatorioWrapper object. Every field below is a property of `input`, the entire body must be nested under it.
input.postNamestringobbligatorioInternal name for the campaign (not shown publicly).
input.locationIdsarray of stringsobbligatorioBase64-encoded location Relay IDs to publish to.
input.postTypestringobbligatorioOne of `EVENT`, `OFFER`, `ANNOUNCEMENT`, `COVID19`, `PRODUCT`.
input.postSitesarray of stringsobbligatorioTarget publishers: `GOOGLE` and/or `FACEBOOK`.
input.postMessagearray of objectsfacoltativoPer-site post body. Each entry: `site` and `message`.
input.postMessage[].sitestringobbligatorioPublisher for this message: `GOOGLE` or `FACEBOOK`.
input.postMessage[].messagestringobbligatorioPost body text for that site.
input.postMediaUrlarray of objectsfacoltativoPer-site media. Each entry: `site`, `url`, and `type` (`IMAGE` or `VIDEO`).
input.postMediaUrl[].sitestringobbligatorioPublisher for this media asset.
input.postMediaUrl[].urlstringobbligatorioPublicly accessible media URL.
input.postMediaUrl[].typestringfacoltativo`IMAGE` or `VIDEO`.
input.postCtaarray of objectsfacoltativoPer-site call-to-action button. Each entry: `site`, `type`, `url`.
input.postScheduledDatesobjectfacoltativoScheduling window: `startDatetime`, `endDatetime`, and optional `removalSites`. When provided, the post is created with status `SCHEDULED`.
input.postScheduledDates.startDatetimestringobbligatorioISO-8601 datetime the post goes live.
input.postScheduledDates.endDatetimestringobbligatorioISO-8601 datetime the post is removed.
input.postContextInfoobjectfacoltativoType-specific details (offer coupon/redeem/terms, or event title/times). Required by `OFFER`, `EVENT`, and `PRODUCT` posts.
input.productsarray of objectsfacoltativoProduct entries for `PRODUCT` posts (name, price, photo, cta).
input.componentIdentifierstringfacoltativoOptional client component reference for tracking.
input.componentTypestringfacoltativoOptional client component type for tracking.

Richiesta di esempio

Corpo pronto da incollare. Sostituisci gli ID e i valori segnaposto con i tuoi.

Request body
{  "input": {    "postName": "July Reopening Announcement",    "locationIds": [      "TG9jYXRpb246MTgwMDI4OQ==",      "TG9jYXRpb246MTgwMDI5MA=="    ],    "postType": "ANNOUNCEMENT",    "postSites": ["GOOGLE", "FACEBOOK"],    "postMessage": [      { "site": "GOOGLE", "message": "We're back! Visit us this week for our summer menu." },      { "site": "FACEBOOK", "message": "We're back! Swing by for the new summer menu." }    ],    "postMediaUrl": [      { "site": "GOOGLE", "url": "https://cdn.example.com/summer.jpg", "type": "IMAGE" }    ],    "postScheduledDates": {      "startDatetime": "2026-07-10T09:00:00Z",      "endDatetime": "2026-07-24T23:59:00Z"    }  }}

Risposte

200Bulk post accepted. `success` is true and the created campaign is returned. Note the response is keyed under `createSocialPost`: the bulk endpoint returns the same response shape as `POST /posts`.
Response
{  "data": {    "createSocialPost": {      "clientMutationId": null,      "success": true,      "errors": null,      "socialPost": {        "id": "U29jaWFsUG9zdDo5OTIwMQ==",        "name": "July Reopening Announcement",        "status": "SCHEDULED",        "type": "ANNOUNCEMENT",        "createdAt": "2026-07-08",        "scheduledStartDate": "2026-07-10",        "scheduledEndDate": "2026-07-24",        "sites": ["GOOGLE", "FACEBOOK"],        "locationIds": [1800289, 1800290]      }    }  }}
400Bad request, the body was not wrapped in `input` (error message: `Variable "$input" of required type ... was not provided`).
401Unauthenticated, missing or invalid API key.

Crea una campagna con un unico post e lo distribuisce a ogni sede in locationIds, pubblicandolo su postSites selezionati. A differenza della creazione per singola sede, una sola chiamata interessa tutte le tue sedi, consentendoti di gestire in modo efficiente un annuncio, un'offerta o un evento per l'intera azienda.

Struttura della richiesta. L'intero corpo deve essere racchiuso in un oggetto input; ogni campo (postName, locationIds, postType, …) è una proprietà di input. Un corpo piatto, senza oggetto contenitore, viene rifiutato con uno stato HTTP 400 (Variable "$input" of required type ... was not provided). Il contratto è lo stesso di POST /posts e una risposta riuscita usa la chiave createSocialPost anziché una chiave specifica per le operazioni in blocco.

Caso d'uso: annuncio per l'intera azienda (mostrato sopra). Imposta postType: "ANNOUNCEMENT", elenca gli ID delle sedi e fornisci un postMessage per sito. Aggiungi postScheduledDates per pubblicare il post durante un intervallo prestabilito (il post viene quindi creato con lo stato SCHEDULED); omettilo per pubblicare immediatamente.

Caso d'uso: un'offerta a tempo limitato in tutti i negozi. Modifica postType in OFFER e fornisci il coupon in postContextInfo (sempre all'interno di input):

JSON
{  "input": {    "postName": "Summer 20% Off",    "locationIds": ["TG9jYXRpb246MTgwMDI4OQ=="],    "postType": "OFFER",    "postSites": ["GOOGLE"],    "postMessage": [{ "site": "GOOGLE", "message": "20% off through July!" }],    "postContextInfo": {      "title": "Summer Sale",      "couponCode": "SUMMER20",      "redeemUrl": "https://example.com/offer",      "termsConditions": "Valid through July 31",      "startDay": "2026-07-10",      "startTime": "09:00",      "endDay": "2026-07-31",      "endTime": "23:59"    }  }}

Aspetti a cui prestare attenzione.

  • Il corpo deve essere racchiuso in input; se invii i campi al livello principale, viene restituito uno stato HTTP 400.
  • postType, postSites, postName e locationIds sono obbligatori; i tipi EVENT, OFFER e PRODUCT richiedono anche i campi postContextInfo (o products) corrispondenti.
  • postSites accetta solo GOOGLE e FACEBOOK; le sedi di destinazione devono avere il canale corrispondente collegato, altrimenti il sito viene saltato.
  • In caso di errore di validazione parziale o totale, la risposta restituisce HTTP 200 con success: false e un array errors popolato; controlla success, quindi monitora la pubblicazione effettiva per ciascuna sede tramite l'endpoint per il recupero del post in blocco.
Request
curl -X POST 'https://listingsapi.com/api/v4/bulk-posts' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "postName": "July Reopening Announcement",      "locationIds": [        "TG9jYXRpb246MTgwMDI4OQ==",        "TG9jYXRpb246MTgwMDI5MA=="      ],      "postType": "ANNOUNCEMENT",      "postSites": [        "GOOGLE",        "FACEBOOK"      ],      "postMessage": [        {          "site": "GOOGLE",          "message": "We're back! Visit us this week for our summer menu."        },        {          "site": "FACEBOOK",          "message": "We're back! Swing by for the new summer menu."        }      ],      "postMediaUrl": [        {          "site": "GOOGLE",          "url": "https://cdn.example.com/summer.jpg",          "type": "IMAGE"        }      ],      "postScheduledDates": {        "startDatetime": "2026-07-10T09:00:00Z",        "endDatetime": "2026-07-24T23:59:00Z"      }    }  }'
Run in playground