Sending

Prepare a draft from an uploaded PDF

post/drafts/from-upload

Prepares a PDF uploaded through POST /uploads as an editable draft. Recipients and fields are optional; finish missing details in Inkly. Delivery is email only. Supports coordinates and use_markers with the same syntax as POST /documents/from-upload. Retrying upload_id returns the same document unchanged, including after staging cleanup. No invitations or monthly allowance charge. The workspace draft limit and the app upload and storage limits apply. Do not send Idempotency-Key.

Needs a key with documents:send.

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 below
Up 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
- delivery"email"
  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
Optional fields. A draft without fields can be finished in the editor.
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.

curl -X POST "https://www.inkly.so/api/v1/drafts/from-upload" \
  -H "Authorization: Bearer $INKLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "upload_id": "d06b8e24-9f13-4c7a-a5d8-3e1c7f2b6049",
    "title": "Consulting agreement"
  }'

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

field_out_of_bounds400A field falls outside the page.
invalid_request400The request is invalid.
prefilled_value_conflict400Prefilled fields with the same label must have the same value.
unknown_field400This field is not supported.
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.
upload_already_used409This upload has already been used to create 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.
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.
temporarily_unavailable503The service is temporarily unavailable. Try again.

Every endpoint can also return the common errors.