Guides

Send a document

Upload PDFs or use templates, place fields, choose how signers get their link, and set the order, deadline and reminders.

The smallest envelope

A title, a document and a signer. With send: true it goes out straight away; without it you get a draft.

json

{
  "title": "Harbour Lane lease, unit 4",
  "documents": [{ "file_url": "https://files.example.com/lease-unit-4.pdf" }],
  "signers": [{ "name": "Ava Chen", "email": "ava@example.com" }],
  "send": true
}

Documents

Each document is one of:

file_base64: the PDF's bytes, base64-encoded.
file_url: an https link squiggli downloads it from.
template_id with variables: a template, rendered now.

PDFs can be up to 10 MB and 200 pages. Password-protected PDFs are refused: remove the password first. name sets the file name signers see. As a shortcut, template_id and variables can go on the envelope itself instead of in documents.

Placing fields

Each field says which document (its index, default 0), which page (1 is the first), where (x, y in points from the top-left), and which signer: their index in signers, their role, or their email.

json

"fields": [
  { "signer": 0, "type": "signature", "page": 3, "x": 72, "y": 640 },
  { "signer": 0, "type": "date_signed", "page": 3, "x": 320, "y": 668 },
  { "signer": 0, "type": "text", "page": 1, "x": 380, "y": 140, "label": "Unit number", "key": "unit" },
  { "signer": 1, "type": "signature", "page": 3, "x": 72, "y": 740 }
]

key is your own name for a field; it comes back with the signer's answer, so you can read unit without tracking field ids. A field that runs off the page is refused with the page's size in the message.

Leave out fields for any signer and squiggli adds a "Signatures" page at the end with a signature and date for them. Good for agreements where position doesn't matter.

Signers

Field	What it does
`name`	Required. Shown on the document and in emails.
`email`	Required for email delivery. Each signer needs a different email.
`delivery`	`email` (default): squiggli sends the link and reminders. `link`: no emails; use `signing_url`.
`role`	Which template role they fill, e.g. tenant.
`order`	Their turn when signing_order is sequential. 1 signs first; equal numbers sign together.
`access_code`	A code they must enter before seeing the document. Give it to them by phone or SMS. See access codes.

Signing order

signing_order: "parallel" (the default) sends to everyone at once. "sequential" sends to the first signer, and each next one gets their invite when the one before has signed.

Deadlines and reminders

Set deadline (an ISO 8601 time) or deadline_days (days from now). After it, the envelope expires and the sender is told.

json

"deadline_days": 14,
"reminders": { "every_days": 3, "before_deadline_days": [1], "max": 5 }

Those are the defaults: a reminder every 3 days, one the day before the deadline, and no more than 5 per signer. "reminders": false turns them off. Each reminder is a fresh link, so you can see which one got them to open it. Move the deadline or change reminders on a sent envelope with PATCH /v1/envelopes/{id}.

Who it's from

sender sets who signers are told sent it ("Priya Shah sent you Harbour Lane lease, unit 4 to sign") and who gets the declined and completed emails. Without it, the business's name and notification email are used.

json

"sender": { "name": "Priya Shah", "email": "priya@harbourlane.com.au" },
"message": "Hi Ava, here's the lease we talked about. Call me with any questions."

Your own data

metadata holds up to 20 string values of your own, returned on the envelope and in every webhook. Filter by it: GET /v1/envelopes?metadata[job_id]=J-1042.

After signing

redirect_url sends signers back to your site after they sign. whitelabel: true removes squiggli's name from everything signers see ($1.50 instead of $1.00).

Drafts

Create without send, check it, then send it. If a send fails (for example 402 card_required), the draft is kept and the error includes its envelope_id, so you can fix the problem and send it without building it again.

bash

curl -X POST https://squiggli.billy-965.workers.dev/v1/envelopes/env_.../send -H "Authorization: Bearer $SQUIGGLI_API_KEY"

Changing your mind

To	Call
Remind people now	`POST /v1/envelopes/{id}/remind` (at most hourly per signer)
Cancel a sent envelope	`POST /v1/envelopes/{id}/void` with an optional reason; signers are told
Delete a draft	`DELETE /v1/envelopes/{id}`
Change the deadline or reminders	`PATCH /v1/envelopes/{id}`