API ReferenceForms

Create Form

Create a hosted form without sending it.

Returns the form object including its public URL — https://forms.pinnacle.sh/{form_id}.

To also deliver the URL to a recipient over SMS or RCS in a single call, use POST /forms/send.

Authentication

PINNACLE-API-KEYstring
API Key authentication via header

Request

This endpoint expects an object.
fieldslist of objectsRequired
Ordered list of fields the recipient will fill out. At least one field is required.
can_updatebooleanOptionalDefaults to false

If true, the recipient can reopen the submission URL and edit their answers. When false (default), the submission URL becomes read-only (Already submitted) after the first submit.

descriptionstringOptional
Longer description rendered below the title.
expires_atstringOptionalformat: "date-time"
After this timestamp the form stops accepting submissions. Omit for no expiration.
namestringOptional

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

theme_overrideobject or nullOptional

Per-form theme tweaks layered on top of your team’s default theme. Omit or set to null to use team defaults.

Response

Form created.
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
500
Internal Server Error