Save a form

PUT/api/v1/workspaces/{slug}/certificates/{id}/forms/{kind}

Save a certificate's request, unlock, or correction form definition

Saving publishes a new immutable version whenever the title, description, or fields change. Every response records the version it answered, so editing a live form never makes an existing response unreadable or re-validates it against the new definition. current_version in the response is the version new submissions are pinned to.

Omitted fields keep their current value.

Field types

text, textarea, phone_number, single_select, multi_select, star_rating, scale, checkbox, url, date, image, attachment.

single_select and multi_select require at least one options entry. star_rating defaults to 1–5 and scale to 0–10; both accept min and max between 0 and 100.

A checkbox stores a boolean answer and defaults to unticked. Use an optional, explicitly labelled checkbox when asking for permission; submitting a form never implies consent.

Authorization

Scopecertificates:write

Authorization: Bearer vc_...

Requires certificates:write (or full access) and an active Pro seat.

Path parameters

slug*string

Workspace slug

Example: acme

id*string

Certificate id

Example: 550e8400-e29b-41d4-a716-446655440000

kind*string

request, unlock, or correction

Example: unlock

Body parameters

enabled?boolean

Turn the form on or off. Enabling an unlock form invites every pending recipient; disabling it revokes outstanding links.

Example: true

title?string

Form title shown to the recipient

Example: Event Feedback

description?string

Short explanation shown above the fields

Example: Tell us how it went.

fields?object[]

Ordered field definitions (key, label, type, required, caption, options, min, max)

Example: []