Create a document
POST
/api/v1/documentsUploads files, adds recipients and fields, and sends the document unless draft is true. Send JSON with files as file_url or file_base64, or multipart/form-data with files plus a JSON payload field. Fields are required unless the document is a draft, uses text_tags, or uses with_signature_page.
Body parameters
filesarrayRequired- Each item is { name, file_url } or { name, file_base64 }. PDF, Word, images and more are converted to PDF.
recipientsarrayRequired- Each item is { id, name, email, signing_order?, passcode?, passcode_delivery?, subject?, message?, send_email?, send_email_delay? }. id is your own reference, such as "1".
fieldsarray of arrays- One array per file. Each field has type, page, x, y, width, height, recipient_id and optional api_id, required, label, value, validation, date_format, options.
namestring- Document name. Defaults to the first file's name.
subject / messagestring- Email subject and message for recipients.
draftboolean- Save without sending. Send later with Update and send.
self_signboolean- Only the sender signs. No recipients needed.
test_modeboolean- Free, not legally binding and does not count toward limits. The X-TestMode-Enabled header works too.
apply_signing_orderboolean- Recipients sign one after another in signing_order.
expires_ininteger- Days until signing links expire (1 to 365).
remindersboolean- Send automatic reminders to recipients who haven't signed.
allow_decline / allow_reassignboolean- Let recipients decline, or pass the document to someone else.
redirect_url / decline_redirect_urlstring- Where to send recipients after they sign or decline.
embedded_signingboolean- Return embedded_signing_url for each recipient so you can sign inside your own app.
text_tagsboolean- Create fields from {{text tags}} found in the files.
copied_contactsarray- People to CC: [{ name, email }].
metadataobject- Your own key value pairs. Returned on every response and webhook.
labelsarray- Label names to file the document under.
languagestring- Recipient language code, such as en, fr, de or es.
checkbox_groups / conditional_rules / attachment_requestsarray- Checkbox validation groups, show or hide rules, and files to request from signers.
api_application_idstring- Brand and isolate the document with an API application.
Request
curl -X POST "https://sign.scalesmart.dev/api/v1/documents" \
-H "X-Api-Key: $SCALESIGN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Services Agreement",
"files": [{ "name": "agreement.pdf", "file_url": "https://example.com/agreement.pdf" }],
"recipients": [{ "id": "1", "name": "Alex Kim", "email": "alex@example.com" }],
"fields": [[{ "type": "signature", "page": 3, "x": 72, "y": 640, "width": 180, "height": 44, "recipient_id": "1", "api_id": "client_signature" }]],
"metadata": { "deal_id": "4521" }
}'Response (201 Created)
{
"id": "6d0c3a9e-2c1f-4b8e-9f51-0c7c3f8e2a10",
"object": "document",
"name": "Services Agreement",
"subject": "Please complete Services Agreement",
"message": "Hi Alex, here is the agreement we discussed.",
"status": "Sent",
"test_mode": false,
"draft": false,
"requester_email_address": "jane@acme.com",
"metadata": { "deal_id": "4521" },
"created_at": "2026-10-20T09:14:02.884Z",
"updated_at": "2026-10-20T09:14:03.120Z",
"sent_at": "2026-10-20T09:14:03.120Z",
"completed_at": null,
"recipients": [
{
"id": "1",
"uuid": "0f9a6c1e-6a52-4d0e-9a8e-3e1c1b2f4d77",
"name": "Alex Kim",
"email": "alex@example.com",
"placeholder_name": null,
"delivery_method": "email",
"signing_order": 1,
"signing_url": "https://sign.scalesmart.dev/sign/Xr8kq2mN4tY7",
"embedded_signing_url": null,
"bounced": false,
"attachment_requests": [],
"passcode": null,
"passcode_delivery": { "enabled": false, "methods": null, "expire_after_access": false },
"status": "sent",
"sent_at": "2026-10-20T09:14:03.120Z",
"viewed_at": null
}
],
"files": [{ "name": "agreement.pdf", "pages_number": 3 }],
"fields": [
[
{
"api_id": "client_signature",
"type": "signature",
"page": 3, "x": 72, "y": 640, "width": 180, "height": 44,
"recipient_id": "1",
"required": true,
"value": null
}
]
],
"copied_contacts": [],
"labels": [],
"reminders": true,
"apply_signing_order": false,
"expires_in": 30,
"expires_at": "2026-11-19T09:14:03.120Z",
"allow_decline": true,
"allow_reassign": true,
"redirect_url": null,
"language": "en",
"embedded_signing": false,
"embedded_edit_url": null,
"embedded_preview_url": "https://sign.scalesmart.dev/documents/6d0c3a9e-2c1f-4b8e-9f51-0c7c3f8e2a10?embedded=1",
"checkbox_groups": [],
"conditional_rules": [],
"template_id": null,
"template_ids": [],
"completed_pdf_url": null
}