Listings APIListings API
Get API keySign in

Connected accounts

Connect Google and Facebook accounts, match their listings to locations, and disconnect them via client.connected_accounts.

All connected-account methods live under client.connected_accounts. A connected account is one Google Business Profile or Facebook Pages login that has authorized the platform, identified by a connectedAccountId you get from connected_accounts.list.

There are two ways to connect. The bulk flow authorizes a whole publisher account and then matches its listings to your locations. The single-location flow mints one OAuth link for one location, which is what you want behind a per-store "Connect Google" button. Methods that take a location_id accept numeric or base64-encoded IDs, see Location IDs.

Matching flow

After a bulk connect, the publisher's listings are not linked to your locations yet. Call trigger_matches to queue the match job, poll details until requestMatchesStatus reads MATCH_COMPLETED, read the pairings with suggestions, then commit the ones you want with confirm_matches. Skipping trigger_matches leaves suggestions empty.

connected_accounts.connect_google

Mint a URL that authorizes a whole Google Business Profile account. Send the user to it, and they return to success_url or error_url. The link is valid for 24 hours.

Python
client.connected_accounts.connect_google(    success_url: str,    error_url: str,) -> APIObject
Python
link = client.connected_accounts.connect_google(  "https://app.example.com/onboarding/google/done",  "https://app.example.com/onboarding/google/retry",)print(link.url)

Returns the bulkConnectLinkForGoogle object. Read url, and check success and errors. Both redirect URLs must be absolute https URLs. See Connect a Google account.

connected_accounts.connect_facebook

Same as connect_google, for a Facebook Pages account. Valid 24 hours.

Python
client.connected_accounts.connect_facebook(    success_url: str,    error_url: str,) -> APIObject
Python
link = client.connected_accounts.connect_facebook(  "https://app.example.com/onboarding/facebook/done",  "https://app.example.com/onboarding/facebook/retry",)print(link.url)

Returns the bulkConnectLinkForFacebook object, with the same url, success, and errors fields. See Connect a Facebook account.

connected_accounts.oauth_url

Mint a URL that connects one publisher profile to one location. Use this when you already know which location the user is connecting, so no matching step is needed. Valid 24 hours.

Python
client.connected_accounts.oauth_url(    location_id: str | int,    site: str,    success_url: str,    error_url: str,) -> APIObject
ParameterTypeDescription
location_idstr | intLocation to attach the profile to, numeric or base64.
sitestrGOOGLE or FACEBOOK. The SDK uppercases it before sending.
success_urlstrAbsolute https URL the user returns to on success.
error_urlstrAbsolute https URL the user returns to on failure.
Python
link = client.connected_accounts.oauth_url(  16808,  site="google",  success_url="https://app.example.com/locations/16808?connected=1",  error_url="https://app.example.com/locations/16808?connected=0",)print(link.url)

Returns the createConnectUrl object. A relative or unparseable redirect comes back as success: true with a null url, so check url itself and not just success. The link is single-use, so mint a fresh one per attempt. See Create an OAuth connect URL for one location.

connected_accounts.list

List the Google and Facebook accounts connected to your account. This is where you get the connectedAccountId every later call needs.

Python
client.connected_accounts.list(    *,    publisher: str | None = None,    status: str | None = None,    page: int | None = None,    per_page: int | None = None,) -> APIObject
ParameterTypeDescription
publisherstrOnly accounts for one publisher.
statusstrOnly accounts in one connection state, for example CONNECTED.
pageint1-based page number.
per_pageintPage size. Sent as perPage.
Python
accounts = client.connected_accounts.list(status="CONNECTED", per_page=50)for account in accounts.records:  print(account.connectedAccountId, account.email, account.connectedLocationsCount)print(accounts.pageInfo.totalRecords)

Returns the connectedAccountsInfo object: records plus pageInfo with hasNextPage, totalPages, and totalRecords. Ordering is fixed to account email ascending. See List connected accounts.

connected_accounts.details

Get one connected account by ID. Poll this after trigger_matches and wait for requestMatchesStatus to reach MATCH_COMPLETED.

Python
client.connected_accounts.details(connected_account_id: str) -> APIObject
Python
account = client.connected_accounts.details("4f712c17-4f95-42dd-90f4-97171a2e67b5")print(account.details.get("status"))print(account.details.get("requestMatchesStatus"))

Returns the connectedAccountDetails object. The fields sit under details: status, connectedAccountType, connectedLocationsCount, connectivityIssue, requestMatchesStatus, and lastFetchMatchesRequestedAt. A non-null connectivityIssue means the publisher token needs re-authorizing. See Get connected account details.

connected_accounts.listings

List the publisher listings a connected account can reach, whether or not they are matched to one of your locations. Use it to show the user what access you picked up.

Python
client.connected_accounts.listings(    connected_account_id: str,    *,    location_info: str | None = None,    page: int | None = None,    per_page: int | None = None,) -> APIObject
ParameterTypeDescription
connected_account_idstrConnected account to read listings from.
location_infostrFree-text filter on the listing name and address.
pageint1-based page number.
per_pageintPage size. Sent as perPage.
Python
page = client.connected_accounts.listings(  "4f712c17-4f95-42dd-90f4-97171a2e67b5",  location_info="Manhattan",  per_page=25,)for listing in page.records:  print(listing.locationName, listing.address, listing.accountTypeName)

This endpoint is a POST and takes every argument in the request body, not the query string; the SDK builds that body for you. Returns the connectedAccountListings object: records plus pageInfo. Each record carries id, locationName, address, phone, accountTypeName, and liveLink. See Fetch listings of a connected account.

connected_accounts.trigger_matches

Queue the job that pulls every profile the given accounts can reach and matches it against your locations. Run it right after a bulk connect, and again after you add locations.

Python
client.connected_accounts.trigger_matches(    connected_account_ids: list[str],) -> APIObject
Python
result = client.connected_accounts.trigger_matches(  ["4f712c17-4f95-42dd-90f4-97171a2e67b5"],)print(result.success, result.failedIds)

Returns the connectedAccountsTriggerMatches object with success and failedIds. The work is asynchronous, so a success: true means queued, not finished. Poll details until requestMatchesStatus is MATCH_COMPLETED before reading suggestions. See Trigger matches.

connected_accounts.suggestions

Read the pairings the match job found between the account's listings and your locations. Show these to the user for review before confirming them.

Python
client.connected_accounts.suggestions(    connected_account_id: str,    *,    page: int | None = None,    per_page: int | None = None,) -> APIObject
Python
page = client.connected_accounts.suggestions(  "4f712c17-4f95-42dd-90f4-97171a2e67b5",  per_page=50,)for match in page.records:  print(match.locationId, match.accountType, match.matchedDataDatabaseId)

Returns the connectionSuggestionsForAccount object: records plus pageInfo. Each record carries locationId, accountType, matchedDataDatabaseId, locationInfo, and suggestedLocationInfo. An empty records with totalRecords: 0 usually means the match job has not run yet. See List connection suggestions.

connected_accounts.confirm_matches

Commit suggested pairings. Once confirmed, the publisher listing starts syncing with the matched location.

Python
client.connected_accounts.confirm_matches(    match_record_ids: list[str],) -> APIObject
Python
result = client.connected_accounts.confirm_matches([  "R21iTG9jYXRpb25NYXRjaGVkRGF0YTowZDVlMzA2Zi0wZGEwLTQ2ZTMtOTI5Zi1mZDNjNjdjY2Q4Y2M=",])print(result.success, result.failedIds)

Returns the confirmConnectMatches object with success and failedIds. A suggestion record has no id of its own: build each match record ID from the record's matchedDataDatabaseId and accountType, as described on Confirm matches.

connected_accounts.folders

List the folders (Google calls them account groups) a connected Google account can reach. Pass the chosen folderId when you create a Google listing so it lands in the right place.

Python
client.connected_accounts.folders(    connected_account_id: str,    *,    folder_name: str | None = None,) -> list[APIObject]
Python
folders = client.connected_accounts.folders(  "4f712c17-4f95-42dd-90f4-97171a2e67b5",)for folder in folders:  print(folder.folderId, folder.folderName, folder.locationCount)

Returns the getFoldersUnderGoogleAccount list. Each item has folderId (an accounts/{id} string used verbatim), folderName, and locationCount, which is null when Google reports no count. Google-type accounts only. See List folders and listings.create_gmb.

connected_accounts.disconnect_google

Disconnect a whole Google account. Every location matched through it stops syncing with Google.

Python
client.connected_accounts.disconnect_google(    connected_account_id: str,) -> APIObject
Python
result = client.connected_accounts.disconnect_google(  "4f712c17-4f95-42dd-90f4-97171a2e67b5",)print(result.success)

Returns the gmbBulkDisconnect object with success. See Disconnect a Google account.

connected_accounts.disconnect_facebook

Disconnect a whole Facebook Pages account.

Python
client.connected_accounts.disconnect_facebook(    connected_account_id: str,) -> APIObject
Python
result = client.connected_accounts.disconnect_facebook(  "9a41b8c0-7d2e-4c15-9f63-2b8e5ad71f04",)print(result.success)

Returns the fbBulkDisconnect object with success. See Disconnect a Facebook account.

connected_accounts.oauth_disconnect

Disconnect one location from one publisher, leaving the rest of the account connected. This is the counterpart to oauth_url.

Python
client.connected_accounts.oauth_disconnect(    location_id: str | int,    site: str,) -> APIObject

site is GOOGLE or FACEBOOK, and the SDK uppercases it before sending.

Python
client.connected_accounts.oauth_disconnect(16808, site="google")

Returns the disconnectConnectedAccountsLocations object with success and errors. See Disconnect one location from a publisher.

See also