API ReferenceForms

Update Form

Partial update. Only keys present in the body are applied. Archived forms (non-null archived_at) cannot be updated — restore the form by setting archived_at: null in a PATCH first.

Authentication

PINNACLE-API-KEYstring
API Key authentication via header

Path parameters

idstringRequired

The unique identifier of the form you want to update.

This identifier is a string that always begins with the prefix form_, for example: form_Oy2n7iUoi9CJwUU6.

Request

This endpoint expects an object.
namestring or nullOptional

Replace the form’s title. Pass null to clear.

descriptionstring or nullOptional

Replace the form’s description. Pass null to clear.

fieldslist of objectsOptional

Replace the full set of fields on the form. Partial field updates aren’t supported — send the complete new list.

can_updatebooleanOptional

Toggle whether the recipient can re-edit their submission.

expires_atstring or nullOptionalformat: "date-time"
Set or clear the form's expiration timestamp.
theme_overrideobject or nullOptional

Replace the per-form theme override. Pass null to revert to team defaults.

archived_atstring or nullOptionalformat: "date-time"

Set to an ISO timestamp to archive the form (soft-delete), or null to restore an archived form.

Response

Updated form.
idstring

Form id (starts with form_).

urlstring

Public shareable URL of the form (https://forms.pinnacle.sh/{form_id}).

namestring or null

Human-readable name for the form. Rendered as the form’s title.

descriptionstring or null
Longer description rendered below the title.
fieldslist of objects
Ordered list of fields the recipient fills out.
can_updateboolean

When true, the recipient can reopen the submission URL and edit their answers. When false, the URL becomes read-only after the first submit.

expires_atstring or nullformat: "date-time"
After this timestamp the form stops accepting submissions. Null means no expiration.
theme_overrideobject or null

Per-form theme tweaks layered on top of your team’s default theme. Null means the team defaults are used as-is.

submission_countinteger

Count of distinct completed submissions for this form. Does not increment on edits to an existing can_update=true submission.

last_submitted_atstring or nullformat: "date-time"

Timestamp of the most recent submission event. Updated on each new submit and on each edit of a can_update=true submission.

archived_atstring or nullformat: "date-time"

When set, the form is archived (soft-deleted) and cannot accept new submissions or be updated. Restore by PATCHing archived_at back to null.

created_atstringformat: "date-time"
ISO 8601 timestamp of when the form was created.
updated_atstringformat: "date-time"
ISO 8601 timestamp of the most recent form mutation.

Errors

400
Bad Request Error
401
Unauthorized Error
404
Not Found Error
500
Internal Server Error