`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:readaccounting:write

Who can call it

admin, finance

Retries

Idempotency key required

MCP

accounting_signing_envelopes_create_draft

Fields

titlestringRequired
A short title.
1–200 characters
messagestring
at most 4000 characters · Default ""
templateIdstring (ID)
The ID of the related record.
templateKeystring
Matches ^[a-z][a-z0-9-]{1,60}$
fileIdstring (ID)
The ID of the related record.
subjectTypeenum
The kind of record this is about, such as entry, invoice or mail.
contractorpartyinvoice
subjectIdstring
The ID of the record this is about.
1–200 characters
mergeValuesmap
Default {}
signingOrderenum
sequentialparallel
Default "parallel"
recipientsarray of objects
at most 20 items
fieldsarray of objects
at most 500 items · Default []
expiresAtstring (date-time)
When this stops working, as an ISO 8601 date and time.
expiresInDaysinteger
1 to 365
reminderIntervalDaysinteger
0 to 30 · Default 3
allowChangesboolean
jobRoleIdstring (ID)
The ID of the related record.
jobRoleVersioninteger
1 to 100000
engagementobject
No other fields
idempotencyKeystringRequired
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

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"
}'

const response = await fetch("https://app.getoatmilk.com/api/v1/accounting/signing.envelopes.createDraft", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OATMILK_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    "title": "Synthetic services agreement"
  }),
});
const { data, error } = await response.json();
if (!response.ok) throw new Error(`${error.code}: ${error.message}`);
console.log(data);

import os
import uuid

import requests

response = requests.post(
    "https://app.getoatmilk.com/api/v1/accounting/signing.envelopes.createDraft",
    headers={
        "Authorization": f"Bearer {os.environ['OATMILK_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "title": "Synthetic services agreement",
    },
    timeout=30,
)
payload = response.json()
if not response.ok:
    raise RuntimeError(f"{payload['error']['code']}: {payload['error']['message']}")
print(payload["data"])

Response

{
  "data": { … }
}

Try it

Checks your input with this action’s real schema and answers like the API, with synthetic data. No key needed, and nothing changes.

Input

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

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"
}'

const response = await fetch("https://app.getoatmilk.com/api/v1/accounting/signing.envelopes.createDraft", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OATMILK_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    "title": "Synthetic services agreement"
  }),
});
const { data, error } = await response.json();
if (!response.ok) throw new Error(`${error.code}: ${error.message}`);
console.log(data);

import os
import uuid

import requests

response = requests.post(
    "https://app.getoatmilk.com/api/v1/accounting/signing.envelopes.createDraft",
    headers={
        "Authorization": f"Bearer {os.environ['OATMILK_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "title": "Synthetic services agreement",
    },
    timeout=30,
)
payload = response.json()
if not response.ok:
    raise RuntimeError(f"{payload['error']['code']}: {payload['error']['message']}")
print(payload["data"])

Fields

Fields inside recipients

Fields inside fields

Fields inside engagement

Example

Try it