Sending

Send a document from a template

post/documents

Creates and sends a real document from a template. recipients must fill every role on the template exactly once: Send from a template walks through it. Templates with in-person signers are refused. Each document counts toward the monthly allowance.

Needs a key with documents:send. Requires an Idempotency-Key header.

Request body

template_idUUIDRequired
The template to send.
titlestring
The document title. Defaults to the template's title.
1 to 120 characters
external_idstring
Your own reference for this document, in printable ASCII. It is not required to be unique.
Up to 255 characters
recipientsarray of objectsRequired
One entry for every template role, each role exactly once.
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}.
- deliverystring
  email sends the invitation and reminders. link sends neither and gives you signing_url to share yourself. It is not a sandbox: the document is real and legally binding.
  One of email, link
  Default email
ccarray of objects
Extra people who get a copy once the document is complete.
Up to 5 items
2 child fields
- namestring
  The person's name.
  Up to 200 characters
- emailemailRequired
  The person's email address.
prefilled_valuesobject
Values for the template's prefilled fields, keyed by field label.
messagestring
A personal note in the invitation.
Up to 2000 characters
automatic_remindersboolean
Send automatic reminders until the document is signed.
Default false

Example request

curl -X POST "https://www.inkly.so/api/v1/documents" \
  -H "Authorization: Bearer $INKLY_API_KEY" \
  -H "Idempotency-Key: crm-8841-send-1" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "a2d94c10-6e7b-4f38-8c15-1f3e9b7d6c02",
    "title": "Consulting agreement",
    "external_id": "crm-8841",
    "recipients": [
      {
        "role_id": "c81e7f42-0b39-4d6a-a7c4-92e15d3f8b76",
        "name": "Alex Morgan",
        "email": "alex@example.com",
        "delivery": "email"
      }
    ],
    "cc": [
      {
        "name": "Sam Lee",
        "email": "sam@example.com"
      }
    ],
    "prefilled_values": {
      "Project name": "Website redesign"
    },
    "message": "Please sign by Friday."
  }'

Example response, 201

{
  "document": {
    "id": "3f1c2a7e-8b4d-4e21-9a6f-5d0c7e1b2a34",
    "title": "Consulting agreement",
    "status": "sent",
    "external_id": "crm-8841",
    "template_id": "a2d94c10-6e7b-4f38-8c15-1f3e9b7d6c02",
    "created_at": "2026-11-02T15:04:05.123Z"
  },
  "recipients": [
    {
      "id": "5b7e9d13-2c84-4f06-b1a9-6d40e8c2f715",
      "role_id": "c81e7f42-0b39-4d6a-a7c4-92e15d3f8b76",
      "role": "signer",
      "name": "Alex Morgan",
      "email": "alex@example.com",
      "delivery": "email",
      "status": "pending",
      "signing_url": null
    },
    {
      "id": "e47a0c96-7d21-4b58-9f3e-08b6c1d5a243",
      "role_id": null,
      "role": "cc",
      "name": "Sam Lee",
      "email": "sam@example.com",
      "delivery": "email",
      "status": "pending",
      "signing_url": null
    }
  ]
}

Response fields

documentobjectRequired
6 child fields
- idUUIDRequired
- titlestringRequired
- statusstringRequired
  One of draft, sent, completed, declined, voided
- external_idstring or nullRequired
- template_idUUID or nullRequired
- created_attimestampRequired
recipientsarray of objectsRequired
8 child fields
- idUUIDRequired
- rolestringRequired
  One of signer, cc
- namestring or nullRequired
- emailstring or nullRequired
- deliverystringRequired
  How this person hears from Inkly. Always email for CC recipients.
  One of email, link
- statusstringRequired
  One of pending, viewed, signed, declined
- signing_urlURL or nullRequired
  Set only when delivery is link and it is this signer's turn. With sequential signing, later signers get null: when GET /documents/{id} shows is_signing_turn is true, call POST /documents/{id}/recipients/{recipient_id}/signing-link. Treat it like a password: anyone holding it can sign.
- role_idUUID or nullRequired
  The template role. null for people added through cc.

Errors specific to this endpoint

dropdown_options_invalid400A dropdown's options are missing, duplicated, or not valid.
idempotency_key_required400Provide an Idempotency-Key header.
invalid_request400The request is invalid.
recipient_invalid_email400A recipient's email address is not valid.
unknown_field400This field is not supported.
unknown_prefilled_field400This prefilled field is not in the template.
sending_paused403Sending is paused for this workspace. Contact support.
template_not_found404Template not found.
document_changed409The document or template changed while it was being sent. Retry with a new Idempotency-Key.
idempotency_key_reused409This idempotency key was used with a different request.
idempotency_request_in_progress409A request with this idempotency key is still running.
body_too_large413The JSON body must be at most 64 KB.
cc_recipient_cannot_have_fields422A CC recipient cannot be assigned fields.
cc_recipient_duplicate_email422The same CC email address appears more than once.
cc_recipient_limit_exceeded422A document can have at most 5 CC recipients.
document_has_no_fields422The document has no fields.
document_has_no_recipients422The document has no recipients.
document_has_no_signers422The document has no signers.
in_person_not_supported422Templates with in-person signers cannot be sent through the API.
prefilled_value_missing422A required prefilled field has no value.
recipient_limit_exceeded422A document can have at most 25 recipients.
selection_group_incomplete422A checkbox or radio group on the template is incomplete.
signer_has_no_fields422A signer has no field to fill in.
monthly_allowance_exceeded429The monthly API document allowance has been reached.
temporarily_unavailable503The service is temporarily unavailable. Try again.

Every endpoint can also return the common errors.