v1Resources/Connections/postPreview Google listing creation
Preview Google listing creation
Checks whether each location in the selection can get a new Google listing, without creating or saving anything. Start the flow here: send only locationIds to get each location's readiness and the Google logins in accounts that can create for every client in the selection. After you pick a group with the destinations endpoint, call preview again with accountConnectionId and googleAccountName to check that destination. When canSubmit is true, send the same body, plus confirmedNoExistingProfiles, to the create endpoint. Location ids you can't access come back in unavailableIds instead of failing the request. Up to 200 locations per request. Checking a group reads it live from Google, so that call can return 502.
post
connections:read/api/v1/connections/google-listing-create/previewRequest body
locationIdsarray of stringrequired
The ids of the locations to work on, up to 200. Duplicates are ignored.
accountConnectionIdstringoptional
The connectionId of the Google login to create under, from accounts in the preview response. Required for destinations and create. Optional for preview, where you send it with googleAccountName to check a destination.
googleAccountNamestringoptional
The resourceName of the Google group to create the listings in, such as accounts/123456789, from the destinations response. Required for create. Optional for preview.
Response
dataobjectoptional
countsobjectoptional
How many locations fall into each state.
readyintegeroptional
Locations that can be created as they are.
reviewintegeroptional
Locations that can be created, but should be checked first.
needs_attentionintegeroptional
Locations that need a fix before they can be created.
excludedintegeroptional
Locations that won't get a new Google listing.
unavailableintegeroptional
Requested ids that weren't found or that you can't access.
locationsarray of objectoptional
Readiness for each requested location you can access.
locationIdstringoptional
The location's id.
clientIdstringoptional
The client the location belongs to, or null.
namestringoptional
The location's business name, or null.
statestring (ready | review | needs_attention | excluded)optional
ready (can be created), review (can be created, but check it first because Google may already have a profile for it), needs_attention (fix the location, then preview again) or excluded (won't get a new Google listing).
reasonsarray of string (archived | already_connected | creating | needs_reconnection | google_excluded_by_package | opted_out | missing_business_name | missing_google_category | missing_address | possible_existing_profile | previously_connected)optional
Why the location is in this state. Excluded: archived, already_connected, creating (a create is already in progress), needs_reconnection (linked to a Google listing whose access has expired), google_excluded_by_package (Google isn't part of the location's listing package) or opted_out. Needs attention: missing_business_name, missing_google_category or missing_address (no street, city and country, and no service area). Review: possible_existing_profile (a Google listing found under one of your logins matches this location) or previously_connected (the location was linked to Google before and has been disconnected). Empty for a ready location.
unavailableIdsarray of stringoptional
Requested location ids that weren't found or that you can't access. They are listed here instead of failing the request.
accountsarray of objectoptional
Google logins that can create for every client in the selection, including ones that need reconnecting. Agency logins come first. Empty when every selected location is excluded, or when no single login covers all the clients.
connectionIdstringoptional
The login's connection id. Send it as accountConnectionId.
displayNamestringoptional
The login's display name, usually the Google account's email.
ownerobjectoptional
Who the login belongs to: the agency, or one client.
typestring (agency | client)optional
agency for an agency-wide login, client for a login that belongs to one client.
clientIdstringoptional
The id of the client that owns the login. Only present when type is client.
namestringoptional
The business name of the client that owns the login. Only present when type is client.
statusstring (ready | needs_reconnection)optional
ready when the login can be used, needs_reconnection when its access has expired and someone has to reconnect it first.
noCommonAccountbooleanoptional
True when some locations could be created but no single login covers all of their clients. Split the selection by client and try again.
destinationobjectoptional
The result of checking the destination you sent.
selectedbooleanoptional
False when you sent neither accountConnectionId nor googleAccountName.
validbooleanoptional
Whether the login and group can be used for this selection. Present when selected is true.
resourceNamestringoptional
The checked group's resource name. Present when valid is true.
reasonstring (account_unavailable | group_unavailable | group_not_creatable)optional
Why the destination can't be used: account_unavailable (the login can't create for this selection or needs reconnecting), group_unavailable (the group wasn't found under the login, or googleAccountName isn't in the accounts/123456789 form) or group_not_creatable (the group can't hold new listings). Present when valid is false.
submittableCountintegeroptional
How many locations create would queue: ready plus review.
canSubmitbooleanoptional
True when the destination is valid and at least one location can be created.
Errors
400The request is missing a required parameter or is otherwise malformed.
401Missing, invalid, expired, or revoked API key.
403The key lacks the required scope, or isn't authorized for this client/location.
429Too many requests. Retry after the number of seconds in the Retry-After header.
502Google couldn't be reached to read the login's groups. Try again later. The response's code is provider_unavailable.
post/api/v1/connections/google-listing-create/preview
Your API key
Request body*
{}Guides that use this resource
- What Is a Business Listings API?A business listings API manages a business's name, address, hours and more across many publishers at once, with sync status and duplicate detection built in.
- Business Listings API: Complete Developer GuideHow a business listings API works and how to create, update, sync and monitor locations across Google, Apple, Bing and directories with the Synup API.
- Google Business Profile API vs a Listings Management APIHow Google's Business Profile API compares with a listings management API on scope, access, sync status, duplicates and reviews, and when to use each.
- How to Add Local Marketing Features to Your SaaSAdd listings management, reviews, Google posts, profile analytics, rank tracking and AI visibility to a SaaS product with the Synup API, tenant by tenant.
- How to Update Business Information Across Google, Apple, Bing and DirectoriesPush one business-information change to Google, Apple, Bing and the directory network through a single API call, and verify it reached each publisher.
- How to Manage Thousands of Business Locations via APIDesign a sync job for thousands of locations on the Synup API with cursor pagination, tags, rate-limit handling, an id map and rollup health checks.
- How Google Business Profile Synchronization WorksGoogle Business Profile sync rests on an owner's OAuth consent, matching a location to the right Google listing, then a write-and-verify loop.
- How to Build a Multi-Location Marketing DashboardBuild a multi-location marketing dashboard from the API's rollup endpoints, one call per panel, covering listings, reviews, rank, AI visibility and duplicates.
- How to Connect and Manage Google Business Profiles via APIConnect a Google Business Profile to a location, match the account's listings, keep the profile in sync and handle reconnects with the Synup API.
- Building Publisher Integrations Directly vs Using SynupWhat it really costs to integrate Google, Apple, Bing and directories yourself, versus one API, and how to decide between them or combine both.