Submit Google Business Selection API: Save selected Google Business locations
The Submit Google Business Selection API completes a location-selection flow for Google Business Profile. A client sends POST {{API_BASE_URL}}/v1/connect/googlebusiness/selection/{token}, placing a one-time selection token in the path and the chosen account identifiers in the JSON body. The call creates integrations for the chosen locations, and the token used for that call is then invalidated, so the same token should not be submitted again.
Save selected Google Business locations — operation summary and exact endpoint
This operation creates integrations for the Google Business Profile locations a user chose during selection, and it closes that selection by invalidating the one-time token afterward. The endpoint is POST {{API_BASE_URL}}/v1/connect/googlebusiness/selection/{token}. The token path parameter is required and is a string with length 1 <= length. Replace the token segment with the one-time selection token for the flow you are completing, and do not reuse it after a successful save because the captured behavior invalidates it at that point.
Request body: selectedAccountIds
The request body is application/json and contains one required field, selectedAccountIds. It is an array of strings with at least one item, so an empty array does not satisfy the captured contract. Send the identifiers for the locations the user selected, and only those locations, because the operation creates integrations for the chosen locations. Check the request before sending: the body must be JSON, selectedAccountIds must be present, every item must be a string, and the array must contain at least one item.
Response 200: success, platform, message, redirectUri, and integrations
A 200 response returns the required boolean success field, with the sample showing true, together with platform set to googlebusiness and a message string. The optional redirectUri field may be present when the flow supplies a redirect target. The required integrations array contains the saved integration objects. For each integration, use id as the account identifier for later operations, read platform to confirm the platform value, and inspect authStatus together with authFailureReason to see whether the integration is active or needs reconnection. Also read insightsReadable to distinguish readable analytics from not-yet-determined or not-granted states, and use profileId, profileName, appId, app, and byok to understand which profile and OAuth app the integration belongs to. Fields such as platformUserId, username, displayName, profileUrl, imageUrl, and platformMetadata may be null or optional according to the field map, so handle null values instead of assuming every descriptive field is populated.
Responses 400 and 404: error contract and failure matrix
Both 400 and 404 responses use the same captured shape: a required error string. The captured contract does not define distinct error codes or messages for the two statuses, so a client should branch on the HTTP status first and then surface the returned error string without inventing a more specific meaning. Do not assume the token was invalidated or that any location was saved unless a 200 response confirms it.
Origin-modular request example with {{API_BASE_URL}}
Use the origin-modular request example titled Submit Google Business selection request to see the exact method, path, content type, and body shape. Replace the token placeholder with the actual one-time token and replace the sample string in selectedAccountIds with the selected location identifiers. After sending, compare the response against the 200 response example titled 200 response example, and use the error example titled 400 and 404 error response example when the status is 400 or 404. The field maps below list requiredness, types, nullability, and enums so you can validate the response in code rather than relying on the sample values.
| Field | Location | Required | Type | Constraints / notes |
|---|---|---|---|---|
| token | Path parameter | Required | string | Length 1 <= length |
| selectedAccountIds | Request body (application/json) | Required | array<string> | Items 1 <= items; at least one string item |
Exact captured contract; origin shown as {{API_BASE_URL}}.
| Field | Required | Type | Constraints / notes |
|---|---|---|---|
| success | Required | boolean | Required boolean; sample shows true |
| platform | Required | string | Enum value: googlebusiness |
| message | Required | string | Human-readable result message |
| redirectUri | Optional | string | Redirect target when supplied |
| integrations | Required | array<object> | Saved integration objects; see integrations fields |
Exact captured contract for the 200 response.
| Field | Required | Type | Constraints / notes |
|---|---|---|---|
| id | Required | string | Use this as accountId when creating posts |
| platform | Required | string | Enum: twitter | instagram | youtube | tiktok | pinterest | linkedin | bluesky | facebook | threads | googlebusiness |
| platformUserId | Required | string | null | User ID on the platform, or null if not yet retrieved |
| username | Required | string | null | Public username or handle, including @ for handle-based platforms |
| displayName | Required | string | null | Human-readable display name of the connected account |
| profileUrl | Required | string | null | Format uri; public profile/page URL when it can be derived |
| imageUrl | Required | string | null | Format uri; profile image URL, or null if unavailable |
| platformMetadata | Optional | object | Provider-specific public metadata; [key: string] values are any |
| profileId | Required | string | null | Profile this integration belongs to, or null if connected without a profile |
| profileName | Optional | string | null | Name of the profile (social group); only populated on the list endpoint |
| appId | Required | string | null | OAuth app this integration was connected under, or null if the system app was used |
| app | Required | object | null | OAuth app metadata for BYOK integrations, or null when the system app was used; object fields id, name, and imageUrl are optional, with imageUrl string | null |
| byok | Required | boolean | True when connected under the customer's own OAuth app (Bring Your Own Keys), i.e. appId is set |
| authStatus | Required | string | Enum: active | reconnect_required; whether this integration can authenticate or needs OAuth reconnection |
| authFailureReason | Required | string | null | Enum: token_expired | access_revoked | security_invalidation | refresh_rejected | null; stable reason reconnection is required, or null while active |
| insightsReadable | Required | boolean | null | null = not determined yet, true = readable, false = account did not grant insights permission (auth can still be active) |
| createdAt | Required | string | Format date-time |
Exact captured contract for each integrations[] object.
| Status | Response field | Required | Type | Client check |
|---|---|---|---|---|
| 400 | error | Required | string | Branch on status and surface the returned error string |
| 404 | error | Required | string | Branch on status and surface the returned error string |
Only the captured error string contract is specified; no distinct error codes or messages are defined for 400 versus 404.
curl -X POST "{{API_BASE_URL}}/v1/connect/googlebusiness/selection/{token}" \
-H "Content-Type: application/json" \
-d '{
"selectedAccountIds": [
"string"
]
}'{
"success": true,
"platform": "googlebusiness",
"message": "string",
"redirectUri": "string",
"integrations": [
{
"id": "string",
"platform": "twitter",
"platformUserId": "string",
"username": "string",
"displayName": "string",
"profileUrl": "http://example.com",
"imageUrl": "http://example.com",
"platformMetadata": {},
"profileId": "string",
"profileName": "string",
"appId": "string",
"app": {
"id": "string",
"name": "string",
"imageUrl": "string"
},
"byok": true,
"authStatus": "active",
"authFailureReason": "token_expired",
"insightsReadable": true,
"createdAt": "2019-08-24T14:15:22Z"
}
]
}{
"error": "string"
}| Scope | Field | Type | Type reference | Required | Description | Constraints |
|---|---|---|---|---|---|---|
| response#1 | response | object | __0 | |||
| response#1 | response.success | boolean | __1 | Yes | ||
| response#1 | response.platform | string | __2 | Yes | kind: schemaValueIn; value: "googlebusiness" | |
| response#1 | response.message | string | __3 | Yes | ||
| response#1 | response.redirectUri | string | __4 | No | ||
| response#1 | response.integrations | array<object> | __5 | Yes | ||
| response#1 | response.integrations[] | object | __6 | |||
| response#1 | response.integrations[].id | string | __7 | Yes | Use this as accountId when creating posts | |
| response#1 | response.integrations[].platform | string | __8 | Yes | kind: schemaValueIn; value: "twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness" | |
| response#1 | response.integrations[].platformUserId | string | null | __9 | Yes | The user ID on the platform, or null if not yet retrieved | |
| response#1 | response.integrations[].platformUserId[variant1] | string | __9_type:string | The user ID on the platform, or null if not yet retrieved | ||
| response#1 | response.integrations[].platformUserId[variant2] | null | __9_type:null | The user ID on the platform, or null if not yet retrieved | ||
| response#1 | response.integrations[].username | string | null | __10 | Yes | The public username or handle, including @ for handle-based platforms | |
| response#1 | response.integrations[].username[variant1] | string | __10_type:string | The public username or handle, including @ for handle-based platforms | ||
| response#1 | response.integrations[].username[variant2] | null | __10_type:null | The public username or handle, including @ for handle-based platforms | ||
| response#1 | response.integrations[].displayName | string | null | __11 | Yes | Human-readable display name of the connected account | |
| response#1 | response.integrations[].displayName[variant1] | string | __11_type:string | Human-readable display name of the connected account | ||
| response#1 | response.integrations[].displayName[variant2] | null | __11_type:null | Human-readable display name of the connected account | ||
| response#1 | response.integrations[].profileUrl | string | null | __12 | Yes | Public profile/page URL for the connected account, when it can be derived | kind: schemaFormat; value: uri |
| response#1 | response.integrations[].profileUrl[variant1] | string | __12_type:string | Public profile/page URL for the connected account, when it can be derived | kind: schemaFormat; value: uri | |
| response#1 | response.integrations[].profileUrl[variant2] | null | __12_type:null | Public profile/page URL for the connected account, when it can be derived | kind: schemaFormat; value: uri | |
| response#1 | response.integrations[].imageUrl | string | null | __13 | Yes | Profile image URL for the connected account, or null if unavailable | kind: schemaFormat; value: uri |
| response#1 | response.integrations[].imageUrl[variant1] | string | __13_type:string | Profile image URL for the connected account, or null if unavailable | kind: ; value: uri | |
| response#1 | response.integrations[].imageUrl[variant2] | null | __13_type:null | Profile image URL for the connected account, or null if unavailable | kind: ; value: uri | |
| response#1 | response.integrations[].platformMetadata | object | __14 | No | Provider-specific public metadata for this connected account. | |
| response#1 | response.integrations[].platformMetadata.[key: string] | any | true | No | ||
| response#1 | response.integrations[].profileId | string | null | __15 | Yes | Profile this integration belongs to, or null if it was connected without a profile | |
| response#1 | response.integrations[].profileId[variant1] | string | __15_type:string | Profile this integration belongs to, or null if it was connected without a profile | ||
| response#1 | response.integrations[].profileId[variant2] | null | __15_type:null | Profile this integration belongs to, or null if it was connected without a profile | ||
| response#1 | response.integrations[].profileName | string | null | __16 | No | Name of the profile (social group) this integration belongs to, or null when it has no profile. Only populated on the list endpoint so clients can label the group without fetching the full profiles list. | |
| response#1 | response.integrations[].profileName[variant1] | string | __16_type:string | Name of the profile (social group) this integration belongs to, or null when it has no profile. Only populated on the list endpoint so clients can label the group without fetching the full profiles list. | ||
| response#1 | response.integrations[].profileName[variant2] | null | __16_type:null | Name of the profile (social group) this integration belongs to, or null when it has no profile. Only populated on the list endpoint so clients can label the group without fetching the full profiles list. | ||
| response#1 | response.integrations[].appId | string | null | __17 | Yes | The OAuth app (customer's own OAuth app) this integration was connected under, or null if the service's system app was used. | |
| response#1 | response.integrations[].appId[variant1] | string | __17_type:string | The OAuth app (customer's own OAuth app) this integration was connected under, or null if the service's system app was used. | ||
| response#1 | response.integrations[].appId[variant2] | null | __17_type:null | The OAuth app (customer's own OAuth app) this integration was connected under, or null if the service's system app was used. | ||
| response#1 | response.integrations[].app | object | null | __18 | Yes | The OAuth app metadata for BYOK integrations, or null when the service's system app was used. | |
| response#1 | response.integrations[].app[variant1] | object | __18_type:object | The OAuth app metadata for BYOK integrations, or null when the service's system app was used. | ||
| response#1 | response.integrations[].app[variant1].id | string | __19 | No | ||
| response#1 | response.integrations[].app[variant1].name | string | __20 | No | ||
| response#1 | response.integrations[].app[variant1].imageUrl | string | null | __21 | No | ||
| response#1 | response.integrations[].app[variant1].imageUrl[variant1] | string | __21_type:string | |||
| response#1 | response.integrations[].app[variant1].imageUrl[variant2] | null | __21_type:null | |||
| response#1 | response.integrations[].app[variant2] | null | __18_type:null | The OAuth app metadata for BYOK integrations, or null when the service's system app was used. | ||
| response#1 | response.integrations[].byok | boolean | __22 | Yes | True when this integration was connected under the customer's own OAuth app (Bring Your Own Keys), i.e. appId is set. False when the service's system app is used. | |
| response#1 | response.integrations[].authStatus | string | __23 | Yes | Whether this integration can authenticate or needs OAuth reconnection | |
| response#1 | response.integrations[].authStatus[variant1] | string | __23_extends:__24 | Whether this integration can authenticate or needs OAuth reconnection | kind: ; value: "active" | |
| response#1 | response.integrations[].authStatus[variant2] | string | __23_extends:__25 | Whether this integration can authenticate or needs OAuth reconnection | kind: ; value: "reconnect_required" | |
| response#1 | response.integrations[].authFailureReason | string | null | __26 | Yes | Stable reason reconnection is required, or null while active | |
| response#1 | response.integrations[].authFailureReason[variant1] | string | __26_extends:__27 | Stable reason reconnection is required, or null while active | kind: ; value: "token_expired" | |
| response#1 | response.integrations[].authFailureReason[variant2] | string | __26_extends:__28 | Stable reason reconnection is required, or null while active | kind: ; value: "access_revoked" | |
| response#1 | response.integrations[].authFailureReason[variant3] | string | __26_extends:__29 | Stable reason reconnection is required, or null while active | kind: ; value: "security_invalidation" | |
| response#1 | response.integrations[].authFailureReason[variant4] | string | __26_extends:__30 | Stable reason reconnection is required, or null while active | kind: ; value: "refresh_rejected" | |
| response#1 | response.integrations[].authFailureReason[variant5] | null | __26_extends:__31 | Stable reason reconnection is required, or null while active | ||
| response#1 | response.integrations[].insightsReadable | boolean | null | __32 | Yes | Whether this account can read analytics/insights. null = not determined yet, true = readable, false = the account did not grant the insights permission (auth can still be active). Reconnect and approve the analytics permission to fix a false. | |
| response#1 | response.integrations[].insightsReadable[variant1] | boolean | __32_type:boolean | Whether this account can read analytics/insights. null = not determined yet, true = readable, false = the account did not grant the insights permission (auth can still be active). Reconnect and approve the analytics permission to fix a false. | ||
| response#1 | response.integrations[].insightsReadable[variant2] | null | __32_type:null | Whether this account can read analytics/insights. null = not determined yet, true = readable, false = the account did not grant the insights permission (auth can still be active). Reconnect and approve the analytics permission to fix a false. | ||
| response#1 | response.integrations[].createdAt | string | __33 | Yes | kind: ; value: date-time | |
| response#2 | response | object | __0 | |||
| response#2 | response.error | string | __1 | Yes |