> For the complete documentation index, see [llms.txt](https://api-reference.usecommune.dev/llms.txt)

# Update a signup form

> PATCH /forms/{form}
> 
> Changes a signup form. Needs `audience: write`, and is a write.
> 
> Only what the body names changes, inside `style`, `after_signup`,
> `after_confirm` and `confirmation_email` too: `{"style": {"corners":
> "pill"}}` moves the corners and nothing else, and
> `{"confirmation_email": {"subject": null}}` hands the subject back to
> the newsletter's default. The form as it stands afterwards is checked
> whole, so a change that is fine on its own and wrong in combination is
> refused: setting `after_signup.action` to `redirect` on a form with no
> `after_signup.url` answers `400`.
> 
> **Every site the form is on changes with it.** The script embed reads
> the form's settings when it loads, so a new heading or colour shows up
> without anybody pasting new code. The plain HTML embed has its own
> markup and takes no style from here; its tags, its confirmation email
> and its automations still follow the form.
> 
> A change to `tag_ids` applies to the people who sign up from now on.
> Nobody who already joined gains or loses a tag through it.
> 
> Publishes no event.



## Servers
- Production. There is no separate sandbox host.
: https://api.usecommune.com (Production. There is no separate sandbox host.
)


## Authentication methods
- Api key
- Oauth2


## Parameters
### Headers

- **Idempotency-Key** (string)
  A value of your choosing naming the change this request is making.

  Send the same value again to retry the same request. Commune replays
  the answer the first attempt gave instead of making the change twice,
  and marks the replay with an `Idempotent-Replay: true` response header.
  Send a different value for a different change: a key reused for a
  request that differs in any way answers `409`, because replaying an
  answer to a question you did not ask is a wrong answer you could not
  detect.

  A UUID per change is the usual choice. Remembered for 24 hours, per
  credential, so two credentials choosing the same value never see each
  other's answers.

  Required, not optional.

- **Commune-Version** (string)
  The contract version this request is written against. Every version
  published so far is a release date (`YYYY-MM-DD`), which is why the
  examples look like one, but the value is an opaque identifier: match it
  against the versions this API publishes rather than parsing it, because
  a future one may not be only a date. An unknown value answers `400`
  with `invalid_version`.

  Omitting the header pins the request to the version that was current
  when the API key was issued, so an integration keeps working when a
  newer version ships.


### Path parameters

- **form** (string)
  The form's `id`, or its `public_id`: the short id in its embed code
  and its link, `k7x2p9` in `https://usecommune.com/f/k7x2p9`.



### Body: application/json (object)

- **name** (string)

- **heading** (string)

- **description** (string)

- **button_label** (string)

- **email_placeholder** (string)

- **name_field** (object)
  Any of a form's name field settings. Only what is named changes.

- **consent** (object)
  Any of a form's consent settings. Only what is named changes.

- **style** (object)
  Any of a form's style settings. Only what is named changes.

- **tag_ids** (array[string(uuid)])
  Replaces the form's tags. Applies to people who sign up from now
  on; nobody who already joined gains or loses one.

- **after_signup** (object)
  Any of what happens right after a signup. Only what is named changes.

- **after_confirm** (object)
  Any of where a confirmed reader goes. Only what is named changes.

- **confirmation_email** (object)
  Any of the confirmation email's settings. Only what is named changes,
  and null hands a setting back to the level below it.



## Responses
### 200
The form, as it now stands.

#### Body: application/json (object)
- **object** (string)
  Always `form`.

- **id** (string(uuid))
  Stable identifier.

- **public_id** (string)
  The short id in the form's link and embed code, `k7x2p9` in
  `https://usecommune.com/f/k7x2p9`. Accepted wherever `{form}` is,
  and fixed for the life of the form, because it is in every copy of
  the code already pasted.

- **newsletter** (object)
  The newsletter whose list the form signs people up to. A `Ref`
  unless `newsletter` is named in `?expand=`.

- **name** (string)
  What the form is called in Commune: in the list of forms, in
  automations and in Growth. Readers never see it; they see
  `heading`.

- **heading** (string)
  The heading above the form. May be empty.

- **description** (string)
  A line under the heading. May be empty.

- **button_label** (string)
  The words on the button.

- **email_placeholder** (string)
  The placeholder in the email field. May be empty.

- **name_field** (object)
  Whether the form asks for a name as well as the address, and how the
  field reads. Off on a new form.

  A signup's name is kept with the subscription, only ever filling an
  empty one, and is written when the reader confirms. It is what the
  `subscriber.display_name` merge tag says for somebody without a
  Commune account; the account's own name wins for somebody with one.
  Not to be confused with the form's own `name`, which readers never
  see.

- **consent** (object)
  Whether the form draws a consent checkbox, and what it says. Off on a
  new form. When it is on it is required: a signup without the box
  ticked answers `422` with `code: consent_required` and stores nothing.

  Every signup that ticks it leaves a record on the subscriber
  (`Subscriber.consents`): these words as they were shown, the privacy
  policy link, the page, when and from which IP address the box was
  ticked, and when and from which IP address the reader confirmed by
  email.

- **style** (object)
  How the script embed draws the form. Text, fonts and the page behind
  it come from the creator's own site; this is the shape and the one
  brand colour. The plain HTML embed has no styles and ignores it.

- **tag_ids** (array[string(uuid)])
  The newsletter's tags this form gives the people who join through
  it: on confirming for somebody new, straight away for somebody
  already on the list. A tag deleted since is skipped when the form
  applies them.

- **after_signup** (object)
  What somebody sees right after submitting the form, before they have
  confirmed anything.

- **after_confirm** (object)
  Where somebody goes after clicking the link in the confirmation email.

- **confirmation_email** (object)
  The email a signup gets asking them to confirm, in the creator's words.
  Every setting is null where it falls back, one setting at a time: a
  form's own value, else the newsletter's default
  (`GET /newsletters/{newsletter}/form-defaults`), else Commune's email,
  which is "Confirm your subscription to" and the newsletter's name, a
  line naming the newsletter and the site the form was on, a violet
  `Confirm subscription` button on a white card, and "Didn't sign up?
  Ignore this email and you won't hear from us again." under it.

  **The confirm link is always there.** It is the button, between `body`
  and `footnote`, and no setting here removes or moves it: the creator
  writes the words around it.

- **embed** (object)
  The three ways to put the form on a site, ready to paste. For a form
  of your own instead, see
  [Build your own signup form](https://usecommune.dev/guides/forms).

- **subscriber_count** (integer)
  How many people joined through this form, counting each person once
  however many times they signed up. Includes people who were already
  on the list when they did.

- **subscribers_this_week** (integer)
  Of those, how many first joined in the last seven days.

- **created_at** (string(date-time))
  When the form was created.

- **updated_at** (string(date-time))
  When the form's settings last changed.


### 400
The request was malformed, and the same request will fail the same way
until it is changed. `param` names the parameter or header at fault
when there is exactly one, and `allowed_values` lists what it accepts
when that is a finite set. The code is `bad_request` for every case
below except the last.

* **A query parameter**: one the operation does not have, a value
  outside its set, range or format (an unparseable cursor, an unknown
  `expand` path or `fields` name, an identifier that is not a UUID),
  or a required one left out, such as `q` on a search or `newsletter`
  when the credential reaches more than one.
* **The request body**: not JSON, not the shape the operation reads,
  a property it does not write, or a value of the wrong type, length
  or format. `param` is absent here, since the body is not a
  parameter, and the message names the property.
* **The `Idempotency-Key` header**, on an operation that changes
  something: missing, or a value this API will not store.
* **An unrecognised `Commune-Version`**, which answers with its own
  code, `invalid_version`, because it is never fixed by changing the
  body.


#### Body: application/json (object)
- **error** (object)


### 401
No credential was presented, or it is malformed, unknown, revoked or
expired, or it is an access token minted for a different audience.

Every one of these answers identically, down to the wording and the
headers, so a refusal never confirms that a string was once real.

#### Headers

- **WWW-Authenticate** (string)
  The authentication scheme this API accepts, and where to find out
  how to get a credential for it. Always
  `Bearer realm="Commune API", resource_metadata="https://api.usecommune.com/.well-known/oauth-protected-resource"`.

  `resource_metadata` is the RFC 9728 pointer to this API's protected
  resource metadata, which names the authorization server an OAuth
  client should send its user to. A client holding an API key can
  ignore it. The header carries no `error` parameter, not even
  `error="invalid_token"`, because it describes what this API accepts
  rather than what was wrong with the credential sent, and the
  reasons above are deliberately indistinguishable.

  There is no second scheme and no query-parameter fallback, because
  a credential that can travel in a URL ends up in access logs and
  referer headers.


#### Body: application/json (object)
- **error** (object)


### 402
The credential is allowed to do this but the newsletter's plan does not
include it.

Two surfaces can answer it: **insights**, the engagement and metrics
operations, which are the only reads Commune reserves the right to
meter, and **writing**, every operation that changes something.

Every other read stays free on every plan, so a credential refused at
one of these can still read everything else. The body names the plan the
newsletter is on and the plans that would work.

One refusal is a feature of the paid plan rather than a charge for API
access, and it answers whatever is metered: a newsletter whose plan does
not include it may have **one automation active at a time**, so
`POST /automations/{automation}/activate` is refused while another is
running. That one is also the only `402` a client can clear on its own,
by pausing the automation that is running.

**This status is predictable and should not be how you discover it.**
`GET /newsletters/{newsletter}/entitlements` answers the same question
in advance, carrying the same plan list this puts in `allowed_values`
and the same sentence it puts in `message`. Read it once at the start
of a run rather than finding out in the middle of one.


#### Body: application/json (object)
- **error** (object)


### 403
The credential is valid but is not allowed to do this. Two codes answer
with this status, and `error.code` says which.

**`insufficient_scope`: it does not hold the permission.** The
operation needs, say, `audience: read` on the newsletter addressed, and
this credential holds less than that there. `allowed_values` carries
the permission that was needed, and the message says what the
credential does hold on that newsletter, because a credential granted
the wrong family and a credential belonging to somebody whose standing
on the team has narrowed look identical without it. The answer can
differ per newsletter: the same credential may be allowed here and
refused on the next one it reaches.

The same code answers an operation that needs the **account
permission** from a credential that does not carry it. That permission
is about the person a credential belongs to rather than about any
newsletter, so nothing granted on a newsletter adds up to it. It is
granted on the credential itself, when a key is minted or when an
authorization asks for `account:read`.

And it answers a parameter the credential may send, but not with the
value it sent: a filter a credential holding only `read` permissions
may not use, or an `expand` path whose rows need a permission the
operation does not. `param` names the parameter, and `allowed_values`
carries what this credential may send instead, or is absent when it may
send nothing there at all.

**`forbidden`: it may not act here at all.** Either the credential does
not reach the newsletter addressed, because it was never granted it or
because the person it belongs to can no longer act on it, or it reaches
no newsletter at all; `param` is `newsletter`, and `GET /newsletters`
lists the ones it does reach. Or, on `DELETE /api-keys/{key}`, the
credential named belongs to somebody else. Neither carries
`allowed_values`, because there is no value to send instead.


#### Body: application/json (object)
- **error** (object)


### 404
No such resource, or the key is not allowed to know that it exists.
Commune answers `404` rather than `403` where distinguishing the two
would leak the existence of private content.


#### Body: application/json (object)
- **error** (object)


### 409
The request collided with something. On a write this is always the
`Idempotency-Key`, in one of two ways, and the message says which.

Either the key was already used for a **different** request, which is
refused rather than answered with the earlier request's result. Or an
earlier request using the same key has not finished, or never reported
an outcome, in which case this one was not run and the key becomes
usable again shortly.

Nothing was changed by a request that answers this.

#### Headers

- **Retry-After** (integer)
  Seconds to wait before retrying, on the second case only.


#### Body: application/json (object)
- **error** (object)


### 422
The request is well formed and every value in it is legal, and the
state of what it addresses refuses it anyway. The message says what
about that state is in the way.


#### Body: application/json (object)
- **error** (object)


### 429
Too many requests. Back off and retry after the interval named by the
`Retry-After` response header.

One of the budgets in `RateLimit-Policy` ran out, and the
`RateLimit-*` headers on this response say which and when it resets.

#### Headers

- **Retry-After** (integer)
  Seconds to wait before retrying.


#### Body: application/json (object)
- **error** (object)


### 500
Something failed inside Commune. The request may be retried.

#### Body: application/json (object)
- **error** (object)



[Powered by Bump.sh](https://bump.sh)
