列出已连接账户 | Listings API

参数

查询

名称	类型	必填	描述	默认值
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 响应头。