列出品牌 | Listings API

參數

查詢

名稱	類型	必填	說明	預設值
filters	string	選填	JSON-encoded filter object with two fields. `statuses` (array of strings, required inside the object) selects which brand states to return: `ACTIVE` or `ARCHIVED`. `profileName` (string, optional) is a case-insensitive substring match on the brand name. Omit the parameter entirely to return active brands.	—
page	integer	選填	1-based page number. Defaults to 1.	—
size	integer	選填	Rows per page. Defaults to 20.	—

回應

200A page of brands plus `pageInfo` for paging.

Response

{  "data": {    "listSocialProfiles": {      "profiles": [        {          "id": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",          "profileName": "Jenny Home",          "archived": false,          "logo": null,          "profileLogo": null,          "siteUrl": "https://jennyhome.example",          "countryIso": "US",          "bio": "Handmade furniture for real homes.",          "businessIntent": "A family-run home furnishings store selling handmade furniture and textiles.",          "categories": ["Furniture Store", "Home Goods"],          "brandHashtags": ["jennyhome", "handmadefurniture"],          "competitorHashtags": [],          "connectedChannelCount": 3,          "timezone": {            "label": "(GMT-05:00) Eastern Time",            "tzCode": "America/New_York",            "name": "Eastern Standard Time",            "utc": "-05:00"          },          "contentPreferredLanguage": "en"        },        {          "id": "a90f7c22-5db1-4e83-9f40-2b7c6a1e5d33",          "profileName": "Jenny Home Eastside",          "archived": false,          "logo": null,          "profileLogo": null,          "siteUrl": null,          "countryIso": "US",          "bio": null,          "businessIntent": "general",          "categories": [],          "brandHashtags": [],          "competitorHashtags": [],          "connectedChannelCount": 0,          "timezone": {            "label": "(GMT-06:00) Central Time",            "tzCode": "America/Chicago",            "name": "Central Standard Time",            "utc": "-06:00"          },          "contentPreferredLanguage": "en"        }      ],      "pageInfo": {        "total": 11,        "hasNextPage": true,        "totalEngagementPosts": 0,        "totalPublishedPosts": 0      }    }  }}

401Unauthenticated, missing or invalid API key.

逐頁列出您帳戶中的品牌。每一列都是 GET /social/brands/{brandId} 針對單一品牌傳回的相同品牌物件，因此通常只需這份清單就能呈現品牌選擇器，無須再次往返請求。

使用案例：在您自己的 UI 中提供品牌選擇器。 當使用者開啟您的發布畫面時，呼叫此端點一次，並在每一列顯示 profileName 和 logo。若品牌的 connectedChannelCount 為 0，表示該品牌尚未連結任何社群帳號，無法發布；請為其加上標記，並引導使用者前往連線連結。當 pageInfo.hasNextPage 為 true 時，使用 page 和 size 分頁。

使用案例：核對您的紀錄。 每晚逐頁讀取所有資料，並將 id 與您在建立時儲存的品牌 ID 比對。從預設清單中消失的品牌已封存；傳入 filters={"statuses":["ARCHIVED"]} 即可查看。

注意事項。

id 是一般的 UUID，在 Social API 的其他位置用作 brandId 路徑佔位符，並在請求主體中用作 socialProfileId。
篩選條件會以單一 JSON 編碼字串放在 filters 查詢參數中傳送，而不是作為個別參數傳送。請將此字串做 URL 編碼。只要您傳送 filters，其中就必須包含 statuses；profileName 則可選擇一併提供。
分頁以位移量為基礎（page／size），並不像 Locations 和 Reviews 端點以游標為基礎。pageInfo.total 是符合條件的品牌總數，而不是本頁的品牌數量。pageInfo.totalEngagementPosts 和 totalPublishedPosts 是與貼文清單共用的貼文計數器，在此處皆為 0。
connectedChannelCount 僅計算有效連線；管道一旦中斷連線，就會立即從計數中移除。如需取得管道本身的資料，請呼叫 GET /social/brands/{brandId}/connections。
timezone.tzCode 是 IANA 識別碼，該品牌的所有排程都以此判定時區；其餘 3 個時區欄位則是用於顯示的標籤。
品牌數量沒有上限，無須核對是否達到上限。 API 方案不限制品牌數量，因此此清單的長度僅供參考。有數量上限的是連線：請從 GET /social/limits 讀取該數值。封存品牌會立即使其連線離線，但連線名額在計費週期結束前仍計入 maxConnections，因此已從此清單中移除的品牌仍可能占用名額，直到續訂時才釋出。