Sending

Prepare a draft from a template

post/drafts

Prepares an editable draft from a template without sending invitations or charging the monthly allowance. Fill each template role exactly once using roles; prefilled uses the labels from GET /templates/{id}. Reuse request_id on retries to get the existing document without changing human edits. Draft attempts are limited to 60 per workspace per hour, including retries. Do not send Idempotency-Key.

Needs a key with documents:send.

Request body

template_idUUIDRequired
The template to send.
titlestring
The document title. Defaults to the template's title.
1 to 120 characters
rolesarray of objectsRequired
1 to 25 items
4 child fields
- namestring
  The person's name.
  Up to 200 characters
- emailemailRequired
  The person's email address.
- role_idUUIDRequired
  The template role this person fills. Get it from GET /templates/{id}.
- delivery"email"
  Default email
prefilledobject
Values for the template's prefilled fields, keyed by field label.
messagestring
A personal note in the invitation.
Up to 2000 characters
request_idUUID
Reuse this UUID when retrying. A replay returns the existing document without changing edits.

curl -X POST "https://www.inkly.so/api/v1/drafts" \
  -H "Authorization: Bearer $INKLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "a2d94c10-6e7b-4f38-8c15-1f3e9b7d6c02",
    "roles": [
      {
        "role_id": "c81e7f42-0b39-4d6a-a7c4-92e15d3f8b76",
        "name": "Alex Morgan",
        "email": "alex@example.com"
      }
    ],
    "prefilled": {
      "Project name": "Website redesign"
    },
    "request_id": "7d6b1f0a-3c4e-4a55-9e21-0b8f6c2d1a90"
  }'

Example response, 201

{
  "document": {
    "id": "3f1c2a7e-8b4d-4e21-9a6f-5d0c7e1b2a34",
    "status": "draft",
    "app_url": "https://www.inkly.so/documents/3f1c2a7e-8b4d-4e21-9a6f-5d0c7e1b2a34/edit"
  }
}

Response fields

documentobjectRequired
3 child fields
- idUUIDRequired
- status"draft"Required
- app_urlURLRequired
  Open the draft in Inkly to review and send it. No invitations have been sent.

Errors specific to this endpoint

invalid_request400The request is invalid.
unknown_field400This field is not supported.
unknown_prefilled_field400This prefilled field is not in the template.
template_not_found404Template not found.
body_too_large413The JSON body must be at most 64 KB.
in_person_not_supported422Templates with in-person signers cannot be sent through the API.
prefilled_value_missing422A required prefilled field has no value.
selection_group_incomplete422A checkbox or radio group on the template is incomplete.
temporarily_unavailable503The service is temporarily unavailable. Try again.

Every endpoint can also return the common errors.