# signing.envelopes.updateDraft

Edit a draft envelope with expectedRevision, including uploaded-document field positions, and its job (jobRoleId with jobRoleVersion, or both null) and engagement (the structured pay and dates, or null). Changing document content, the job or the pay clears the prepared PDF and its field positions; field placement alone keeps the PDF.

`POST /api/v1/accounting/signing.envelopes.updateDraft`

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

MCP tool: `accounting_signing_envelopes_update_draft`

## Fields

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `id` | string (ID) | Yes | The record's ID. |
| `expectedRevision` | integer | Yes | 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. |
| `title` | string |  | A short title. 1–200 characters. |
| `message` | string |  | at most 4000 characters. |
| `templateId` | string (ID) or null |  |  |
| `fileId` | string (ID) |  | The ID of the related record. |
| `subjectType` | enum or null |  | The kind of record this is about, such as entry, invoice or mail. One of: `contractor`, `party`, `invoice`. |
| `subjectId` | string or null |  | The ID of the record this is about. |
| `mergeValues` | map |  |  |
| `signingOrder` | enum |  | One of: `sequential`, `parallel`. |
| `recipients` | array of objects |  | at most 20 items. |
| `recipients[].kind` | enum | Yes | Which kind of record or job this is. One of: `signer`, `cc`. |
| `recipients[].signerRole` | string or null |  |  |
| `recipients[].name` | string | Yes | A display name. 1–200 characters. |
| `recipients[].email` | string (email) | Yes | An email address. at most 320 characters. |
| `recipients[].title` | string or null |  | A short title. |
| `recipients[].company` | string or null |  |  |
| `recipients[].order` | integer |  | 1 to 20. |
| `recipients[].userId` | string or null |  | The ID of a person in your company. |
| `fields` | array of objects |  | at most 500 items. |
| `fields[].role` | string | Yes | A person's access level in the company. Matches ^[a-z][a-z0-9_]{0,40}$. |
| `fields[].kind` | enum | Yes | Which kind of record or job this is. One of: `signature`, `initials`, `name`, `title`, `date`, `email`. |
| `fields[].page` | integer | Yes | 0 to 499. |
| `fields[].x` | number | Yes | 0 to 5000. |
| `fields[].y` | number | Yes | 0 to 5000. |
| `fields[].width` | number | Yes | at most 5000; greater than 0. |
| `fields[].height` | number | Yes | at most 5000; greater than 0. |
| `expiresAt` | string (date-time) |  | When this stops working, as an ISO 8601 date and time. |
| `expiresInDays` | integer |  | 1 to 365. |
| `reminderIntervalDays` | integer |  | 0 to 30. |
| `allowChanges` | boolean |  |  |
| `jobRoleId` | string (ID) or null |  |  |
| `jobRoleVersion` | integer or null |  |  |
| `engagement` | object or null |  |  |
| `engagement.rate` | object | Yes | No other fields. |
| `engagement.rate.amountMinor` | string | Yes | An amount in cents (the currency's smallest unit), written as a whole-number string such as "1250" for $12.50. Matches ^[1-9]\d{0,14}$. |
| `engagement.rate.currency` | string | Yes | Three-letter currency code, such as CAD or USD. |
| `engagement.rate.unit` | enum | Yes | One of: `hour`, `day`, `week`, `month`, `year`, `fixed`. |
| `engagement.basis` | enum | Yes | One of: `job`, `one_off`. |
| `engagement.note` | string or null |  | A short note, kept with the record. |
| `engagement.startDate` | string (date) or null |  |  |
| `engagement.endDate` | string (date) or null |  |  |
| `engagement.noticeDays` | integer or null |  |  |
| `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. |

## Example request

```bash
curl https://app.getoatmilk.com/api/v1/accounting/signing.envelopes.updateDraft \
  -H "Authorization: Bearer $OATMILK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "expectedRevision": 3
}'
```

Reference page: https://app.getoatmilk.com/docs/api/signing.envelopes.updateDraft