Listings APIListings API
Iniciar sesión
POST/api/v4/posts

Crear una publicación de anuncio

Crea una publicación social de tipo ANNOUNCEMENT y la publica en los sitios elegidos para una o más ubicaciones.

Requiere una clave de API. Consulta Autenticación para conocer el formato del encabezado y la rotación de claves.

Parámetros

Cuerpo

NombreTipoObligatorioDescripción
inputobjectobligatorioWrapper object. Every field below is a property of `input`, the entire body must be nested under it.
input.postNamestringobligatorioInternal name for the campaign (not shown to customers).
input.locationIdsarray of stringsobligatorioBase64-encoded location IDs to publish to (e.g. `TG9jYXRpb246MTgwMDI4OQ==`).
input.postTypestringobligatorioMust be `ANNOUNCEMENT`. One of EVENT, OFFER, ANNOUNCEMENT, COVID19, PRODUCT.
input.postSitesarray of stringsobligatorioSites to publish to: `GOOGLE`, `FACEBOOK`.
input.postMessagearray of objectsopcionalPer-site body text: `{ site, message }`. Provide one entry per site in `postSites`.
input.postCtaarray of objectsopcionalOptional 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 objectsopcionalOptional media per site: `{ site, url, type }` where `type` is IMAGE or VIDEO.
input.clientMutationIdstringopcionalOptional client token returned unchanged in the response for correlation.

Solicitud de ejemplo

Cuerpo listo para pegar. Sustituye los ID y valores de ejemplo por los tuyos.

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" }    ]  }}

Respuestas

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` (error message: `Variable "$input" of required type "CreateSocialPostMutationInput!" was not provided`).
401Unauthenticated, missing or invalid API key.

Crea un anuncio: el tipo de publicación más sencillo. Un anuncio contiene un mensaje sencillo (y, opcionalmente, una CTA y una imagen), sin fechas de evento ni detalles de oferta. Pasa postType: "ANNOUNCEMENT" y una entrada postMessage por sitio en postSites.

Caso de uso: «Estamos abiertos» en tus establecimientos. Anuncia una gran inauguración o un nuevo horario en Google (y Facebook) para un conjunto de ubicaciones en una sola llamada. Proporciona una CTA de tipo LEARN_MORE que enlace a tu sitio y una imagen para crear una tarjeta más completa. La llamada devuelve inmediatamente status: INPROGRESS; consulta periódicamente GET /posts/{postId} con el socialPost.id devuelto hasta que indique SUCCESS, y consulta publishDetails[].submissionError si falla algún sitio.

Notas.

  • El cuerpo de la solicitud debe estar envuelto en un objeto input: cada campo (postName, locationIds, postType, postSites, …) es una propiedad de input. Un cuerpo plano, sin envolver, se rechaza con un estado HTTP 400 (Variable "$input" of required type "CreateSocialPostMutationInput!" was not provided).
  • postSites y cada postMessage.site usan la enumeración de sitios (GOOGLE, FACEBOOK); proporciona una entrada de mensaje para cada sitio de destino.
  • Para publicar el mismo anuncio en muchas ubicaciones, pasa todos los ID en locationIds aquí, o usa POST /bulk-posts para publicaciones a gran escala en múltiples ubicaciones.
  • Para publicaciones con fechas, usa eventos; para cupones o descuentos, usa ofertas.

Operación de escritura: no se ha ejecutado en la cuenta real. La solicitud y la respuesta mostradas se han generado a partir del esquema de la API; al ejecutarse, esta operación publica en perfiles reales de Google/Facebook.

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