---
title: Suggest a time for a draft
url: /docs/developers/reference/social-edition-propose
---

# Suggest a time for a draft

`social.edition.propose@1`

Suggest a time for a draft, or take the suggestion back. Requires **Write social**. A suggestion is two cells beside the post: it never approves, schedules or posts anything, moves no approval or approval digest, and a draft that is not approved can never be placed by suggesting a time for it. Approving later keeps the suggested time; scheduling is still your own action, and placing the post takes the suggestion back.

## Suggest a time for a draft

The draft keeps its status and approval; only the suggestion is written. Send the revision you read. Send `"proposedAt": null` with no zone to take it back.

```curl tabs
# A new operationId for each new request; the same one to retry it.
curl https://api.growlocal.site/api/v1/profiles/YOUR_BUSINESS_ID/invocations \
  -H "Authorization: Bearer gl_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "target": {
    "featureId": "YOUR_FEATURE_ID",
    "export": "proposeEdition",
    "contractRef": "social.edition.propose@1"
  },
  "operationId": "propose-time-1",
  "input": {
    "edition": {
      "ref": {
        "businessProfileId": "YOUR_BUSINESS_ID",
        "featureId": "juniper-cakes.data",
        "collectionId": "juniper-cakes.editions",
        "id": "YOUR_EDITION_ID"
      },
      "revision": 1
    },
    "proposedAt": "2031-06-03T16:00:00Z",
    "displayTimeZone": "America/Phoenix"
  }
}'
```

```javascript tabs
// A new operationId for each new request; the same one to retry it.
const response = await fetch(
  "https://api.growlocal.site/api/v1/profiles/YOUR_BUSINESS_ID/invocations",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer gl_YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "target": {
        "featureId": "YOUR_FEATURE_ID",
        "export": "proposeEdition",
        "contractRef": "social.edition.propose@1"
      },
      "operationId": "propose-time-1",
      "input": {
        "edition": {
          "ref": {
            "businessProfileId": "YOUR_BUSINESS_ID",
            "featureId": "juniper-cakes.data",
            "collectionId": "juniper-cakes.editions",
            "id": "YOUR_EDITION_ID"
          },
          "revision": 1
        },
        "proposedAt": "2031-06-03T16:00:00Z",
        "displayTimeZone": "America/Phoenix"
      }
    }),
  },
);
const receipt = await response.json();
console.log(response.status, receipt);
```

```python tabs
import requests

# A new operationId for each new request; the same one to retry it.
response = requests.post(
    "https://api.growlocal.site/api/v1/profiles/YOUR_BUSINESS_ID/invocations",
    headers={"Authorization": "Bearer gl_YOUR_API_KEY"},
    json={
        "target": {
            "featureId": "YOUR_FEATURE_ID",
            "export": "proposeEdition",
            "contractRef": "social.edition.propose@1",
        },
        "operationId": "propose-time-1",
        "input": {
            "edition": {
                "ref": {
                    "businessProfileId": "YOUR_BUSINESS_ID",
                    "featureId": "juniper-cakes.data",
                    "collectionId": "juniper-cakes.editions",
                    "id": "YOUR_EDITION_ID",
                },
                "revision": 1,
            },
            "proposedAt": "2031-06-03T16:00:00Z",
            "displayTimeZone": "America/Phoenix",
        },
    },
    timeout=30,
)
print(response.status_code, response.json())
```

## Parameters

What goes in `input`:

| Name | Type | Required | Description |
|---|---|---|---|
| `edition` | object | Yes | The draft to suggest a time for, as you last read it. A post that already holds a placement is refused: move the placement instead. |
| `edition.ref` | object | Yes | The draft's row. |
| `edition.ref.businessProfileId` | string | Yes | The business that owns it. |
| `edition.ref.featureId` | string | Yes | The editions Data feature. |
| `edition.ref.collectionId` | string | Yes | The editions table. |
| `edition.ref.id` | string | Yes | The row id. |
| `edition.revision` | integer | Yes | The revision you read it at; refused if it changed since. |
| `proposedAt` | string or null | Yes | The moment to suggest, an instant with its offset, still ahead; `null` takes the suggestion back. |
| `displayTimeZone` | string | No | The time zone the time is shown in, such as `America/Denver`. Required with a time, refused with `null`. |

## Response

A call that worked answers `200` with an `applied` receipt; its `output` holds these fields, among others. `GET /catalog/social.edition.propose@1` answers the complete shape as JSON Schema.

| Name | Type | Description |
|---|---|---|
| `ref` | object | The draft's reference. |
| `revision` | integer | Its revision after this call; unchanged when the call changed nothing. |
| `account` | object | The account it is for. |
| `account.label` | string | The account's name. |
| `account.platform` | one of `facebook`, `instagram`, `linkedin`, `x`, `tiktok`, `youtube`, `pinterest`, `threads`, `bluesky` | Its platform. |
| `account.handle` | string | Its handle on the platform. |
| `account.connected` | boolean | Whether the account is still connected. |
| `account.textPost` | object | Whether this platform accepts a text-only post, independently of whether the account is connected. |
| `account.textPost.compatible` | boolean | True when the connector accepts a post with no media. |
| `account.textPost.reason` | string | The plain reason when text-only posting is incompatible; omitted otherwise. |
| `caption` | string | The caption. |
| `mediaRefs` | array of string | The media, in order. |
| `format` | one of `post`, `story`, `reel` | `post`, `story` or `reel`. |
| `notes` | string | The internal notes. |
| `source` | object or null | Where the content came from, or `null`. |
| `proposedAt` | string | The suggested time, an instant in UTC; absent after a suggestion is taken back. |
| `proposedZone` | string | The time zone the suggested time is shown in; present with `proposedAt`. |
| `createdAt` | string | When it was made. |
| `createdBy` | string or null | Who made it, or `null`. |
| `contentDigest` | string | The digest of the content an approval stands on; a suggested time is no part of it. |
| `approval` | object | The draft's approval, exactly as it was: suggesting a time never approves, invalidates or changes it. |
| `approval.state` | one of `none`, `approved`, `invalidated` | `none`, `approved` or `invalidated`; the same before and after. |
| `publication` | object or null | `null`: suggesting a time never places the draft. A draft that is already placed is refused. |
| `status` | one of `draft`, `approved`, `scheduled`, `suspended`, `held`, `dispatching`, `accepted`, `published`, `failed`, `uncertain` | Where the draft is. Suggesting a time never changes it: a draft stays `draft` and an approved draft stays `approved`. |
| `canEdit` | boolean | Whether you may edit it. |
| `canApprove` | boolean | Whether you may approve it. |
| `canSchedule` | boolean | Whether you may schedule it: only an approved draft can be scheduled, whatever time is suggested. |
| `canCancel` | boolean | Whether you may cancel it. |
| `canRemove` | boolean | Whether you may remove it. |
| `canPropose` | boolean | Whether you may suggest a time for it now: it holds no placement and this operation admits you. |

```json title="Response"
{
  "status": "applied",
  "operationId": "propose-time-1",
  "output": {
    "ref": {
      "businessProfileId": "YOUR_BUSINESS_ID",
      "featureId": "juniper-cakes.data",
      "collectionId": "juniper-cakes.editions",
      "id": "YOUR_EDITION_ID"
    },
    "revision": 1,
    "account": {
      "ref": {
        "businessProfileId": "YOUR_BUSINESS_ID",
        "featureId": "juniper-cakes.social",
        "collectionId": "juniper-cakes.accounts",
        "id": "YOUR_ACCOUNT_ID"
      },
      "revision": 1,
      "label": "Juniper Cakes",
      "platform": "x",
      "handle": "junipercakes",
      "connected": true,
      "textPost": {
        "compatible": true
      },
      "constraints": null
    },
    "caption": "This week: lemon drizzle, fresh from the oven.",
    "mediaRefs": [],
    "format": "post",
    "platformOptions": {},
    "notes": "",
    "source": null,
    "createdAt": "2026-11-13T09:30:00Z",
    "createdBy": null,
    "contentDigest": "0000000000000000000000000000000000000000000000000000000000000000",
    "approval": {
      "state": "none",
      "digest": null,
      "approvedAt": null,
      "approvedBy": null,
      "review": null
    },
    "publication": null,
    "status": "draft",
    "canEdit": true,
    "canApprove": true,
    "canSchedule": false,
    "canPropose": true,
    "canCancel": false,
    "canRemove": true,
    "proposedAt": "2031-06-03T16:00:00Z",
    "proposedZone": "America/Phoenix"
  }
}
```

## Errors

Besides the answers every request can get ([Errors](../errors.md)), its receipt can say:

| Status | HTTP | What it means |
|---|---|---|
| `pending` | 202 | Accepted and still running. Look it up with `GET /operations/{operationId}`. |
| `uncertain` | 202 | GrowLocal can't yet tell whether it took effect. Look it up before trying again. |
| `requirements` | 409 | Something must happen first; the receipt lists what. |
| `conflict` | 409 | The row changed since you read it, or this `operationId` was used with a different body. |
| `rejected` | 400, or 403 when it's a matter of access | Not done. `diagnostics` says why: each has a `code`, a `path` into what you sent and a `message`. |

The codes in `diagnostics` you're most likely to see:

| Code | Status | What it means |
|---|---|---|
| `SOCIAL.PROPOSAL_PAST` | `rejected` | The suggested moment is not ahead. |
| `SOCIAL.PROPOSAL_PLACED` | `rejected` | The post already has a placement; move that instead. |
| `SOCIAL.TIME_ZONE_REQUIRED` | `rejected` | A time was suggested without the zone it is shown in. |
| `SOCIAL.TIME_ZONE_UNEXPECTED` | `rejected` | A zone was sent with `null`. |
| `SOCIAL.TIME_ZONE_UNKNOWN` | `rejected` | The zone is not a real IANA time zone. |
| `SOCIAL.REVISION_CONFLICT` | `conflict` | The draft changed since `expectedRevision` was read. |
