POST
/
oauth
/
google
/
generate-url
cURL
curl --request POST \
  --url https://api.gmbapi.com/external-api/gmb/oauth/google/generate-url \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "state": "<string>",
  "redirect_url": "<string>"
}
'
{
  "success": true,
  "url": "https://accounts.google.com/o/oauth2/v2/auth?access_type=offline&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fuserinfo.email%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fuserinfo.profile%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fbusiness.manage&state=a1b2c3d4e5f6&redirect_uri=YOUR_CALLBACK_URL&client_id=YOUR_CLIENT_ID"
}
This endpoint generates a Google OAuth authorization URL that can be used to authenticate and authorize access to Google Business Profile data. The generated URL includes the necessary scopes and a secure state parameter for validation.

​
OAuth Flow

  1. Generate URL - Call this endpoint with your state and redirect_url
  2. Redirect User - Redirect the user to the generated URL
  3. User Authorizes - User grants permissions on Google’s consent screen
  4. Callback - User is redirected back to your redirect_url with authorization results

​
Scopes Included

The generated OAuth URL requests the following permissions:
  • userinfo.email - Access to user’s email address
  • userinfo.profile - Access to user’s basic profile information
  • business.manage - Manage Google Business Profile locations

​
Callback Query Parameters

After the OAuth flow completes, the user will be redirected to your specified redirect_url with the following query parameters:

​
Success Callback

When authorization is successful, your callback URL will receive: 
https://your-redirect-url.com?uid={uid}&googleId={google_user_id}&billing_id={organization_id}&token_refreshed={true|false}&external_api=true&state={state}
  • uid - User identifier (null for external API)
  • googleId - Google user ID
  • billing_id - Organization ID
  • token_refreshed - Whether a refresh token was obtained
  • external_api - Always true for external API calls
  • state - The original state parameter

​
Error Callbacks

If there’s an error during the OAuth flow, your callback URL will receive an error parameter:

​
User Denied Access

https://your-redirect-url.com?error=access_denied
User declined to grant permissions on Google’s consent screen.

​
Invalid State

https://your-redirect-url.com?error=invalid_state
The state parameter validation failed or the request was not from external API.

​
Invalid Grant/Scope

https://your-redirect-url.com?error=invalid_grant
Required scope (business.manage) was not granted by the user.

​
General OAuth Error

https://your-redirect-url.com?error=oauth_error
An unexpected error occurred during the OAuth callback processing.

​
Connect Account Endpoint

After receiving the OAuth callback with the authorization parameters, you need to call the connect account endpoint to complete the account connection process. This endpoint processes the authorization and creates the Google Business Profile account connection.

​
Endpoint

POST /connect/account

​
Query Parameters

  • uid (string) - User identifier
  • googleId (string) - Google user ID from the OAuth callback
  • id (string) - Account identifier
  • billing_id (string) - Organization/billing ID
  • external_api (boolean) - Must be true for external API calls
  • state (string) - The state parameter from your OAuth flow

​
External API Response Format

When external_api=true, the endpoint returns a JSON object with a redirect URL instead of the standard response: 
{
  "url": "https://your-redirect-url.com?status=success&gmb_profile_id={profile_id}&business_name={name}&state={state}",
  "external_api": true
}

​
Success Response

When the account is successfully connected, the returned URL contains: 
https://your-redirect-url.com?status=success&gmb_profile_id={gmb_profile_id}&business_name={business_name}&state={state}
Query Parameters:
  • status - Always success for successful connections
  • gmb_profile_id - The Google Business Profile account ID
  • business_name - The name of the connected business (URL encoded)
  • state - The original state parameter from your OAuth flow

​
Error Responses

When an error occurs during account connection, the returned URL contains error details: 
https://your-redirect-url.com?status=error&error_message={error_message}&state={state}
Query Parameters:
  • status - Always error for failed connections
  • error_message - A description of the error (URL encoded)
  • state - The original state parameter from your OAuth flow

​
Specific Error Messages

ACCOUNT_ALREADY_CONNECTED 
status=error&error_message=ACCOUNT_ALREADY_CONNECTED
The Google account has already been connected to your organization. TOO_MANY_REQUESTS 
status=error&error_message=TOO_MANY_REQUESTS
Too many connection requests are being processed. Please wait before retrying. NO_LOCATION_FOUND 
status=error&error_message=NO_LOCATION_FOUND
No Google Business Profile locations were found for this account. Account Info Error 
status=error&error_message=Error getting account info from Google
An error occurred while retrieving account information from Google’s API. Generic Errors Any other errors will include the specific error message in the error_message parameter.

​
Example Flow

  1. User completes OAuth authorization and is redirected to your callback URL with authorization parameters
  2. Your application calls POST /connect/account with all required parameters, including external_api=true
  3. If successful, redirect the user to the url provided in the response (contains success status and profile details)
  4. If an error occurs, redirect the user to the url provided in the response (contains error status and message)

​
Disconnect Account Endpoint

The disconnect account endpoint allows you to remove a connected Google Business Profile account from your organization. This will disconnect the account, remove all associated data, and update subscription billing accordingly.

​
Endpoint

DELETE /disconnect/account

​
Query Parameters

  • uid (string) - User identifier
  • googleId (string) - Google user ID of the account to disconnect
  • id (string) - Account identifier (GMB profile ID)
  • external_api (boolean) - Must be true for external API calls
  • state (string) - The state parameter from your OAuth flow

​
External API Response Format

When external_api=true, the endpoint returns a JSON object with a redirect URL: 
{
  "url": "https://your-redirect-url.com?status=success_disconnect&state={state}&account_id={account_id}",
  "external_api": true
}

​
Success Response

When the account is successfully disconnected, the returned URL contains: 
https://your-redirect-url.com?status=success_disconnect&state={state}&account_id={account_id}
Query Parameters:
  • status - Always success_disconnect for successful disconnections
  • state - The original state parameter from your OAuth flow
  • account_id - The ID of the disconnected account

​
What Happens on Disconnect

When an account is disconnected, the following actions are performed:
  1. The business account is removed from the user’s account
  2. The Google account access tokens are removed
  3. The account is removed from the billing/organization
  4. If there’s an active subscription, it’s updated to reflect the new number of locations (excluding the disconnected account)

​
Example Flow

  1. Your application calls DELETE /disconnect/account with the account details and external_api=true
  2. The account is disconnected and all associated data is removed
  3. Redirect the user to the url provided in the response (contains success status and account ID)

​
Reconnect Account Endpoint

The reconnect account endpoint allows you to refresh and update the connection for an existing Google Business Profile account. This is useful when access tokens have expired or need to be refreshed. The endpoint updates the access tokens and triggers a data export.

​
Endpoint

POST /reconnect/account

​
Query Parameters

  • uid (string) - User identifier
  • googleId (string) - Google user ID of the account to reconnect
  • id (string) - Account identifier (GMB profile ID)
  • external_api (boolean) - Must be true for external API calls
  • state (string) - The state parameter from your OAuth flow

​
External API Response Format

When external_api=true, the endpoint returns a JSON object with a redirect URL instead of the standard response: 
{
  "url": "https://your-redirect-url.com?status=success_reconnect&state={state}&account_id={account_id}",
  "external_api": true
}

​
Success Response

When the account is successfully reconnected, the returned URL contains: 
https://your-redirect-url.com?status=success_reconnect&state={state}&account_id={account_id}
Query Parameters:
  • status - Always success_reconnect for successful reconnections
  • state - The original state parameter from your OAuth flow
  • account_id - The ID of the reconnected account

​
Error Responses

When an error occurs during account reconnection, the returned URL contains error details: 
https://your-redirect-url.com?status=error&error_message={error_message}&state={state}
Query Parameters:
  • status - Always error for failed reconnections
  • error_message - A description of the error (URL encoded)
  • state - The original state parameter from your OAuth flow

​
Common Error Scenarios

NotFoundException The account or refresh token was not found. This typically occurs when:
  • The account ID does not exist
  • The refresh token is missing or invalid
  • The Google user ID does not match an existing account
Generic Errors Any other errors will include the specific error message in the error_message parameter. These may include token refresh failures or API communication errors.

​
What Happens on Reconnect

When an account is reconnected, the following actions are performed:
  1. The refresh token is retrieved for the Google account
  2. The account access token is updated with the new refresh token
  3. The business account reconnect information is updated
  4. A data export is triggered for the account

​
Example Flow

  1. Your application calls POST /reconnect/account with the account details and external_api=true
  2. The account access tokens are refreshed and updated
  3. If successful, redirect the user to the url provided in the response (contains success status and account ID)
  4. If an error occurs, redirect the user to the url provided in the response (contains error status and message)

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

OAuth URL generation parameters

​
redirect_url
string
required

URL where the user will be redirected after OAuth authorization

​
state
string

Custom state data to be included in the OAuth flow for validation

Response

OAuth URL generated successfully. Redirect the user to this URL to begin the authorization flow.

​
success
boolean

Indicates if the request was successful

​
url
string

The generated Google OAuth authorization URL