POST/api/v4/bulk-posts

Membuat unggahan massal

Membuat satu unggahan media sosial dan memublikasikannya di banyak lokasi dalam satu permintaan.

Memerlukan kunci API. Lihat Autentikasi untuk format header dan rotasi kunci.

Parameter

Body

Field bersarang yang ditandai wajib hanya berlaku jika Anda mengirim induknya. Jika induknya opsional dan Anda menghilangkannya, field turunan yang wajib tidak berlaku.

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

Contoh permintaan

Body siap tempel. Ganti ID dan nilai placeholder dengan milik Anda.

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

Respons

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.

Membuat satu kampanye unggahan dan menyebarkannya ke setiap lokasi dalam locationIds, dengan memublikasikannya ke postSites yang dipilih. Berbeda dengan pembuatan per lokasi, satu panggilan menargetkan seluruh lokasi Anda, sehingga menjadi cara yang efisien untuk menyampaikan pengumuman, penawaran, atau acara di seluruh perusahaan.

Struktur permintaan. Seluruh body harus dibungkus dalam objek input; setiap field (postName, locationIds, postType, …) merupakan properti dari input. Body datar tanpa pembungkus ditolak dengan HTTP 400 (Variable "$input" of required type ... was not provided). Kontrak ini sama dengan POST /posts, dan respons yang berhasil menggunakan createSocialPost sebagai kunci, bukan kunci khusus untuk operasi massal.

Kasus penggunaan: pengumuman di seluruh perusahaan (ditampilkan di atas). Tetapkan postType: "ANNOUNCEMENT", cantumkan ID lokasi, dan sediakan satu postMessage untuk setiap lokasi. Tambahkan postScheduledDates untuk menayangkan unggahan selama rentang waktu yang ditentukan (unggahan kemudian dibuat dengan status SCHEDULED); hilangkan field tersebut untuk langsung memublikasikannya.

Kasus penggunaan: penawaran berbatas waktu di seluruh toko. Ubah postType menjadi OFFER dan sertakan kupon dalam postContextInfo (tetap dibungkus dalam 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"    }  }}

Hal yang perlu diperhatikan.

Body harus dibungkus dalam input; pengiriman field di tingkat teratas menghasilkan respons HTTP 400.
postType, postSites, postName, dan locationIds wajib diisi; tipe EVENT, OFFER, dan PRODUCT juga memerlukan field postContextInfo (atau products) yang sesuai.
postSites hanya menerima GOOGLE dan FACEBOOK; lokasi tujuan harus memiliki saluran terkait yang sudah terhubung atau lokasi tersebut akan dilewati.
Respons mengembalikan HTTP 200 dengan success: false dan array errors yang terisi jika validasi gagal sebagian atau seluruhnya; periksa success, lalu pantau pengiriman secara langsung untuk setiap lokasi menggunakan endpoint pengambilan unggahan massal.

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