# signing.envelopes.createDraft

Create a draft envelope from a template (templateId or templateKey) or an uploaded file (fileId) with title, message, recipients (signer or cc, signerRole, order, userId for a company signer who signs in Oatmilk), mergeValues, signingOrder (parallel or sequential), deadline, and reminder interval. A template that states pay (like the contractor agreement) is made from a job: jobRoleId and jobRoleVersion (a version from contractorOps.roles.versions), and engagement: the pay as rate {amountMinor (minor units, as a string of digits), currency, unit: hour, day, week, month, year or fixed}, basis job (the version's pay: its currency and unit, within its band) or one_off (a rate for this agreement only, with an optional note), and startDate, endDate and noticeDays. The pay, its currency, the role and the dates are then filled in from these and can't be set through mergeValues. Nothing is sent.

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

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

MCP tool: `accounting_signing_envelopes_create_draft`

## Fields

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `title` | string | Yes | A short title. 1–200 characters. |
| `message` | string |  | at most 4000 characters. Default `""`. |
| `templateId` | string (ID) |  | The ID of the related record. |
| `templateKey` | string |  | Matches ^[a-z][a-z0-9-]{1,60}$. |
| `fileId` | string (ID) |  | The ID of the related record. |
| `subjectType` | enum |  | The kind of record this is about, such as entry, invoice or mail. One of: `contractor`, `party`, `invoice`. |
| `subjectId` | string |  | The ID of the record this is about. 1–200 characters. |
| `mergeValues` | map |  | Default `{}`. |
| `signingOrder` | enum |  | One of: `sequential`, `parallel`. Default `"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. Default `[]`. |
| `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. Default `3`. |
| `allowChanges` | boolean |  |  |
| `jobRoleId` | string (ID) |  | The ID of the related record. |
| `jobRoleVersion` | integer |  | 1 to 100000. |
| `engagement` | object |  | No other fields. |
| `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.createDraft \
  -H "Authorization: Bearer $OATMILK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "title": "Synthetic services agreement"
}'
```

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