> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.hrizn.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Social posting & reviews

> Publish to social platforms and manage reviews via the API

The Social API lets you publish and schedule posts across every connected
platform and manage reviews — all through one unified surface modeled on the
underlying Zernio system. Posting and scheduling are handled by Zernio; the API
reflects status asynchronously.

## Supported platforms

| Platform                | `platform` value | Posting | Reviews |
| ----------------------- | ---------------- | :-----: | :-----: |
| X (Twitter)             | `twitter`        |   Yes   |    —    |
| Facebook                | `facebook`       |   Yes   |   Yes   |
| Instagram               | `instagram`      |   Yes   |    —    |
| LinkedIn                | `linkedin`       |   Yes   |    —    |
| Google Business Profile | `googlebusiness` |   Yes   |   Yes   |

Reviews are only available for Google Business Profile and Facebook.

## 1. Discover connected accounts

Accounts are connected in the Hrizn dashboard. List them to get the
`account_id` values to post with:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://api.app.hrizn.io/v1/public/social/accounts \
  -H "X-API-Key: hzk_your_key_here"
```

## 2. Create a post

A single post can target multiple platforms via the `platforms[]` array. Provide
`publish_now: true` to publish immediately, or `scheduled_for` (ISO 8601) plus
`scheduled_timezone` to schedule.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.app.hrizn.io/v1/public/social/posts \
  -H "X-API-Key: hzk_your_key_here" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -d '{
    "content": "Spring sales event this weekend!",
    "media_items": [{ "type": "image", "url": "https://cdn.example.com/promo.jpg" }],
    "platforms": [
      { "platform": "facebook", "account_id": "zacc_123" },
      { "platform": "googlebusiness", "account_id": "zacc_456" }
    ],
    "scheduled_for": "2026-07-04T15:00:00Z",
    "scheduled_timezone": "America/New_York"
  }'
```

The response is `202 Accepted` with the logical `id` (`post_id`). Use that id
for [get](/api-reference/social/get-post), [update](/api-reference/social/update-post),
[delete](/api-reference/social/delete-post),
[unpublish](/api-reference/social/unpublish-post), and
[retry](/api-reference/social/retry-post).

### Platform-specific options

Some platforms accept extra options via a **JSON-encoded** `platform_specific_data`
string on the relevant `platforms[]` entry:

| Platform         | `platform_specific_data`                                 | Notes                                                                                                                                                                                                                      |
| ---------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `linkedin`       | `{"organizationUrn":"urn:li:organization:123"}`          | Optional. The connected organization is used automatically — its `organization_urn` is returned on `GET /social/accounts`. Only pass this to override the default. Accounts that post as a personal profile need no value. |
| `googlebusiness` | `{"locationId":"<gbp-location-id>"}`                     | Targets a specific Google Business location. The `location_id` is available on each review from `GET /social/reviews`.                                                                                                     |
| `twitter`        | `{"poll":{"options":["A","B"],"duration_minutes":1440}}` | Attaches a poll.                                                                                                                                                                                                           |

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# LinkedIn organization post (URN taken from GET /social/accounts -> organization_urn)
curl -X POST https://api.app.hrizn.io/v1/public/social/posts \
  -H "X-API-Key: hzk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "We are hiring!",
    "platforms": [
      {
        "platform": "linkedin",
        "account_id": "zacc_li",
        "platform_specific_data": "{\"organizationUrn\":\"urn:li:organization:123\"}"
      }
    ],
    "publish_now": true
  }'
```

## 3. Track status

Status is updated asynchronously. Either poll
[`GET /social/posts/{id}`](/api-reference/social/get-post) or subscribe to
webhooks:

* `social.post.published`
* `social.post.scheduled`
* `social.post.failed`

## 4. Manage reviews

List reviews, generate an AI reply draft, then publish it:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Generate a draft
curl -X POST https://api.app.hrizn.io/v1/public/social/reviews/$REVIEW_ID/responses/generate \
  -H "X-API-Key: hzk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "brand_voice": "Friendly", "language": "English" }'

# Publish the generated draft (or post your own text)
curl -X POST https://api.app.hrizn.io/v1/public/social/reviews/$REVIEW_ID/responses \
  -H "X-API-Key: hzk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "response_id": "5f0c…" }'
```

New and updated reviews emit `social.review.created` and
`social.review.updated` webhooks.

## Scopes

| Capability                        | Scope           |
| --------------------------------- | --------------- |
| Read accounts, posts, reviews     | `social:read`   |
| Create / manage posts             | `social:write`  |
| Generate / publish review replies | `reviews:write` |