연결된 계정 목록 조회

매개변수

쿼리

이름	유형	필수	설명	기본값
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를 필터 값으로 다시 전달하면 유효하지 않은 enum 값으로 처리되어 400이 반환됩니다.

응답의 pageInfo.hasNextPage와 pageInfo.totalPages를 확인하여 다음 페이지를 가져올지 결정합니다. 이 엔드포인트 호출은 계정의 요청 빈도 제한에 포함되며, 429 응답에는 Retry-After 헤더가 포함됩니다.