Listings APIListings API
登录
POST/api/v4/bulk-posts

创建批量帖子

创建一条社交帖子，并在一次请求中将其发布到多个地点。

需要 API 密钥。请求头格式和密钥轮换请参阅身份验证。

参数

请求体

标记为必填的嵌套字段仅在您发送其父字段时适用。如果父字段为可选且您省略了它，其必填子字段不适用。

名称类型必填描述
inputobject必填Wrapper object. Every field below is a property of `input`, the entire body must be nested under it.
input.postNamestring必填Internal name for the campaign (not shown publicly).
input.locationIdsarray of strings必填Base64-encoded location Relay IDs to publish to.
input.postTypestring必填One of `EVENT`, `OFFER`, `ANNOUNCEMENT`, `COVID19`, `PRODUCT`.
input.postSitesarray of strings必填Target publishers: `GOOGLE` and/or `FACEBOOK`.
input.postMessagearray of objects可选Per-site post body. Each entry: `site` and `message`.
input.postMessage[].sitestring必填Publisher for this message: `GOOGLE` or `FACEBOOK`.
input.postMessage[].messagestring必填Post body text for that site.
input.postMediaUrlarray of objects可选Per-site media. Each entry: `site`, `url`, and `type` (`IMAGE` or `VIDEO`).
input.postMediaUrl[].sitestring必填Publisher for this media asset.
input.postMediaUrl[].urlstring必填Publicly accessible media URL.
input.postMediaUrl[].typestring可选`IMAGE` or `VIDEO`.
input.postCtaarray of objects可选Per-site call-to-action button. Each entry: `site`, `type`, `url`.
input.postScheduledDatesobject可选Scheduling window: `startDatetime`, `endDatetime`, and optional `removalSites`. When provided, the post is created with status `SCHEDULED`.
input.postScheduledDates.startDatetimestring必填ISO-8601 datetime the post goes live.
input.postScheduledDates.endDatetimestring必填ISO-8601 datetime the post is removed.
input.postContextInfoobject可选Type-specific details (offer coupon/redeem/terms, or event title/times). Required by `OFFER`, `EVENT`, and `PRODUCT` posts.
input.productsarray of objects可选Product entries for `PRODUCT` posts (name, price, photo, cta).
input.componentIdentifierstring可选Optional client component reference for tracking.
input.componentTypestring可选Optional client component type for tracking.

请求示例

可直接粘贴的请求体。请将占位 ID 和值替换为您自己的。

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

响应

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.

创建一个帖子营销活动，并将其分发到 locationIds 中的每个地点，发布到所选的 postSites。与按地点创建不同，一次调用即可覆盖您的所有地点，是发布全公司公告、优惠或活动的高效方式。

请求结构。 整个请求体必须封装在一个 input 对象中，每个字段（postName、locationIds、postType 等）都是 input 的属性。未封装的扁平请求体会被拒绝，并返回 HTTP 400（Variable "$input" of required type ... was not provided）。这与 POST /posts 的约定相同，成功响应的内容位于 createSocialPost 键下，而非批量操作专用的键下。

使用场景：全公司公告（如上所示）。 设置 postType: "ANNOUNCEMENT"，列出地点 ID，并为每个站点提供一个 postMessage。添加 postScheduledDates 可让帖子在固定时间段内发布（此时创建的帖子状态为 SCHEDULED）；省略该字段则立即发布。

使用场景：所有门店的限时优惠。 将 postType 改为 OFFER，并在 postContextInfo 中提供优惠券（仍需封装在 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"    }  }}

注意事项。

  • 请求体必须封装在 input 中；在顶层发送这些字段会返回 HTTP 400。
  • postType、postSites、postName 和 locationIds 为必填项；EVENT、OFFER 和 PRODUCT 类型还需要对应的 postContextInfo（或 products）字段。
  • postSites 仅接受 GOOGLE 和 FACEBOOK；目标地点必须已连接相应渠道，否则会跳过该站点。
  • 部分或全部验证失败时，响应会返回 HTTP 200，并包含 success: false 和非空的 errors 数组，请检查 success，然后使用获取批量帖子的端点按地点跟踪实时发布情况。
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