# contractorOps.forms.save

Create or update a custom hours form with name, ordered fields (key, label, type text/textarea/number/select/multiselect/date/checkbox/url, required, options, help), optional isDefault or archived, expectedRevision for updates, and idempotencyKey.

`POST /api/v1/accounting/contractorOps.forms.save`

Permissions: `accounting:read`, `accounting:write` · Roles: admin, finance · Idempotency key required · Send `expectedRevision`

MCP tool: `accounting_contractor_ops_forms_save`

## Fields

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `id` | string (ID) |  | The record's ID. |
| `expectedRevision` | integer |  | The record's current revision, from the last time you read it. If someone changed the record since, the request is refused with a conflict so you can reload and check before trying again. at most 9007199254740991; greater than 0. |
| `idempotencyKey` | string | Yes | Any unique text you generate once per intended change, so a retried request only happens once. Send it as the Idempotency-Key header instead if you prefer; if you send both they must match. 8–200 characters. |
| `name` | string | Yes | A display name. 1–120 characters. |
| `description` | string |  | A short description. at most 1000 characters. Default `""`. |
| `fields` | array of objects | Yes | at most 40 items. |
| `fields[].key` | string | Yes | Matches ^[a-z][a-zA-Z0-9_]{0,39}$. |
| `fields[].label` | string | Yes | 1–120 characters. |
| `fields[].type` | enum | Yes | One of: `text`, `textarea`, `number`, `select`, `multiselect`, `date`, `checkbox`, `url`. |
| `fields[].required` | boolean |  | Default `false`. |
| `fields[].options` | array of strings |  | at most 50 items; each 1–100 characters. |
| `fields[].help` | string |  | at most 300 characters. |
| `isDefault` | boolean |  |  |
| `archived` | boolean |  | Whether the record is archived. |

## Example request

```bash
curl https://app.getoatmilk.com/api/v1/accounting/contractorOps.forms.save \
  -H "Authorization: Bearer $OATMILK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "name": "Synthetic Ventures Inc.",
  "fields": [
    {
      "key": "key",
      "label": "example",
      "type": "text"
    }
  ]
}'
```

Reference page: https://app.getoatmilk.com/docs/api/contractorOps.forms.save