列出已連結的帳戶

參數

查詢

名稱	類型	必填	說明	預設值
page	integer	選填	1-based page number.	1
perPage	integer	選填	Records per page.	20
publisher	string	選填	Narrow to one publisher by account type: `GoogleAccount`, `FacebookAccount`, `AppleAccount`, `YelpAccount`, `TripadvisorAccount`, `LinkedinAccount`, `PinterestAccount`, or `TwitterAccount`.	—
status	string	選填	Narrow to one connection status: `Connected`, `NotConnected`, or `ConnectionIssue`. Note the mixed case, and that these are not the values the response's own `status` field uses.	—

回應

200List of connected accounts with pagination metadata.

Response

{  "data": {    "connectedAccountsInfo": {      "pageInfo": {        "hasNextPage": false,        "hasPreviousPage": false,        "totalPages": 1,        "totalRecords": 1      },      "records": [        {          "accountId": "12345",          "clientName": "owner@brightsmile-dental.com",          "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5",          "connectedAccountType": "GoogleAccount",          "connectedLocationsCount": 0,          "connectivityIssue": null,          "email": "owner@brightsmile-dental.com",          "lastFetchMatchesRequestedAt": "2026-07-06 21:43:07 UTC",          "remarks": null,          "requestMatches": false,          "requestMatchesStatus": "MATCH_COMPLETED",          "status": "CONNECTED"        }      ]    }  }}

401Unauthenticated, missing or invalid API key.

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

傳回已獲授權連結至您的 Listings API 帳戶的所有 Google Business Profile 和 Facebook Pages 帳戶。每筆記錄都包含連線健康狀態（status、connectivityIssue）、已連結的地點數量（connectedLocationsCount），以及上次擷取比對結果的狀態（requestMatchesStatus）。

使用案例：同步前稽核連線健康狀態。 在每晚排程作業開始時呼叫此端點，找出憑證已失效的帳戶。任何記錄只要 connectivityIssue 不為 null，或 status 不是 CONNECTED，就需要客戶透過連結流程重新授權；請略過這些記錄，以免在失效的憑證上浪費一次 trigger-matches 呼叫。

使用案例：取得供後續呼叫使用的 connectedAccountId。 trigger-matches、fetch-listings、folders 和 details 端點都以 connectedAccountId 指定帳戶。列出帳戶，選取 email 與客戶相符的帳戶，並重複使用其 connectedAccountId。

分頁和篩選使用一般的扁平查詢參數，而非 JSON：page、perPage、publisher 和 status。沒有 pageInfo、filters 或 sort 參數，也無法變更排序方式：結果一律依帳戶電子郵件地址遞增排序。您傳送的其他內容都會被忽略，而不會遭到拒絕，因此 JSON 格式的 pageInfo 會直接傳回第 1 頁，不會發出任何提示。

Shell

curl -s 'https://listingsapi.com/api/v4/connected-accounts?page=1&perPage=20&publisher=GoogleAccount&status=Connected' \  -H "Authorization: API $LISTINGSAPI_KEY"

status 篩選條件與 status 欄位使用的值並不相同。 篩選條件接受 Connected、NotConnected 或 ConnectionIssue；每筆傳回記錄的 status 則為 CONNECTED、MATCH_IN_PROGRESS 或 CONNECTIVITY_ISSUE。若把記錄本身的 status 直接當作篩選條件傳入，該值會被視為無效的列舉值，並傳回 400。

讀取回應中的 pageInfo.hasNextPage 和 pageInfo.totalPages，以決定是否擷取下一頁。此端點的呼叫會計入帳戶的速率限制，429 回應會包含 Retry-After 標頭。