Skip to the main content

API reference

Everything the app does goes through this JSON API. Create a key under Settings, then API and webhooks, and send it as a Bearer token.

Before you start

  • The API is the same on every plan, including the free one. There is no separate API plan and no feature held back for a higher tier.
  • There is no go-live review. A key works the moment you create it, against the real service. There is no separate test environment to move out of.
  • Running out never turns into a charge. A send needs one signature for each signer, the same as in the app. If the account has too few, the call returns 402 and says how many are needed and how many are left. Nothing is billed.
  • The rules that keep scammers out are the same as in the app. They apply to every call that emails a recipient: sending, a correction, a reminder, reopening and a bulk send. 403 means sending is paused on the account, and gives the reason. 422 means the request reads like a fake payment notice, or goes out under the name of a well-known brand, and says which words set it off. 429 means it would newly email more people than the daily limit, and says when there is room again. The last two apply until the account has a payment that is 14 days old and was not refunded or disputed, so paying does not lift them at once. A word with us lifts them sooner. While an account is paused, more time for an envelope that is out still works, and so does voiding.
  • Errors are written for people. Every error is JSON with an error that says what went wrong and what to do, and a request_id. The same id is in the X-Request-Id header of every response. Quote it when you ask for help.
  • A key does everyday work, and nothing else unless you say so. A new key has the send scope: envelopes, templates, files, contacts, bulk sends, export and reports. An admin can create a key with the admin scope, which also covers account settings, invitations and webhooks. No key of either scope can create or revoke keys, remove a team member, hand over or close the account, see or change the ways its creator signs in (a password link, Google or Microsoft), see or change two-step login, write, read or answer help requests, or change the plan, pay or refund. Those answer 403 and need a person signed in to the app. Two-step login does not apply to keys: a key is never asked for a code, also not in an account that requires it of its members, so treat a key like a password.
  • A key that cannot be used says why. 401 tells you whether the header could not be read, the key is unknown or revoked, or the person who created it has left the account. While an account is being closed, or the person who created a key is closing their own login, the key answers 403 until that person signs in again. When a key stops because its creator left a team, by being removed or by closing their login, the admins of the team get an email that names it. The word Bearer may be in any case.
  • Retries are safe. Send an Idempotency-Key header, any text of up to 200 characters that you make up for that one call, with POST /api/envelopes and POST /api/bulk. A repeated call with the same key and the same body returns the envelope or batch the first call made instead of sending twice. A key is yours: the same text used by someone else on your team is their own key. The same key with a different body answers 409 and sends nothing. A key lasts as long as what it made: delete the envelope and the key is free again.
  • Sending can come back with warnings, and never fails because of them. Sign&Grow makes simple electronic signatures. Some documents often need ink on paper, a witness, a notary or a qualified signature, depending on the country: wills, trusts, powers of attorney, sales of land, and in some countries parts of an employment contract. When the subject, a document name or the text of a document names one, POST /api/envelopes with "send": true, POST /api/envelopes/:id/send and POST /api/bulk answer with a warnings list that says which word was found and where, and the audit trail records it. Show it to whoever is sending. It is a reminder, not legal advice: what we know, country by country.
  • An envelope reminds people by itself unless you say otherwise. A new envelope takes the account's default for reminder_days, which is 3 for an account made since reminders are on by default: whoever has their turn and has not finished is emailed again every 3 days, until they finish or the deadline passes. Send "reminder_days": 0 if your own system does the reminding. The account's default is account.default_reminder_days in GET /api/me.
  • All times are ISO 8601 in UTC. A machine-readable description is at /api/openapi.json.

Send a document in three calls

# 1. Upload the PDF
curl -H "Authorization: Bearer $KEY" -F file=@contract.pdf https://YOUR_HOST/api/files
# => {"id":"fil_...","pages":2,...}

# 2. Create and send. Positions are fractions of the page, measured from the top left.
curl -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: contract-4471" \
  https://YOUR_HOST/api/envelopes -d '{
    "subject": "Please sign: contract",
    "send": true,
    "documents":  [{"id": "d1", "file_id": "fil_..."}],
    "recipients": [{"id": "r1", "role": "signer", "name": "Ada Lovelace", "email": "ada@example.com"}],
    "fields":     [{"document_id": "d1", "recipient_id": "r1", "type": "signature",
                    "page": 0, "x": 0.1, "y": 0.8, "w": 0.25, "h": 0.06}]
  }'

# 3. Download the signed PDF once the envelope.completed webhook fires
curl -H "Authorization: Bearer $KEY" -o signed.pdf https://YOUR_HOST/api/envelopes/env_.../download

Fields may be sent without ids. Each one gets its own id on the server. Documents and recipients take any short id you like, such as d1 and r1, so that fields can point at them. The response carries the permanent ids.

Recipient roles: signer, approver, cc, viewer, inperson, witness. Field types: signature, initials, date_signed, full_name, email, text, number, date, company, title, checkbox, radio, dropdown, attachment, note, strike.

A witness is a recipient with the role witness and witness_for, the id of the person who signs whose signature they watch. Give them at least a signature field. They are asked straight after that person has signed, and never use a signature. With "named_by_signer": true and no name or email, that person names the witness on the signing page before Finish. The witness ticks a statement of their own first (witness_statement in the answer), or says they were not there (witness_absent_at). Sign&Grow records what a witness states and cannot check it. See /api/openapi.json.

CallWhat it does
Files and envelopes
POST/api/filesUpload a PDF, PNG or JPEG as the multipart field "file", up to 25 MB and 500 pages. Returns the file id, page sizes and stored size. A phone photo is turned upright from its camera note. Repeat "file" to make one document from several pictures, a page for each, in the order sent. A PNG can have up to 25 million pixels and a JPEG up to 50 million.
POST/api/envelopesCreate a draft, or create from a template with template_id. Add "send": true to send straight away.
GET/api/envelopesList envelopes. Filters: box (drafts, sent, waiting, completed, closed), q, folder, kind=template, limit, offset.
GET/api/envelopes/:idOne envelope with its documents, recipients and fields, the audit trail, the email delivery log and how far each signer has got.
PUT/api/envelopes/:idNewReplace a draft. On an envelope that is already out, the same call corrects it in place.
PATCH/api/envelopes/:idMove to a folder.
DELETE/api/envelopes/:idDelete a draft, a template or a closed envelope for good. A completed envelope, or any envelope somebody has already signed, is taken out of your lists, search, export and reports, and its recipients keep their link and their copy.
POST/api/envelopes/:id/sendSend a draft. The answer carries "warnings": what the check before sending found. The envelope has gone out either way.
GET/api/envelopes/:id/warningsNewThe check before sending, to read before you send: words in the subject, a document name or the text of a document that name a kind of document which often needs paper, a witness, a notary or a qualified signature. It warns and never refuses.
POST/api/envelopes/:id/cloneCopy as a new draft or template. A copy of a template keeps who can use and change it, and a copy of a locked template made by someone who may not change it stays with its owner.
GET/api/envelopes/:id/accessWho can use and change a template (everyone, admins only or chosen members; its owner and admins, chosen members as well or everyone), and whether its wording is locked. A template you may not use answers 403 with who to ask, wherever it is read or used.
PUT/api/envelopes/:id/accessSet that rule and the chosen members. Only for the person the template belongs to and admins. Written to the template's history.
GET/api/envelopes/:id/downloadThe signed PDF with its certificate, or a preview while signing is in progress. A voided, declined or expired envelope comes with a first page that says so and a mark across every page.
GET/api/envelopes/:id/evidenceThe evidence pack as a ZIP: the signed PDF, the certificate alone, the audit trail as text and JSON with its chain values, every stored email about it with what became of it, the consent wording and a README.
While an envelope is out
POST/api/envelopes/:id/remindNewRemind everyone whose turn it is. Send a recipient_id to remind one person only.
POST/api/envelopes/:id/extendNewPush the deadline out by a number of days, or reopen an envelope that expired.
POST/api/envelopes/:id/correctFix one recipient's name, email or access code. A name fix keeps their link. A new email address gets a new one, and counts as a new person towards the daily limit of an account that has not paid. An access code needs at least 4 characters, and a new one unfreezes a code that was frozen after 10 wrong tries. Also takes "verify", "phone" and "text_link": see Checking who signs.
POST/api/envelopes/:id/voidVoid with a reason. Recipients see the reason.
POST/api/envelopes/:id/recipient-viewGet one recipient's signing URL, for embedded signing.
GET/api/envelopes/:id/commentsEvery question and comment thread, private ones included, with who waits for an answer. Comments are not printed on the document and are not part of what is signed.
POST/api/envelopes/:id/commentsAnswer in a thread ("thread_id"), or start one: "for" is "everyone" or the id of one person, and is never guessed. The person answered is emailed, at most once every 10 minutes. The comment.created webhook fires.
POST/api/envelopes/:id/comments/:thread/settleMark a thread as settled, or open it again with {"settled": false}.
Batches
POST/api/bulkSend a template to up to 500 people in one call. Returns the batch id and a result for every row.
POST/api/bulk/checkNewWhat a list would hold before you send it: how many signatures, how many you have, how many are missing and what they cost, and whether a pause or the daily limit would refuse it. Sends nothing.
GET/api/bulkNewList batches, with how many envelopes each created and completed.
GET/api/bulk/:idNewOne batch with every envelope and the status of every recipient.
POST/api/bulk/:id/remindNewRemind everyone in the batch who has not finished.
POST/api/bulk/:id/voidNewVoid everything in the batch that is still open, with one reason.
Signing groups
GET/api/groupsNewThe account's signing groups: a name and 2 to 20 people, any one of whom can act for it. Put one on a recipient with "group_id" (signer, approver, viewer or copy). Every member gets their own email and link; the first who agrees takes it on, and it uses one signature.
POST/api/groupsNewMake a group. For admins.
PUT/api/groups/:idNewReplace its name and members. For admins. Envelopes already sent keep the members they went out with: change those with PUT /api/envelopes/:id and "members".
DELETE/api/groups/:idNewDelete a group. For admins. Envelopes already sent are not affected.
POST/api/envelopes/:id/recipients/:rid/releaseNewGive a group's document back to the whole group, from the member who took it on and has not finished.
Your data
GET/api/exportNewOne ZIP file with signed PDFs, audit trails and a CSV index. Add ?ids= for some envelopes only.
GET/api/reports/summaryCounts, completion time and paper saved.
API keys
GET/api/api-keysNewYour keys with their name, scope and last use. An admin gets every key in the account and who made it. The key itself is never returned.
Webhooks (account admins; changing them needs a key with the admin scope)
GET/api/webhooksYour webhooks, the event names and the delivery log, newest first, 30 at a time. Add ?webhook= for one webhook, and ?before= with the next_before of the last page to go further back.
POST/api/webhooksAdd a webhook with a url and, if you like, a list of events. Leave events out to get all of them. Up to 20 per account.
DELETE/api/webhooks/:idRemove a webhook.
POST/api/webhooks/deliveries/:id/redeliverNewSend a past delivery again, exactly as it was. Works for the latest 200 deliveries of each webhook.
No key needed
POST/api/public/verifyCheck whether a PDF is, byte for byte, a completed document we hold. A match shows it is unchanged since signing finished, not who signed. For a completed document whose sender deleted it in the last year, "deleted" says so.
GET/api/public/verify/:idLook an envelope up by the ID printed on every page: status, dates, pages, signers, the fingerprint of the signed file and whether it is disputed. Never a name, an address or the title.
POST/api/public/check/dispute"I did not sign this, or this was not me", with the security code of an email we sent. Marks the envelope as disputed; nothing is deleted.
POST/api/public/checkNewCheck the security code from a signing email.
GET/api/auth/providersNewWhich of Google and Microsoft people can sign in with on this server, next to email and password. Empty when the operator has set up neither. Signing in itself is for a person in a browser, never for a key.
GET/api/openapi.jsonThis API as an OpenAPI 3 description, for code generators and API clients.

Correct an envelope that is already out

PUT /api/envelopes/:id on a sent envelope is a correction. Nothing is voided, nobody starts again, and it does not count as another envelope. Read the envelope, change what is wrong, and send the whole thing back with the ids you were given.

curl -s -H "Authorization: Bearer $KEY" https://YOUR_HOST/api/envelopes/env_... \
  | jq '.envelope | .recipients[1].email = "right@example.com"' > fixed.json

curl -X PUT -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  https://YOUR_HOST/api/envelopes/env_... -d @fixed.json

The lock rule.

  • Until someone has finished, anything can change: documents, recipients, fields, subject, message and order.
  • Once a signer, approver or viewer has finished, two things stay as they are. One is what is printed on the documents: the files and their order, every field and whose it is, any wording you wrote on the pages (notes, read-only values, values you filled in for a signer), any name or address a full name or email field prints, also of someone who only gets a copy, and the date format. The other is the people who finished: their name, email, role and place in the order, and whether they are on the envelope at all. A call that touches one of them returns 409 with "code": "sign_again", says who would have to sign again and what would change, and saves nothing.
  • To make such a change anyway, send the same call with "resign": true. Everyone who finished is then told what changed and asked to sign again. Their first signature and answers stay in the audit trail, the certificate shows both times, and signing again does not use another signature.
  • Names, email addresses and the order of the people who have not finished can still change freely, unless a full name or email field prints that name or address on the pages. So can the subject, the message, what a field asks of its signer (label, required, choices), and the access code and private note of anyone, finished or not.
  • A value a signer typed into their own field is never changed by a correction, whatever your body carries for it. The same goes for what a signer who has finished left empty or unticked: that is their answer.

Nothing is dropped without a word. A part of the body that cannot be carried out as you wrote it returns 400, names the part and saves nothing: a field of a type that does not exist, or for a recipient or document that is not in the body; a role, date format or kind that does not exist; two items with the same id; a page the document does not have; text over its limit; a number out of range; a list that is not a list; a value on a signature, initials, attachment or automatic field. Send the edit_version you got from the GET call, and a save from an out-of-date copy returns 409 with "code": "stale" and who changed the envelope, when, and how if it was not a save (edited_how: a quick correction, a signer who passed the document on or fixed their name, or sending), instead of undoing it. Leave it out and the call is not checked.

What recipients notice. Someone whose part did not change keeps the same link and hears nothing. Someone whose part changed keeps their link and gets an email that says the document was updated. A changed email address or role gets a fresh link, and the old one answers 410. A new address is a new person, so they start with empty fields: nothing the first person typed or drew is passed on. Someone you remove is told they are no longer needed. If you change the signing order, someone who has the document but is now behind a person who has not finished is told to wait, and is emailed again when it is their turn. A signer who has the page open while you correct the document cannot finish on the old version: their page loads the new one, a replaced file included, and Finish stays off until its pages are on their screen. Someone who is asked to sign again can still download the document as they signed it the first time. The audit trail, which is printed on the certificate, records what each correction changed in words. The envelope.corrected webhook fires.

A list you send (documents, recipients, fields) replaces the list that was there, so send each list in full. A list or a setting you leave out altogether stays as it is. Keep the field ids from the GET call: a field sent without its id counts as a new field.

More time, one reminder, and everything out

Extend. POST /api/envelopes/:id/extend with {"days": 14} pushes the deadline out. Days can be 1 to 365 and default to 30. On an expired envelope it reopens it: the same links work again, people who were waiting are told, and nobody who signed has to sign again.

Remind one recipient. POST /api/envelopes/:id/remind with {"recipient_id": "rcp_..."} reminds that person only. With no body it reminds everyone whose turn it is. The answer says how many were reminded. A recipient who switched reminders off is skipped and shows muted: 1.

Export. GET /api/export returns one ZIP file: signed/ with every completed PDF and its certificate, audit/ with each audit trail as JSON, and envelopes.csv. Add ?ids=env_a,env_b to pick envelopes. It is free on every plan and keeps working after a paid plan ends.

Batches. A bulk send is one thing you can act on. GET /api/bulk/:id shows every envelope and recipient in it, POST /api/bulk/:id/remind nudges the people who have not finished, and POST /api/bulk/:id/void closes what is still open. Both work through the batch one envelope at a time. An envelope that someone finishes or declines while that is going on is left as it is, and the void answers with how many it voided and how many it skipped for that reason.

A bulk send that is repeated. POST /api/bulk answers when every row has been tried, which takes as long as the mail server needs for the whole list. Send it with an Idempotency-Key. If your call times out, repeat it with the same key and body: while the first call is still sending you get 202 with the same batch and what has gone out so far, and afterwards 200 with the full result. If our side stopped half way, the repeat sends the rows that had not gone out, and nobody gets a second copy. GET /api/bulk/:id lists every row as sent, failed (with the reason) or pending.

Webhooks

Add a URL under Settings, then API and webhooks. We POST JSON for these events: envelope.sent, envelope.completed, envelope.declined, envelope.voided, envelope.expired, envelope.corrected, envelope.updated, recipient.viewed, recipient.completed, comment.created.

{
  "id": "evt_Xk3...",
  "event": "envelope.completed",
  "created_at": "2026-11-20T09:12:44.000Z",
  "envelope": { "id": "env_...", "status": "completed", "subject": "Please sign: contract",
                "sent_at": "2026-11-19T15:02:10.000Z", "completed_at": "2026-11-20T09:12:44.000Z" },
  "text": "Please sign: contract: envelope completed"
}
  • New event: envelope.corrected. Sent whenever an envelope that is out is corrected. Read the envelope again to see how it stands.
  • Recipient events and envelope.declined also carry a recipient_id.
  • The text property is a one-line summary of the event. Slack and Microsoft Teams incoming webhooks show whatever is in text, so you can paste an incoming webhook URL as the webhook address and get every event as a chat message. No code needed.
  • Retries. A delivery that fails is tried three times in all, a few seconds apart. Your endpoint has 10 seconds to answer with a 2xx status. A redirect is not followed and counts as a failure. Only the status of your answer is read.
  • Redelivery. Every delivery is in the log from before the first try, so an event is listed even if our side restarts halfway. After you fix your side, send any of the latest 200 deliveries of that webhook again from Settings, or with POST /api/webhooks/deliveries/:id/redeliver. Older ones stay listed but can no longer be sent again. The id in the body stays the same, so you can ignore repeats.
  • No silent failures. After three failed deliveries in a row, the account admins get an email.
// Verify a delivery (Node.js)
const expected = "sha256=" + crypto.createHmac("sha256", WEBHOOK_SECRET)
  .update(req.headers["x-signandgrow-timestamp"] + "." + rawBody).digest("hex");
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers["x-signandgrow-signature"]));

Webhook addresses must use https and point to a public address. The name is looked up once when each delivery starts, and the delivery only connects to an address that passed the check.

Checking who signs

Each recipient can carry a check that has to be passed before the document opens for them. Set it where you set the name and the email address, on POST /api/envelopes, on PUT /api/envelopes/:id and on POST /api/envelopes/:id/correct:

"recipients": [{
  "name": "Sam Signer", "email": "sam@example.org",
  "verify": "sms_code",        // "none" (the default), "email_code" or "sms_code"
  "phone": "+447700900123",    // E.164: plus sign, country code, number. Needed for "sms_code" and for "text_link"
  "text_link": true            // also text the signing link. Off unless you send true
}]
  • email_code sends a 6-digit code to the recipient's email address, sms_code by text message to phone. The code is sent when the person asks for it on the signing page, works for 10 minutes and for 5 tries, and is never in any answer of this API. access_code works as before and can be combined with either: it is asked for first.
  • Text messages exist only when the operator of this server has switched them on. GET /api/me says so in text_messages. When they are off, "verify": "sms_code" and "text_link": true are refused with 400, a sentence that says so, and "code": "texts_off". email_code always works.
  • A phone number that is not in international form, or a missing one where a text is asked for, is refused with 400 when the envelope is sent or corrected. A draft may hold a half-typed number.
  • What comes back: verify, phone, text_link, and check with line (the sentence the certificate will carry, such as “Link sent by email only”), passed_at and stopped (someone using the link said the number is not theirs, and no code goes to it until you correct it). GET /api/envelopes/:id also returns texts: what became of every text message, with the number masked.
  • Changing verify or phone on an envelope that is out makes that person pass the check again and writes a line to the audit trail. Changing their email address to another person's needs their phone in the same call when a text is still asked for: a number typed for one person is never used for another. After someone using the link said the number is not theirs (check.stopped), no code and no text goes to it; send "number_confirmed": true to POST /api/envelopes/:id/correct once you have checked with the person that it is right after all.
  • A text counts like an email to that person: 403 while the account is paused, 429 when an account under the daily limit would text more phone numbers than it may email people, and 429 when the account has used the text messages this server allows it in 24 hours. Texts are not charged for.
  • Templates keep the check. POST /api/bulk and POST /api/envelopes with a template_id take phone next to name and email for each role. A public form refuses sms_code and text_link on the role its visitors fill in, and accepts email_code.

Embedded signing

Call POST /api/envelopes/:id/recipient-view with a recipient_id to get a signing URL, then send your user there in a new tab or with a redirect. The page cannot be shown inside a frame on another site. Any recipient can get a link, it stays the same while the envelope is open, and it survives a correction that leaves that person alone. Ask for it as often as you like: the audit trail on the certificate records that a link was issued at most once a day for each link.

Treat the URL like a password: whoever holds it can sign as that recipient.

To deliver the link entirely yourself, give the recipient "link_by_sender": true and no email. We then never email that person, not even reminders or the completed copy, and this URL is the only way in, also to the completed document afterwards. The certificate says "Link shared by the sender" for them. They count towards the daily limit on new people like anyone, and reminding everyone answers with them in not_reminded.

Click-to-agree terms

Terms your website's visitors accept with one click (made under Click-to-agree in the app, by an owner or admin). Show them on our page /agree/SLUG, inside your own page with <script src=".../clickwrap.js" data-agreement="SLUG"> or an iframe of /agree/SLUG?embed=1, or collect the click yourself and record it with POST /api/clickwraps/:id/acceptances. Ask GET /api/clickwraps/:id/status?person_id=... whether someone has accepted the version that counts.

  • To say who the visitor is, your server adds who (base64url of JSON with id, name, email and exp in seconds) and sig (HMAC-SHA256 of that exact text with the key of the terms) to the address. Without them the visitor types a name and an address, which nobody checks.
  • The frame cannot be ticked or pressed by the page around it, but it can be covered or hidden. Treat the signgrow:accepted event as a hint and ask the status call before you rely on it. An acceptance you record yourself is marked as recorded by your website.
  • An acceptance is not a signature and costs none. Each account can record a limited number a month (429 with "code": "monthly_limit" after that). Whether a click binds anyone depends on the country and on the agreement: check what applies to yours.

Stuck on something this page does not answer? Write to us. A person replies.