This guide walks through the full lifecycle of Google Business Profile (GBP) posts via the Hrizn Public API — from creating your first post to scheduling, cancelling, rescheduling, and deleting posts.
Prerequisites
- GBP connection — Connect your Google Business Profile account in the Hrizn dashboard. OAuth must be completed in the dashboard before the API can post on your behalf.
- API key with GBP scopes — Create an API key with
gbp:read and gbp:write scopes (or use the GBP Posting preset).
- Location ID — Know the GBP location ID you want to post to. This is available in the dashboard after connecting your GBP account.
Post types
| Type | Description | Required fields |
|---|
NEWS | General update | content_text |
EVENT | Event announcement | content_text, event_title, start_date |
OFFER | Promotional offer | content_text, event_title, start_date, offer fields |
CALL_TO_ACTION | Post with CTA button | content_text, action_type |
Creating an immediate post
The simplest case: publish a post to Google right now.
curl -X POST https://api.app.hrizn.io/v1/public/gbp/posts \
-H "X-API-Key: hzk_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"location_id": "locations/456",
"content_text": "Spring service special — 20% off all maintenance through April!",
"post_type": "NEWS"
}'
Scheduling a post
Add publish_at_utc and scheduled_timezone to schedule a post for a future time. The post is saved in the database with status scheduled and an AWS EventBridge Scheduler one-shot rule is created. At the scheduled time, Scheduler enqueues a message to an internal SQS queue; a worker Lambda consumes the message and publishes the post to Google. (The queue target stays stable across deploys so scheduled jobs are not tied to a specific Lambda ARN.)
curl -X POST https://api.app.hrizn.io/v1/public/gbp/posts \
-H "X-API-Key: hzk_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"location_id": "locations/456",
"content_text": "Tax Day Special: Free multi-point inspection with any service!",
"post_type": "NEWS",
"publish_at_utc": "2026-04-15T14:00:00.000Z",
"scheduled_timezone": "America/Chicago"
}'
status: "scheduled" and include the publish_at_utc and scheduled_timezone fields.
publish_at_utc must be in the future. The scheduled_timezone is stored for display purposes — the actual scheduling is always in UTC.
Creating an event post
Event posts include a title and schedule:
{
"location_id": "locations/456",
"content_text": "Join us for our annual Spring Car Show! Free food, live music, and amazing deals.",
"post_type": "EVENT",
"event_title": "Spring Car Show 2026",
"start_date": "2026-04-20",
"start_time": "10:00",
"end_date": "2026-04-20",
"end_time": "16:00",
"media_url": "https://example.com/car-show-banner.jpg"
}
Creating an offer post
Offer posts combine event scheduling with promotional details:
{
"location_id": "locations/456",
"content_text": "Save big this Memorial Day weekend! Up to $5,000 off select models.",
"post_type": "OFFER",
"event_title": "Memorial Day Sales Event",
"start_date": "2026-05-23",
"end_date": "2026-05-26",
"coupon_code": "MEMORIAL2026",
"redeem_url": "https://dealer.example.com/memorial-day",
"terms_conditions": "Valid May 23-26, 2026. Cannot be combined with other offers."
}
Creating a CTA post
Call-to-action posts include a button:
{
"location_id": "locations/456",
"content_text": "Schedule your spring maintenance today and save 15%!",
"post_type": "CALL_TO_ACTION",
"action_type": "BOOK",
"action_url": "https://dealer.example.com/service/book"
}
action_type values: ORDER, BOOK, SHOP, LEARN_MORE, SIGN_UP, CALL.
Listing and checking post status
# List all posts
curl "https://api.app.hrizn.io/v1/public/gbp/posts?limit=10" \
-H "X-API-Key: hzk_your_key_here"
# Filter by status
curl "https://api.app.hrizn.io/v1/public/gbp/posts?status=scheduled" \
-H "X-API-Key: hzk_your_key_here"
# Get a specific post
curl "https://api.app.hrizn.io/v1/public/gbp/posts/a1b2c3d4-..." \
-H "X-API-Key: hzk_your_key_here"
Cancelling a scheduled post
Cancel a scheduled post before it publishes:
curl -X POST "https://api.app.hrizn.io/v1/public/gbp/posts/a1b2c3d4-.../cancel" \
-H "X-API-Key: hzk_your_key_here"
scheduled can be cancelled. The EventBridge schedule is removed and the post status becomes cancelled.
Rescheduling a post
Change the publication time of a scheduled or failed post:
curl -X POST "https://api.app.hrizn.io/v1/public/gbp/posts/a1b2c3d4-.../reschedule" \
-H "X-API-Key: hzk_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"publish_at_utc": "2026-04-20T15:00:00.000Z",
"scheduled_timezone": "America/New_York"
}'
Rescheduling a failed post resets its retry counter, giving it a fresh attempt at the new time.
Deleting a post
Delete any post — posted, scheduled, or cancelled:
curl -X DELETE "https://api.app.hrizn.io/v1/public/gbp/posts/a1b2c3d4-..." \
-H "X-API-Key: hzk_your_key_here"
- Posted posts are first unpublished from Google, then removed from the database.
- Scheduled posts have their EventBridge schedule removed, then the record is deleted.
- Other statuses are deleted directly from the database.
Deleting a posted post will unpublish it from Google Business Profile. This cannot be undone.
Post lifecycle
Create (immediate) ─────────> posted ──────> deleted
│
└──> (Google removes after ~7 days for some types)
Create (scheduled) ─────────> scheduled ──> posted ──> deleted
│ │
│ └──> failed ──> reschedule ──> scheduled
│
└──> cancelled ──> deleted
Webhook events
If you have webhook subscriptions configured, GBP post lifecycle events are delivered to your endpoint:
| Event | Description |
|---|
gbp.post.published | Post was published to Google Business Profile |
gbp.post.scheduled | Post was scheduled for future publication |
gbp.post.cancelled | Scheduled post was cancelled |
gbp.post.failed | Post publication failed |
Error handling
| Scenario | HTTP Status | Error code |
|---|
| No GBP connection for site | 400 | validation_error |
| Invalid location ID | 400 | validation_error |
| Scheduled time in the past | 400 | validation_error |
| Cancel non-scheduled post | 400 | validation_error |
| Post not found | 404 | not_found |
Missing gbp:write scope | 403 | forbidden |
| Google API error | 400 | validation_error |
| OAuth token expired | 500 | internal_error |
