GBP

GBP endpoints power the dashboard connection flow for Google Business Profile. They use the signed-in app session, not X-NearIQ-Key, and operate on the user’s active accessible business.

These endpoints are not public v1 API-key endpoints. They require an authenticated dashboard session and may return 401 when the session is missing.

GET /api/gbp/connect

Starts the OAuth connection flow and redirects the browser to the consent screen.

curl -i "https://app.neariq.io/api/gbp/connect?returnTo=/settings?tab=business" \
  -H "Cookie: <dashboard session cookie>"

string

Optional relative path to return to after a successful connection. Non-relative values are ignored.

string

Set to 1 when the user is explicitly authorizing spreadsheet export access in the same flow.

string

Set to sheets as an alternate way to include spreadsheet export access.

Successful responses redirect to the OAuth consent screen. Missing app integration configuration returns:

{
  "error": "GBP integration not configured."
}

GET /api/gbp/callback

Handles the OAuth callback, verifies the signed-in user matches the state payload, stores encrypted tokens, discovers the first available location, and redirects back to the requested dashboard path.

curl -i "https://app.neariq.io/api/gbp/callback?code=<oauth_code>&state=<state>"

Successful callbacks redirect to the return path with gbp=connected. Failure redirects include gbp=error and a reason such as missing_code, invalid_state, auth_mismatch, token_exchange_failed, no_business, or encryption_unavailable.

GET /api/gbp/status

Returns the current user’s visible GBP connection status.

curl "https://app.neariq.io/api/gbp/status" \
  -H "Cookie: <dashboard session cookie>"

{
  "connected": true,
  "businessId": "f7f1ec9a-8775-45e0-b09a-4e2de2c9252d",
  "locationTitle": "Aster Grove Fitness",
  "locationName": "locations/123456789",
  "connectedAt": "2026-05-31T10:30:00.000Z"
}

When no connection is visible:

{
  "connected": false
}

POST /api/gbp/disconnect

Disconnects the visible GBP connection for the active business. Token revocation is best effort; the local connection is removed either way.

curl -X POST "https://app.neariq.io/api/gbp/disconnect" \
  -H "Cookie: <dashboard session cookie>"

{
  "ok": true,
  "disconnected": true,
  "connected": false,
  "businessId": "f7f1ec9a-8775-45e0-b09a-4e2de2c9252d"
}

If there is no visible connection, the response is still successful:

{
  "ok": true,
  "disconnected": false,
  "connected": false
}

GET /api/gbp/reviews

Fetches reviews for the active connected location and normalizes them for the dashboard review reply flow.

curl "https://app.neariq.io/api/gbp/reviews" \
  -H "Cookie: <dashboard session cookie>"

{
  "reviews": [
    {
      "reviewName": "accounts/123/locations/456/reviews/abc",
      "rating": 5,
      "text": { "text": "Best class in town." },
      "authorAttribution": {
        "displayName": "Jane D.",
        "photoUri": "https://example.com/avatar.jpg"
      },
      "relativePublishTimeDescription": "",
      "publishTime": "2026-05-30T18:00:00Z",
      "ownerResponse": "Thank you Jane.",
      "ownerResponseDate": "2026-05-30T19:00:00Z"
    }
  ],
  "ownerResponseRate": 72
}

If the active business is missing or not connected, the route returns an empty review array with an explanatory error value.

POST /api/gbp/reply

Posts or updates a reply to a GBP review.

curl -X POST "https://app.neariq.io/api/gbp/reply" \
  -H "Content-Type: application/json" \
  -H "Cookie: <dashboard session cookie>" \
  -d '{
    "reviewName": "accounts/123/locations/456/reviews/abc",
    "comment": "Thank you for visiting Aster Grove Fitness."
  }'

string

required

Full review resource name returned by GET /api/gbp/reviews.

string

Reply text. Either comment or reply is accepted.

string

Alternate reply text field kept for legacy clients.

{
  "ok": true,
  "reply": {
    "comment": "Thank you for visiting Aster Grove Fitness.",
    "updateTime": "2026-05-31T10:45:00Z"
  }
}

Org-owned businesses require the review_responses_post permission.

DELETE /api/gbp/reply

Deletes a reply from a GBP review. DELETE /api/gbp/reviews/reply is an alias for the same handler.

curl -X DELETE "https://app.neariq.io/api/gbp/reply" \
  -H "Content-Type: application/json" \
  -H "Cookie: <dashboard session cookie>" \
  -d '{ "reviewName": "accounts/123/locations/456/reviews/abc" }'

{
  "ok": true
}

POST /api/gbp/post

Creates a local post for the active connected GBP location.

This endpoint requires a plan with gbpAutoPost access. Org-owned businesses also require the social_media_publish permission.

curl -X POST "https://app.neariq.io/api/gbp/post" \
  -H "Content-Type: application/json" \
  -H "Cookie: <dashboard session cookie>" \
  -d '{
    "summary": "Join us this Saturday for a free intro class.",
    "callToAction": {
      "actionType": "SIGN_UP",
      "url": "https://example.com/intro"
    },
    "mediaUrl": "https://example.com/class-photo.jpg"
  }'

string

required

Post text. Must be 1-1500 characters.

string

One of BOOK, ORDER, SHOP, LEARN_MORE, SIGN_UP, or CALL.

string

Optional CTA URL.

string

Optional public image URL.

{
  "success": true,
  "postName": "accounts/123/locations/456/localPosts/789",
  "state": "LIVE",
  "createTime": "2026-05-31T10:50:00Z"
}

POST /api/gbp/bulk-post

Creates the same local post for multiple owned business locations.

curl -X POST "https://app.neariq.io/api/gbp/bulk-post" \
  -H "Content-Type: application/json" \
  -H "Cookie: <dashboard session cookie>" \
  -d '{
    "businessIds": [
      "f7f1ec9a-8775-45e0-b09a-4e2de2c9252d",
      "0f3a7347-bdb5-44fd-8f1e-9f1fbb15c553"
    ],
    "summary": "New weekend classes are open for booking.",
    "callToAction": { "actionType": "BOOK" }
  }'

array

required

Owned business IDs to post to. The route accepts 1-50 IDs.

string

required

Post text. Must be 1-1500 characters.

{
  "results": [
    {
      "businessId": "f7f1ec9a-8775-45e0-b09a-4e2de2c9252d",
      "businessName": "Aster Grove Fitness",
      "success": true
    }
  ],
  "summary": {
    "total": 1,
    "success": 1,
    "failed": 0
  }
}

Bulk posting requires a plan with gbpAutoPost access and only posts to businesses owned by the signed-in user.

API Reference

Endpoints

Webhooks

GET /api/gbp/connect

GET /api/gbp/callback

GET /api/gbp/status

POST /api/gbp/disconnect

GET /api/gbp/reviews

POST /api/gbp/reply

DELETE /api/gbp/reply

POST /api/gbp/post

POST /api/gbp/bulk-post

​GET /api/gbp/connect

​GET /api/gbp/callback

​GET /api/gbp/status

​POST /api/gbp/disconnect

​GET /api/gbp/reviews

​POST /api/gbp/reply

​DELETE /api/gbp/reply

​POST /api/gbp/post

​POST /api/gbp/bulk-post

GET /api/gbp/connect

GET /api/gbp/callback

GET /api/gbp/status

POST /api/gbp/disconnect

GET /api/gbp/reviews

POST /api/gbp/reply

DELETE /api/gbp/reply

POST /api/gbp/post

POST /api/gbp/bulk-post