Google Business Profile

The Google Business Profile connector lets you manage the businesses your clients have on Google Search and Maps from MauKirim: see every business in one list, keep its name, phone, website, description, categories and opening hours up to date, publish posts, add photos, read performance numbers and reviews, answer the reviews, and drive verification. You do it from the dashboard, through the REST API or through an assistant over MCP.

There are three ways to bring a business in: connect a Google account yourself, connect an agency manager account that holds many clients, or — if you run a platform — let each of your own clients connect theirs on a page MauKirim hosts: see Connect your clients’ Google Business Profiles.

Everything you change here is public: a new business name, a new opening hour or a reply to a review is visible to anyone who searches for the business on Google.

Who gets it

The connector is included in the Growth package and every package above it. It is part of the plan, not a per-call purchase: nothing in it is charged from your credit balance (see Credits and pricing). An account on a package without it sees an explanation in the dashboard, and every API call answers 402 gmb_plan_required.

How many businesses you can keep connected at once depends on the package:

Package	Businesses connected at once
Growth	10
Business	50
Scale	200
Platform	1,000

The count is of businesses in the active status, including the ones your own clients connect through the hosted flow. Switching businesses on is your choice: when a Google account is connected or synced, every business it can manage is imported switched off (status: disabled, disabledBy: user), and a switched-off business costs no allowance. Nothing is skipped or lost, even when the account can see more businesses than your package allows: they all appear in your list, and you turn on the ones you want now or later, up to the allowance (below). A downgrade stops new calls (402 gmb_plan_required) but never deletes what was imported.

Before you start

You need a Google account that can manage the business profile — an Owner or a Manager of it. A role with fewer rights can be refused by Google when you edit or reply.
The business should already exist on Google as a Business Profile — or you can create a new one under a connected account through the API or an assistant (below). Claiming a listing that somebody else owns is not possible from here.
Whoever owns that Google account has to approve the connection themselves in a browser. Nobody — not MauKirim, not your assistant, not an API key — can approve it for them.

Connect a Google account

Sign in to MauKirim and open Services → Google Business (/services/gmb).
Choose Connect Google account. You can give the connection a label, such as the agency or client name, to recognise it later.
Google’s own consent screen opens. Pick the Google account that manages the businesses and read what it asks for: permission to manage your Business Profile (business.manage) and to know which account you are signed in as (name, email). MauKirim never sees the Google password.
Approve. Google sends you back to MauKirim, which stores the permission encrypted, reads the businesses the account can manage, and shows them in the list. A first sync of a large agency is paced by the shared rate limit; if it cannot finish at once the connection is kept and the rest arrives within a few minutes.

You will see a connection (the Google account) and, under it, its businesses, all switched off: they wait for you to choose which to turn on.

Choose which businesses are on

A business that is off costs no allowance and is not acted on (reading its reviews, posting, editing and so on answer 409 gmb_location_disabled), but it stays in your list and nothing about it is lost. Turn on the ones you want to manage, and turn others off again whenever you like:

In the dashboard, switch businesses on or off from the businesses list.
Through the API, POST /gmb/locations/activation with activate and/or deactivate lists of business ids (scope gmb). List the ones waiting with GET /gmb/locations?status=disabled.
Through an assistant, the MCP tool set_gmb_locations_active (see MCP).

Turning businesses on is checked against your package’s allowance as a whole: if it would not fit, nothing changes (409 gmb_location_limit), so you never end up with half a choice. Turn some off first, or upgrade, and choose again. You can turn a business on later at any time; sync again later and the businesses Google added since arrive off as well, waiting for your choice.

Connect an agency manager account

If you manage many clients, do not connect each client’s own Google account. Instead:

Ask each client to add your agency’s Google account as a Manager of their business profile, in Google’s own Business Profile settings (Settings → People and access). The client does this once.
Accept the invitation from the agency account.
Connect the agency account to MauKirim, as above. One consent covers every business that account can manage: the sync lists each Google “account” and location it can see, so a hundred clients are one connection.

If your clients should connect their own accounts without a MauKirim login, use the hosted flow in Connect your clients’ Google Business Profiles instead.

You can connect more than one Google account; each is a separate connection and its businesses are listed together. Connecting the same Google account again does not create a second connection: it refreshes the first one and brings back a connection that needed reconnecting.

What you can do with a connected business

Everything is addressed by the business’s MauKirim id (gml_…), from the dashboard, the REST API or an assistant over MCP. Reads need the read or gmb scope; every change needs gmb.

You can	Where
List businesses, read one (stored or live), filter by your own client’s id	Businesses
Change title, phone, website, description, opening hours, special hours, open status, categories and labels	Businesses
Read reviews, write, replace or remove your own reply	Reviews
Publish, edit and delete posts (updates, events, offers, with a button and a photo)	Posts
List, upload (a JPEG or PNG file), add (by URL) and delete photos and videos	Photos
Create a new business under a connected account, or delete one from Google	Create and delete
Read daily performance metrics and the search keywords that showed the business	Insights
Read and change attributes; search the category list	Attributes and categories
See the verification history, the methods Google offers, start a verification and enter the code	Verification
See who manages a business, invite a manager or remove one	Managers
Reach every other location-scoped Business Profile API (place action links, lodging, …)	The Google door
Connect your own clients’ accounts and disconnect them	Connect your clients

MauKirim cannot
Claim a listing somebody else owns, change a business’s address after it is created, or transfer ownership (an owner changes that in Google)
Delete, edit or hide a customer’s review, or reply on behalf of another business
Make someone an owner: managers can be invited as `MANAGER` or `SITE_MANAGER` only
Upload a video or a GIF, WebP or HEIC photo (photos are JPEG or PNG; videos are added by public https URL)
Answer or read questions and answers: Q&A is not offered. We have not built on it, and Google has been retiring that API; check Google’s documentation before relying on it
Receive Google’s push notifications (Pub/Sub)

It reads and writes only what the permission allows, and it never changes a business you did not connect.

Create and delete a business

Create. Under a connected Google account you can open a new business: its name, categories (the first is primary), address, and optionally phone, website, description and opening hours. Ask Google to check it first (validateOnly), then create it; it appears in your list at once, already on, so it counts against your business allowance (and is refused before anything exists on Google when the allowance is full), and a retry with the same Idempotency-Key never creates a second business. A new business is unverified: verify it (verification), then add its photos and posts. Reference: POST /gmb/connections/{id}/locations.

Delete. DELETE /gmb/locations/{id} removes the business from Google for good, and only when you type its exact title back. MauKirim keeps the row as removed_upstream. To stop managing a business without removing it from Google, disconnect the connection.

Photos and managers

A photo can be uploaded as a file (JPEG or PNG, 10 KB to 5 MB; it costs three Google calls) or added by public URL; see Photos. You can invite a person to manage a business, as MANAGER or SITE_MANAGER, and remove one; Google sends the invitation email. Ownership is never offered here. See Managers.

Which Google APIs, and approval

The connector uses several separate Google APIs: Account Management and Business Information (businesses), the My Business API v4 (reviews, posts, photos), the Performance API (insights), the Verifications API (verification), and the Place Actions and Lodging APIs (through the Google door). Each has to be enabled for the Google project MauKirim runs under, and Google may require its own approval for some of them. An unavailable one answers 503 gmb_api_unavailable for that feature only, while the others keep working. That is an operator matter, not an account one; we cannot tell you from here which APIs a given deployment has, and where we are unsure how Google behaves we say so on the page of the feature.

Statuses

A business has one of these statuses:

Status	Meaning	What you can do
`active`	Connected, reachable and counted against your allowance	Everything
`needs_reauth` (shown on its connection)	Google no longer accepts the permission — the owner revoked it, or the Google password changed	Reconnect the account; calls fail with `gmb_reconnect_required` until you do
`removed_upstream`	The business no longer appears under the Google account (deleted, transferred, or the manager access was removed)	Reads of the stored copy still work; live reads, edits and replies answer `gmb_location_not_found`. It returns to `active` when it reappears in a sync
`disabled`	Switched off. `disabledBy` says who: `user` (every business found on connect or sync starts here, waiting for your choice, or you turned it off), `operator` (MauKirim support) or `connection` (its connection was disconnected or lost). It costs no allowance	Reads of the stored copy work; changes answer `gmb_location_disabled`. Turn a `user` one on with `POST /gmb/locations/activation`

A connection (the Google account) has one of these statuses:

Status	Meaning
`active`	Working
`needs_reauth`	Google refused the saved permission. Reconnect it from the dashboard. You also receive an alert
`revoked`	You disconnected it from MauKirim
`suspended`	An operator switched it off; calls answer `gmb_location_disabled`

Only the active businesses of an active connection are usable. Statuses appear as status on businesses and connections.

Disconnect

You can end access from either side, and you should know both.

From MauKirim. Open the connection in Services → Google Business and choose Disconnect — or call DELETE /gmb/connections/{id} (scope gmb), which is how you offboard one of your own clients, or the MCP tool disconnect_gmb_connection. MauKirim asks Google to forget the saved permission, marks the connection revoked, and switches its businesses to disabled. Your history and usage numbers stay. If Google cannot be reached at that moment the disconnect still completes on our side — leaving is never blocked by a Google outage.

From Google. Open myaccount.google.com/permissions, choose MauKirim and select Delete all connections (or Remove access). The next call MauKirim makes with that permission is refused by Google; the connection becomes needs_reauth, you get an alert, and nothing more is read or changed. This is the right move if you suspect the Google account itself was compromised.

Removing a business from the connected account in Google (or removing the agency as a manager) has the same effect on that business only: it becomes removed_upstream at the next sync.

Troubleshooting

“No locations found” after connecting. The Google account you approved manages no business profile, or manages them through another account. Check that you chose the right Google account on the consent screen and that it appears as an Owner or Manager in the business’s own settings on Google. If you use an agency account, confirm the client’s invitation was accepted. Then press Sync: a business added in Google minutes ago can take a moment to appear.

A business is missing, but others show up. It is probably there, but switched off: every business found on connect or sync starts off. List with GET /gmb/locations?status=disabled and turn it on (above). If turning it on answers gmb_location_limit, your package’s allowance is full: turn another business off, or upgrade.

gmb_forbidden when editing or replying. Google answered that the connected account has no right over that business. The usual cause is a role with too few rights, or access that was removed. Ask the owner to make the account an Owner or Manager of the business.

gmb_api_unavailable. This one is not about your account. Google refused because a Business Profile API is not switched on, or not yet approved, for the Google project MauKirim runs under. If it is on everything, including the first sync, the core API is missing; if it is only on insights, verification, place action links or lodging, that one API is. Nothing you do can fix it — contact MauKirim support.

An unverified location. A business that Google has not verified shows verificationState of unverified. Google may refuse edits to it, or not show your changes publicly until it is verified. You can start it from MauKirim (verification) when Google offers a method for the business, but the code goes to the business, not to MauKirim.

A connection says needs_reauth. Choose Reconnect on the connection and approve again with the same Google account. Its businesses come back as they are.

The consent screen shows a warning (“Google hasn’t verified this app”). Permission to manage a Business Profile is a sensitive Google permission. A deployment whose Google client has not completed Google’s verification shows this warning to every user and limits the number of accounts that can connect. On a deployment you do not operate, do not approve a consent screen you do not trust and ask the operator; on your own deployment see the runbook in docs/gmb.md. The warning is about the app’s review status, not about your account’s safety.

gmb_rate_limited. Not a fault: the shared Google budget or your account’s share is spent for a moment. Wait the number of seconds in Retry-After and try again — see Google Business rate limits.

Everything fails with gmb_plan_required. Your package does not include the connector. Upgrade it in Billing.