--- title: "Create Google Business Profile location" method: POST path: "/v1/accounts/{accountId}/gmb-locations" tags: ["Connect"] --- # Create Google Business Profile location `POST /v1/accounts/{accountId}/gmb-locations` ## Request - Base URL: `https://zernio.com/api` - URL: `https://zernio.com/api/v1/accounts/{accountId}/gmb-locations` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Creates a Google Business Profile listing under the Google account of this Zernio account and attaches it to this account, so verification, details, posts and reviews work on it right away. Only for an account with no location yet (connected with `allowNoLocation`). If the account already has a location, the request is rejected with 409 and nothing is created. Search first with `POST /v1/accounts/{accountId}/gmb-locations/search` to avoid duplicating an existing listing, and pick `primaryCategory` from `GET /v1/accounts/{accountId}/gmb-categories`. Required by Google: `title`, `languageCode` (immutable once set) and `primaryCategory`. At least one of `storefrontAddress` or `serviceArea` is required. When `storefrontAddress` is absent, at least one of `phone` or `websiteUri` is required. Both rules are checked before Google is called and a violation returns 400 naming the field. Set `validateOnly` to check the request with Google without creating anything: the response carries the would-be `location` and nothing is attached. A new listing is not on Google Maps until it is verified. `voiceOfMerchantState.hasVoiceOfMerchant` is `false` after creation; start verification with the `gmb-verifications` endpoints. `voiceOfMerchantState` is `null` if Google could not return it, and the listing was still created. If Google creates the listing but it cannot be attached, the error message names the created `locations/`; attach it with `PUT /v1/accounts/{accountId}/gmb-locations`. ## Path parameters - `accountId` string, required ## Headers - `Idempotency-Key` string ## Request body - object - `title` string, required: Business name as shown on Google. - `languageCode` string, required: BCP-47 language of the listing (e.g. "es"). Immutable after creation. - `primaryCategory` string, required: Category name from GET gmb-categories (e.g. "categories/gcid:cafe"). A bare "gcid:cafe" is also accepted. - `additionalCategories` string[]: Further category names, same format as primaryCategory. - `storefrontAddress` object: Physical address of the business. Required unless serviceArea is provided. - `regionCode` string, required: CLDR region code (e.g. "ES"). - `languageCode` string - `postalCode` string - `administrativeArea` string - `locality` string - `addressLines` string[], required - `serviceArea` object: Areas the business serves. Required unless storefrontAddress is provided. - `businessType` 'CUSTOMER_LOCATION_ONLY' | 'CUSTOMER_AND_BUSINESS_LOCATION', required - `regionCode` string: Required when businessType is CUSTOMER_LOCATION_ONLY. - `places` object - `placeInfos` object[] - `placeName` string, required - `placeId` string, required - `phone` string: Primary phone number. Required when storefrontAddress is absent and websiteUri is not set. - `websiteUri` string: Website URL. Required when storefrontAddress is absent and phone is not set. - `description` string: Business description (Google profile.description). - `regularHours` object: Google `regularHours` object (periods with openDay, openTime, closeDay, closeTime). - `validateOnly` boolean: Validate with Google without creating the listing or attaching anything. ## Response `200` Listing created and attached (or validated, when `validateOnly` is true) - object - `success` boolean - `accountId` string - `validateOnly` boolean: Present and true when validateOnly was requested. - `location` object: The location as Google returns it. `id` is present on a real create. - `voiceOfMerchantState` object, nullable: Verification state of the new listing; null if Google could not return it. ## Other responses - `400`: Invalid request - `401`: Missing or invalid API key. `code` is `missing_credentials` when no Authorization header was sent and `invalid_credentials` when the key is unknown, revoked or expired. - `403`: The API key is a restricted key (zrk_ prefix) and may not perform this operation. Three cases: 1. The operation's resource group (see the operation's x-resource-group) is disabled on the key. Fix: create a key with the group enabled in the dashboard API keys tab and revoke the old one. 2. The operation is admin-plane (x-resource-group admin-plane: API keys, invites, connected apps, member identity), never grantable to restricted keys. The error reads "Restricted API keys cannot manage API keys, invites, or member identity." Fix: a full-access key or the dashboard, never a new restricted key. 3. On webhook subscription writes, delivery-log reads and replays, a named event maps to a resource group the key does not hold. A restricted key can never create or edit a subscription broader than itself (a no-messages key cannot subscribe to, test-fire, redeliver or read logs for message.* events). - `404`: Account not found - `409`: The account already has a location (code `profile_platform_conflict`), or the same `Idempotency-Key` is still processing; retry after a short backoff. - `422`: Idempotency-Key reused with a different request - `500`: Google created the listing but it could not be attached to this account. The message names the created `locations/`; attach it with `PUT /v1/accounts/{accountId}/gmb-locations`. ## Changes - **2026-11-12** `081e9a361b7a`: 1 info - endpoint added [Operation history](https://skmtc.dev/zernio/apis/zernio-api/changes/v1/accounts/:accountId/gmb-locations/post.md) --- [API](https://skmtc.dev/zernio/apis/zernio-api.md) - [All operations](https://skmtc.dev/zernio/apis/zernio-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zernio/apis/zernio-api/revisions/e1617f0f422b?raw)