Verify a location

Google only fully trusts a listing once the business proves it is real. Until then reviews do not come through, many edits do not publish and some listing data is missing. Google calls a verified, published listing "Voice of Merchant". This page shows how to check that state and run a verification from your own product, so a new client never has to leave it to finish setup.

#Check the state

GET /v1/accounts/{accountId}/gmb-verifications returns the location's Voice of Merchant state and its verification history.

curl https://api.pozy.ai/v1/accounts/6713b0e5d1f4c69a2b8e3f75/gmb-verifications \
  -H "Authorization: Bearer $POZY_API_KEY"

const res = await fetch("https://api.pozy.ai/v1/accounts/6713b0e5d1f4c69a2b8e3f75/gmb-verifications", {
  headers: { Authorization: `Bearer ${process.env.POZY_API_KEY}` },
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);

if (!data.voiceOfMerchantState.hasVoiceOfMerchant) {
  console.log("Not verified. Pending:", data.voiceOfMerchantState.verify?.hasPendingVerification);
}

import os
import requests

H = {"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"}
state = requests.get(
    "https://api.pozy.ai/v1/accounts/6713b0e5d1f4c69a2b8e3f75/gmb-verifications",
    headers=H, timeout=30,
).json()
print(state["voiceOfMerchantState"])

{
  "success": true,
  "accountId": "6713b0e5d1f4c69a2b8e3f75",
  "locationId": "4821930576104832190",
  "voiceOfMerchantState": {
    "hasVoiceOfMerchant": false,
    "hasBusinessAuthority": true,
    "verify": { "hasPendingVerification": false }
  },
  "verifications": [
    { "name": "locations/4821930576104832190/verifications/7Q2093841176", "method": "SMS", "state": "FAILED", "createTime": "2026-10-20T15:02:00Z" }
  ]
}

A verified location also needs to be matched to a published Maps place before reviews appear. That shows up as a non-null placeId in location details.

#Run a verification

curl -X POST https://api.pozy.ai/v1/accounts/6713b0e5d1f4c69a2b8e3f75/gmb-verifications/options \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "languageCode": "pt-PT" }'

{
  "success": true,
  "options": [
    { "verificationMethod": "SMS", "phoneNumber": "+351210000123" },
    { "verificationMethod": "PHONE_CALL", "phoneNumber": "+351210000123" },
    { "verificationMethod": "ADDRESS" }
  ]
}

curl -X POST https://api.pozy.ai/v1/accounts/6713b0e5d1f4c69a2b8e3f75/gmb-verifications \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "method": "SMS", "languageCode": "pt-PT", "phoneNumber": "+351210000123" }'

curl -X POST https://api.pozy.ai/v1/accounts/6713b0e5d1f4c69a2b8e3f75/gmb-verifications/7Q2093841177/complete \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "pin": "482913" }'

const res = await fetch("https://api.pozy.ai/v1/accounts/6713b0e5d1f4c69a2b8e3f75/gmb-verifications/7Q2093841177/complete", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.POZY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ pin: "482913" }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);

console.log(data.verification.state); // "COMPLETED" or "FAILED"

resp = requests.post(
    "https://api.pozy.ai/v1/accounts/6713b0e5d1f4c69a2b8e3f75/gmb-verifications/7Q2093841177/complete",
    headers=H, json={"pin": "482913"}, timeout=30,
)
print(resp.json()["verification"]["state"])

#Build it into onboarding

A simple flow for new locations:

1. After the account connects, read the verification state.
2. If hasVoiceOfMerchant is true, continue.
3. If a verification is pending, ask the owner for the code they received and submit it.
4. Otherwise fetch the options, let the owner pick one, start it, and ask for the code.

Postcards can take days to arrive, so let the owner close your app and come back to step 3 later.

#Common errors

#Endpoints