POST/api/v4/bulk-posts

建立大量貼文

建立一則社群貼文，並透過單一請求將其發布至多個地點。

需要 API 金鑰。標頭格式與金鑰輪替請參閱驗證。

參數

請求主體

標示為必填的巢狀欄位僅在您傳送其上層欄位時適用。如果上層欄位為選填且您省略它，其必填子欄位便不適用。

名稱	類型	必填	說明
input	object	必填	Wrapper object. Every field below is a property of `input`, the entire body must be nested under it.
input.postName	string	必填	Internal name for the campaign (not shown publicly).
input.locationIds	array of strings	必填	Base64-encoded location Relay IDs to publish to.
input.postType	string	必填	One of `EVENT`, `OFFER`, `ANNOUNCEMENT`, `COVID19`, `PRODUCT`.
input.postSites	array of strings	必填	Target publishers: `GOOGLE` and/or `FACEBOOK`.
input.postMessage	array of objects	選填	Per-site post body. Each entry: `site` and `message`.
input.postMessage[].site	string	必填	Publisher for this message: `GOOGLE` or `FACEBOOK`.
input.postMessage[].message	string	必填	Post body text for that site.
input.postMediaUrl	array of objects	選填	Per-site media. Each entry: `site`, `url`, and `type` (`IMAGE` or `VIDEO`).
input.postMediaUrl[].site	string	必填	Publisher for this media asset.
input.postMediaUrl[].url	string	必填	Publicly accessible media URL.
input.postMediaUrl[].type	string	選填	`IMAGE` or `VIDEO`.
input.postCta	array of objects	選填	Per-site call-to-action button. Each entry: `site`, `type`, `url`.
input.postScheduledDates	object	選填	Scheduling window: `startDatetime`, `endDatetime`, and optional `removalSites`. When provided, the post is created with status `SCHEDULED`.
input.postScheduledDates.startDatetime	string	必填	ISO-8601 datetime the post goes live.
input.postScheduledDates.endDatetime	string	必填	ISO-8601 datetime the post is removed.
input.postContextInfo	object	選填	Type-specific details (offer coupon/redeem/terms, or event title/times). Required by `OFFER`, `EVENT`, and `PRODUCT` posts.
input.products	array of objects	選填	Product entries for `PRODUCT` posts (name, price, photo, cta).
input.componentIdentifier	string	選填	Optional client component reference for tracking.
input.componentType	string	選填	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