/api/v4/connected-accountsElenca gli account collegati
Restituisce gli account Google e Facebook collegati al tuo account Listings API, con lo stato delle connessioni e il numero di sedi collegate.
Parametri
Query
| Nome | Tipo | Obbligatorio | Descrizione | Predefinito |
|---|---|---|---|---|
| page | integer | facoltativo | 1-based page number. | 1 |
| perPage | integer | facoltativo | Records per page. | 20 |
| publisher | string | facoltativo | Narrow to one publisher by account type: `GoogleAccount`, `FacebookAccount`, `AppleAccount`, `YelpAccount`, `TripadvisorAccount`, `LinkedinAccount`, `PinterestAccount`, or `TwitterAccount`. | — |
| status | string | facoltativo | 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. | — |
Risposte
200List of connected accounts with pagination metadata.
{ "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.
Restituisce tutti gli account Google Business Profile e Facebook Pages autorizzati a collegarsi al tuo account Listings API. Ogni record contiene lo stato della connessione (status, connectivityIssue), il numero di sedi collegate (connectedLocationsCount) e lo stato dell'ultimo recupero delle corrispondenze (requestMatchesStatus).
Caso d'uso: verifica lo stato delle connessioni prima di una sincronizzazione. Esegui questa operazione all'inizio di un processo notturno per individuare gli account le cui credenziali sono scadute. Qualsiasi record con un valore di connectivityIssue diverso da null o un valore di status diverso da CONNECTED richiede che il cliente autorizzi nuovamente la connessione tramite il relativo flusso; salta questi record per non sprecare una chiamata trigger-matches con credenziali non più valide.
Caso d'uso: ricava un connectedAccountId per le chiamate successive. Gli endpoint trigger-matches, fetch-listings, folders e details usano tutti connectedAccountId come chiave. Elenca gli account, scegli quello il cui email corrisponde al cliente e riutilizza il suo connectedAccountId.
La paginazione e il filtraggio usano semplici parametri di query non annidati, non JSON: page, perPage, publisher e status. Non esistono parametri pageInfo, filters o sort, né è possibile modificare l'ordinamento: i risultati sono sempre ordinati per indirizzo email dell'account, in ordine crescente. Qualsiasi altro elemento inviato viene ignorato anziché rifiutato, quindi un pageInfo in JSON restituisce la pagina 1 senza alcun avviso.
curl -s 'https://listingsapi.com/api/v4/connected-accounts?page=1&perPage=20&publisher=GoogleAccount&status=Connected' \ -H "Authorization: API $LISTINGSAPI_KEY"Il filtro status e il campo status non usano lo stesso insieme di valori. Il filtro accetta Connected, NotConnected o ConnectionIssue; il valore di status in ogni record restituito è CONNECTED, MATCH_IN_PROGRESS o CONNECTIVITY_ISSUE. Riutilizzare il valore di status di un record come filtro equivale a fornire un valore enum non valido e restituisce un 400.
Leggi pageInfo.hasNextPage e pageInfo.totalPages nella risposta per decidere se recuperare un'altra pagina. Questo endpoint è soggetto al limite di frequenza dell'account; una risposta 429 include un'intestazione Retry-After.
curl -X GET 'https://listingsapi.com/api/v4/connected-accounts' \ -H "Authorization: API $LISTINGSAPI_KEY"