Create an envelope from a template via the API

If your HRIS, intake app, or ops worker already knows the recipient, do not retype them on the desk. Save the PDF and field marks once as a workspace template. Then create a draft from that templateId, fill values you already have, and send. The public API is that path. The desk remains where you design the layout.

The route list and webhook verify steps live in public API and signed webhooks. Who should click versus who should POST is API vs desk for ops teams. Desk help is Docs. This guide is the create-from-template job, start to send.

What you need before the first POST

1. A workspace template with marks already assigned to recipient slots. Templates that reuse field layouts and assign fields to each signer are the desk work.
2. An owner or admin. Members can send from the desk; they cannot mint tokens.
3. A secret store for Authorization: Bearer ip_…. Do not put a token in a browser bundle.

Tokens never cross workspaces. Successful calls update last-used time. Revoke in Settings if a key leaks. Staging should not share production’s token, signing secret, or webhook URL. A forgotten key that has been silent for a month should be rotated, not left in a worker “just in case.” More on templates is the save; Settings → tokens is the mint.

Create the draft

POST /api/v1/packets with templateId, an optional title, optional field values, and an optional per-packet webhookUrl. The response is a draft envelope in the current organization. There is no “upload a PDF through the API” write path in this pass. If the layout is wrong, fix the template on the desk and create again.

Send an Idempotency-Key on create if the worker may retry. The same key with the same body returns the original response. A different body with the same key returns 409. That header is a client retry, not a webhook retry — webhook retries explained is the delivery queue.

Fill what you already know

POST /api/v1/packets/:id/fill sets existing field values by id or label. Use it for a title, an entity name, a date you already have. Leave signature and initials for the signer. PUT /api/v1/packets/:id/fields replaces marks on a draft if you must, but the intended path is: design on the desk, copy from the template, fill known text, send.

Send the envelope

POST /api/v1/packets/:id/send requires fields on the envelope and a remaining envelope on the plan. The response includes signingUrl, embedUrl, emailSent, and emailError. When Resend is missing, email was not sent and you still have the URL — hand it to mail you already send, or iframe embedUrl on a portal you already operate. Embedded signing is the allowlist and postMessage guide.

Send accepts reminder interval, expiration, an optional access code, recipients, and routingMode (SEQUENTIAL or PARALLEL). A single name and email still works. One multi-signer envelope is one envelope, not one envelope per recipient. Send one envelope to multiple signers and More on signing order match those fields. Share an access code on a second channel; the API hashes it and returns the plaintext once.

Stay on the same id after send

Void, resend, and correct sit next to send on the same envelope id. Do not POST create again because an invite failed. A second draft is a second envelope and a second audit trail. Envelope admin is the product explanation. Verify webhooks with HMAC-SHA256 of timestamp.body using the workspace signing secret. Reject stale timestamps. Do not treat iframe events as the server record. The parent tab can lie; a verified POST cannot.

Caps and what is not open yet

Send checks the monthly envelope count. Free allows 5 packets a month. Free at 5 packets a month is the cap this route shares with the desk, bulk send, and Web Form fills. Hitting it returns HTTP 402 and code ENVELOPE_LIMIT. Each API token allows 120 requests per minute per token. Over that limit, /api/v1 returns HTTP 429 with a Retry-After header. Inkpacket does not send X-RateLimit headers. /api/v1 does not return HTTP 429 for traffic. Access-code 429 is a PIN lockout, not a send throttle. Starter is 20 envelopes — more than Free — plus 3 published Web Forms. Seat counts are planning numbers.

Billing checkout is not open. The API still enforces plan envelopes. GET /api/v1/health reports the same flags Settings shows: mail, SMS, Drive, payments. Text-message (SMS) is coming soon. Drive missing: Drive not configured. Stripe off: Payments not live. The envelope still exists.

What this path is not

• Not a hidden Web Form. If strangers should start the envelope, publish /form/SLUG — Web Form intake.
• Not a field-detection API. Suggest starting layout is a desk heuristic.
• Not a place to put the Bearer token in a frontend.
• Not a second envelope because the first email was lost. Resend the existing link.

Save the template. Mint the token. Create, fill, send with an Idempotency-Key. Watch Settings for last-used time on that key. Verify the next webhook. That is the integration. Open a workspace on Free and run one envelope from a worker before you promise a production destination. The FAQ repeats the envelope cap in the same words.