---
title: Save a form
description: Save a certificate's request, unlock, or correction form definition
method: PUT
path: /api/v1/workspaces/{slug}/certificates/{id}/forms/{kind}
group: Forms
scopes: certificates:write
---

# Save a form

# Save a form

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

```http
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: `[]`.

## Request

```bash
curl -X PUT "https://api.verifycate.com/api/v1/workspaces/acme/certificates/550e8400-e29b-41d4-a716-446655440000/forms/unlock" \
  -H "Authorization: Bearer vc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Event Feedback",
    "fields": [
      { "key": "rating", "label": "Overall rating", "type": "star_rating", "required": true }
    ]
  }'
```

## Response

### 200

Returns the saved form definition, with `current_version` bumped when the
content changed.