Skip to content

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.

Path parameter and request body fields
FieldLocationRequiredTypeConstraints / notes
tokenPath parameterRequiredstringLength 1 <= length
selectedAccountIdsRequest body (application/json)Requiredarray<string>Items 1 <= items; at least one string item

Exact captured contract; origin shown as {{API_BASE_URL}}.

200 response fields
FieldRequiredTypeConstraints / notes
successRequiredbooleanRequired boolean; sample shows true
platformRequiredstringEnum value: googlebusiness
messageRequiredstringHuman-readable result message
redirectUriOptionalstringRedirect target when supplied
integrationsRequiredarray<object>Saved integration objects; see integrations fields

Exact captured contract for the 200 response.

Integrations object fields
FieldRequiredTypeConstraints / notes
idRequiredstringUse this as accountId when creating posts
platformRequiredstringEnum: twitter | instagram | youtube | tiktok | pinterest | linkedin | bluesky | facebook | threads | googlebusiness
platformUserIdRequiredstring | nullUser ID on the platform, or null if not yet retrieved
usernameRequiredstring | nullPublic username or handle, including @ for handle-based platforms
displayNameRequiredstring | nullHuman-readable display name of the connected account
profileUrlRequiredstring | nullFormat uri; public profile/page URL when it can be derived
imageUrlRequiredstring | nullFormat uri; profile image URL, or null if unavailable
platformMetadataOptionalobjectProvider-specific public metadata; [key: string] values are any
profileIdRequiredstring | nullProfile this integration belongs to, or null if connected without a profile
profileNameOptionalstring | nullName of the profile (social group); only populated on the list endpoint
appIdRequiredstring | nullOAuth app this integration was connected under, or null if the system app was used
appRequiredobject | nullOAuth 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
byokRequiredbooleanTrue when connected under the customer's own OAuth app (Bring Your Own Keys), i.e. appId is set
authStatusRequiredstringEnum: active | reconnect_required; whether this integration can authenticate or needs OAuth reconnection
authFailureReasonRequiredstring | nullEnum: token_expired | access_revoked | security_invalidation | refresh_rejected | null; stable reason reconnection is required, or null while active
insightsReadableRequiredboolean | nullnull = not determined yet, true = readable, false = account did not grant insights permission (auth can still be active)
createdAtRequiredstringFormat date-time

Exact captured contract for each integrations[] object.

Failure matrix for 400 and 404
StatusResponse fieldRequiredTypeClient check
400errorRequiredstringBranch on status and surface the returned error string
404errorRequiredstringBranch 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.

Submit Google Business selection request
curl -X POST "{{API_BASE_URL}}/v1/connect/googlebusiness/selection/{token}" \
  -H "Content-Type: application/json" \
  -d '{
    "selectedAccountIds": [
      "string"
    ]
  }'
200 response example
{
  "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"
    }
  ]
}
400 and 404 error response example
{
  "error": "string"
}
Interface fields
ScopeFieldTypeType referenceRequiredDescriptionConstraints
response#1responseobject__0
response#1response.successboolean__1Yes
response#1response.platformstring__2Yeskind: schemaValueIn; value: "googlebusiness"
response#1response.messagestring__3Yes
response#1response.redirectUristring__4No
response#1response.integrationsarray<object>__5Yes
response#1response.integrations[]object__6
response#1response.integrations[].idstring__7YesUse this as accountId when creating posts
response#1response.integrations[].platformstring__8Yeskind: schemaValueIn; value: "twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness"
response#1response.integrations[].platformUserIdstring | null__9YesThe user ID on the platform, or null if not yet retrieved
response#1response.integrations[].platformUserId[variant1]string__9_type:stringThe user ID on the platform, or null if not yet retrieved
response#1response.integrations[].platformUserId[variant2]null__9_type:nullThe user ID on the platform, or null if not yet retrieved
response#1response.integrations[].usernamestring | null__10YesThe public username or handle, including @ for handle-based platforms
response#1response.integrations[].username[variant1]string__10_type:stringThe public username or handle, including @ for handle-based platforms
response#1response.integrations[].username[variant2]null__10_type:nullThe public username or handle, including @ for handle-based platforms
response#1response.integrations[].displayNamestring | null__11YesHuman-readable display name of the connected account
response#1response.integrations[].displayName[variant1]string__11_type:stringHuman-readable display name of the connected account
response#1response.integrations[].displayName[variant2]null__11_type:nullHuman-readable display name of the connected account
response#1response.integrations[].profileUrlstring | null__12YesPublic profile/page URL for the connected account, when it can be derivedkind: schemaFormat; value: uri
response#1response.integrations[].profileUrl[variant1]string__12_type:stringPublic profile/page URL for the connected account, when it can be derivedkind: schemaFormat; value: uri
response#1response.integrations[].profileUrl[variant2]null__12_type:nullPublic profile/page URL for the connected account, when it can be derivedkind: schemaFormat; value: uri
response#1response.integrations[].imageUrlstring | null__13YesProfile image URL for the connected account, or null if unavailablekind: schemaFormat; value: uri
response#1response.integrations[].imageUrl[variant1]string__13_type:stringProfile image URL for the connected account, or null if unavailablekind: ; value: uri
response#1response.integrations[].imageUrl[variant2]null__13_type:nullProfile image URL for the connected account, or null if unavailablekind: ; value: uri
response#1response.integrations[].platformMetadataobject__14NoProvider-specific public metadata for this connected account.
response#1response.integrations[].platformMetadata.[key: string]anytrueNo
response#1response.integrations[].profileIdstring | null__15YesProfile this integration belongs to, or null if it was connected without a profile
response#1response.integrations[].profileId[variant1]string__15_type:stringProfile this integration belongs to, or null if it was connected without a profile
response#1response.integrations[].profileId[variant2]null__15_type:nullProfile this integration belongs to, or null if it was connected without a profile
response#1response.integrations[].profileNamestring | null__16NoName 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#1response.integrations[].profileName[variant1]string__16_type:stringName 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#1response.integrations[].profileName[variant2]null__16_type:nullName 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#1response.integrations[].appIdstring | null__17YesThe OAuth app (customer's own OAuth app) this integration was connected under, or null if the service's system app was used.
response#1response.integrations[].appId[variant1]string__17_type:stringThe OAuth app (customer's own OAuth app) this integration was connected under, or null if the service's system app was used.
response#1response.integrations[].appId[variant2]null__17_type:nullThe OAuth app (customer's own OAuth app) this integration was connected under, or null if the service's system app was used.
response#1response.integrations[].appobject | null__18YesThe OAuth app metadata for BYOK integrations, or null when the service's system app was used.
response#1response.integrations[].app[variant1]object__18_type:objectThe OAuth app metadata for BYOK integrations, or null when the service's system app was used.
response#1response.integrations[].app[variant1].idstring__19No
response#1response.integrations[].app[variant1].namestring__20No
response#1response.integrations[].app[variant1].imageUrlstring | null__21No
response#1response.integrations[].app[variant1].imageUrl[variant1]string__21_type:string
response#1response.integrations[].app[variant1].imageUrl[variant2]null__21_type:null
response#1response.integrations[].app[variant2]null__18_type:nullThe OAuth app metadata for BYOK integrations, or null when the service's system app was used.
response#1response.integrations[].byokboolean__22YesTrue 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#1response.integrations[].authStatusstring__23YesWhether this integration can authenticate or needs OAuth reconnection
response#1response.integrations[].authStatus[variant1]string__23_extends:__24Whether this integration can authenticate or needs OAuth reconnectionkind: ; value: "active"
response#1response.integrations[].authStatus[variant2]string__23_extends:__25Whether this integration can authenticate or needs OAuth reconnectionkind: ; value: "reconnect_required"
response#1response.integrations[].authFailureReasonstring | null__26YesStable reason reconnection is required, or null while active
response#1response.integrations[].authFailureReason[variant1]string__26_extends:__27Stable reason reconnection is required, or null while activekind: ; value: "token_expired"
response#1response.integrations[].authFailureReason[variant2]string__26_extends:__28Stable reason reconnection is required, or null while activekind: ; value: "access_revoked"
response#1response.integrations[].authFailureReason[variant3]string__26_extends:__29Stable reason reconnection is required, or null while activekind: ; value: "security_invalidation"
response#1response.integrations[].authFailureReason[variant4]string__26_extends:__30Stable reason reconnection is required, or null while activekind: ; value: "refresh_rejected"
response#1response.integrations[].authFailureReason[variant5]null__26_extends:__31Stable reason reconnection is required, or null while active
response#1response.integrations[].insightsReadableboolean | null__32YesWhether 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#1response.integrations[].insightsReadable[variant1]boolean__32_type:booleanWhether 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#1response.integrations[].insightsReadable[variant2]null__32_type:nullWhether 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#1response.integrations[].createdAtstring__33Yeskind: ; value: date-time
response#2responseobject__0
response#2response.errorstring__1Yes