Sending

Send a document from an uploaded PDF

post/documents/from-upload

Creates and sends a real document from a PDF you uploaded. Place each field by page and position, as fractions of the page measured from its top-left corner: Send a PDF shows how to work them out. Or set use_markers to true and write fields into the PDF as text such as {{signature;signer=client}}. Field markers has the syntax. Prefilled fields must be text. Each document counts toward the monthly allowance.

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

Request body

upload_idUUIDRequired
From POST /uploads, after the PDF has been uploaded.
titlestring
The document title. Defaults to the file name.
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
signing_orderstring
sequential invites signers one at a time, in the order listed.
One of parallel, sequential
Default parallel
messagestring
A personal note in the invitation.
Up to 2000 characters
automatic_remindersboolean
Send automatic reminders until the document is signed.
Default false
recipientsarray of one of the types belowRequired
Up to 25 people, at most 5 of them CCs.
1 to 25 items
2 types
Signer
- namestring
  The person's name.
  Up to 200 characters
- emailemailRequired
  The person's email address.
- refstringRequired
  Your own short name for this person, unique in this request. Fields point at it.
  1 to 40 characters
- role"signer"
  Default signer
- 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
CC
- namestring
  The person's name.
  Up to 200 characters
- emailemailRequired
  The person's email address.
- refstringRequired
  Your own short name for this person, unique in this request. Fields point at it.
  1 to 40 characters
- role"cc"Required
use_markersboolean
Create fields from {{...}} markers in the PDF. fields then becomes optional, and any you send are added to the detected ones.
Default false
fieldsarray of objects
Each signer needs at least one field they fill in. Required unless use_markers is true.
Up to 500 items
12 child fields
- recipientstringRequired
  The ref of the signer who fills this field.
  1 to 40 characters
- typestringRequired
  One of signature, initials, name, email, date, text, number, checkbox, dropdown
- pagenumberRequired
  The page number, starting at 1.
- xnumberRequired
  Distance from the page's left edge, as a fraction of its width.
  0 to 1
- ynumberRequired
  Distance from the page's top edge, as a fraction of its height.
  0 to 1
- widthnumberRequired
  A fraction of the page width. x + width can be at most 1.
- heightnumberRequired
  A fraction of the page height. y + height can be at most 1.
- labelstring
  The label the signer sees.
- requiredboolean
  Default true
- optionsarray of strings
  The choices, for a dropdown.
- prefilledboolean
  You fill this field in now, and it locks. Text fields only.
  Default false
- prefill_valuestring
  The value of a prefilled field.

Example request

curl -X POST "https://www.inkly.so/api/v1/documents/from-upload" \
  -H "Authorization: Bearer $INKLY_API_KEY" \
  -H "Idempotency-Key: crm-8841-send-1" \
  -H "Content-Type: application/json" \
  -d '{
    "upload_id": "d06b8e24-9f13-4c7a-a5d8-3e1c7f2b6049",
    "title": "Consulting agreement",
    "external_id": "crm-8841",
    "signing_order": "parallel",
    "recipients": [
      {
        "ref": "client",
        "name": "Alex Morgan",
        "email": "alex@example.com",
        "delivery": "link"
      },
      {
        "ref": "finance",
        "role": "cc",
        "name": "Sam Lee",
        "email": "sam@example.com"
      }
    ],
    "fields": [
      {
        "recipient": "client",
        "type": "signature",
        "page": 1,
        "x": 0.1,
        "y": 0.8,
        "width": 0.35,
        "height": 0.06
      },
      {
        "recipient": "client",
        "type": "date",
        "page": 1,
        "x": 0.55,
        "y": 0.8,
        "width": 0.2,
        "height": 0.04
      }
    ]
  }'

Example response, 201

{
  "document": {
    "id": "3f1c2a7e-8b4d-4e21-9a6f-5d0c7e1b2a34",
    "title": "Consulting agreement",
    "status": "sent",
    "external_id": "crm-8841",
    "template_id": null,
    "created_at": "2026-11-02T15:04:05.123Z"
  },
  "recipients": [
    {
      "id": "5b7e9d13-2c84-4f06-b1a9-6d40e8c2f715",
      "ref": "client",
      "role": "signer",
      "name": "Alex Morgan",
      "email": "alex@example.com",
      "delivery": "link",
      "status": "pending",
      "signing_url": "https://www.inkly.so/documents/3f1c2a7e-8b4d-4e21-9a6f-5d0c7e1b2a34/sign/example-signing-token"
    },
    {
      "id": "e47a0c96-7d21-4b58-9f3e-08b6c1d5a243",
      "ref": "finance",
      "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.
- refstringRequired
  The ref you sent for this person.

Errors specific to this endpoint

dropdown_options_invalid400A dropdown's options are missing, duplicated, or not valid.
field_out_of_bounds400A field falls outside the page.
idempotency_key_required400Provide an Idempotency-Key header.
invalid_request400The request is invalid.
prefilled_value_conflict400Prefilled fields with the same label must have the same value.
recipient_invalid_email400A recipient's email address is not valid.
unknown_field400This field is not supported.
sending_paused403Sending is paused for this workspace. Contact support.
storage_limit_reached403This workspace has reached its document storage limit. Upgrade your plan or email hello@inkly.so for more storage, then retry with a new Idempotency-Key.
upload_not_found404Upload 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.
upload_already_used409This upload has already been used to send a document.
upload_in_progress409Another request is processing this upload. Retry shortly.
upload_incomplete409The PDF has not been uploaded yet. PUT the file to upload_url, then retry.
upload_expired410This upload has expired. Create a new upload and try again.
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_signers422The document has no signers.
invalid_pdf422The uploaded file is not a valid PDF.
marker_invalid422A field marker is malformed, wraps onto another line, starts in the middle of other text, does not fit on its page, or takes the document over 500 fields.
marker_not_found422use_markers is true, but the PDF has no field markers Inkly can read. A scanned PDF has no text, so send fields with coordinates instead.
marker_page_unsupported422A page with a field marker uses text or layout Inkly cannot place a field on exactly. Fix the PDF, or send fields with coordinates instead.
marker_pdf_too_complex422The PDF is too large or complex for marker detection. Send fields with coordinates instead.
marker_unknown_recipient422A field marker names a signer that is not a signer ref in this request.
pdf_too_many_pages422The PDF has more than 500 pages.
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.