listingsAPI

Parameters

Path

Name	Type	Required	Description
locationId	string	required	Numeric location ID (e.g. 1800289).

Query

Name	Type	Required	Description	Default
tag	string	required	Segment/tag to pull campaigns from. Pass `all` to fetch every bulk campaign touching the location. Omitting this returns an error, not an empty list.	—
page	integer	optional	1-based page number for offset pagination.	1
perPage	integer	optional	Number of records per page.	—
filters	string	optional	JSON-encoded SocialPostFiltersInput (e.g. by `type`, `status`, `creationDateRange`, `siteUrls`).	—
sortFields	string	optional	JSON-encoded sort object `{ "field": "created_at", "order": "Descending" }`. `field` is one of name, type, status, created_at, schedule_start_date, schedule_end_date, client_name, clicks, views, shares.	—
locationIds	string	optional	JSON-encoded array of location IDs to include alongside the path location.	—
componentIdentifier	string	optional	Filter to campaigns created by a specific component/integration.	—

Responses

200A page of bulk campaigns that include the location. `records` is empty when no bulk campaign has targeted it.

{
  "data": {
    "rollupSocialPosts": {
      "records": [
        {
          "id": "U29jaWFsUG9zdDo1MTA4OA==",
          "name": "Diwali Offer - All Stores",
          "status": "SUCCESS",
          "type": "OFFER",
          "createdAt": "2026-06-20",
          "scheduledStartDate": "2026-06-22",
          "scheduledEndDate": "2026-07-06",
          "views": 4210,
          "clicks": 318,
          "shares": 12,
          "reactions": 87,
          "comments": 4,
          "sites": ["GOOGLE", "FACEBOOK"],
          "message": [
            { "site": "GOOGLE", "message": "Festive savings across all our stores this week." },
            { "site": "FACEBOOK", "message": "Festive savings across all our stores this week!" }
          ],
          "cta": [
            { "type": { "value": "GET_OFFER", "label": "Get offer" }, "url": "https://jennyhome.example/diwali", "site": "GOOGLE", "tinyUrl": "https://tiny.cc/jh-diwali" }
          ],
          "contextInfo": {
            "couponCode": "DIWALI25",
            "redeemUrl": "https://jennyhome.example/diwali",
            "termsConditions": "Valid in-store only. Cannot be combined with other offers.",
            "title": "25% off storewide",
            "discount": "25%",
            "startDay": "2026-06-22",
            "endDay": "2026-07-06"
          },
          "mediaUrl": [
            { "url": "https://cdn.listingsapi.com/posts/51088/diwali.jpg", "site": "GOOGLE", "type": "IMAGE" }
          ],
          "publishDetails": [
            { "site": "GOOGLE", "status": "PUBLISHED", "createdDate": "2026-06-20", "publishedDate": "2026-06-22", "submissionError": null },
            { "site": "FACEBOOK", "status": "PUBLISHED", "createdDate": "2026-06-20", "publishedDate": "2026-06-22", "submissionError": null }
          ],
          "postLinks": [
            { "site": "GOOGLE", "link": "https://www.google.com/maps/place/?post=51088" }
          ],
          "locationIds": [1800289, 1800290, 1800291],
          "clientName": "Jenny Home"
        }
      ],
      "locationDetails": [
        {
          "id": "TG9jYXRpb246MTgwMDI4OQ==",
          "name": "Jenny Home",
          "street": "19 east, 5th B cross road, Trinity Enclave Main Rd, Banjara Layout",
          "city": "Bengaluru",
          "postalCode": "560043",
          "countryIso": "IN",
          "stateIso": "KA",
          "stateName": "Karnataka",
          "storeId": null
        }
      ],
      "pageInfo": {
        "totalPages": 1,
        "hasNextPage": false,
        "hasPreviousPage": false,
        "totalRecords": 1
      }
    }
  }
}

401Unauthenticated — missing or invalid API key.

429Rate limit exceeded. Retry after the `Retry-After` header value.

A bulk post is one campaign published to many locations at once (created via POST /bulk-posts). This endpoint lists the bulk campaigns that include the given location, so you can see multi-store rollups from a single store's perspective. The response shape is identical to GET /locations/{locationId}/posts; records here simply span multiple locationIds.

Use case — reconcile a chain-wide rollout. After launching a "Diwali Offer" across every store, call GET /locations/1800289/bulk-posts?tag=all from any one store to confirm the campaign reached it, inspect the shared contextInfo (coupon code, discount, terms), and read the per-site publishDetails to spot a FACEBOOK submissionError on that location.

Gotchas.

Same as the single-location list: tag is effectively required (use tag=all), pagination is offset-based via page/perPage, sortFields is a single object (not an array), and heavy polling can return HTTP 429.
locationIds on each record is the full set the campaign targeted — it will contain IDs beyond the one in the path.

The records array above is representative. The live seed location (Jenny Home) has no bulk campaigns, so a real call returns records: [] with pageInfo.totalRecords: 0.