API fill then send

The public API is three verbs after you have a workspace template: create the draft, fill known values, send. POST /api/v1/packets with a templateId returns a draft. POST /api/v1/packets/:id/fill sets existing field values by id or label. POST /api/v1/packets/:id/send is the envelope. Fill is not send. Create is not send. A draft does not count toward the month. That is fill-then-send honesty: the worker writes what it already knows, then it sends, and it does not treat a 200 on fill as a signing link.

The longer create-from-template job is create an envelope from a template via the API. Secrets are mint and revoke API Bearer tokens. Retries are Idempotency-Key on API sends. Desk help is Docs. This guide is the fill-then-send sequence itself.

The FAQ says create from a template, fill fields, and send. Features lists the same loop under API. Ask Inkpacket for API fill then send to open this article. Ask how the API works to open help. Those phrases stay on the product screens. This article is the public version of why fill and send are two POSTs.

Fill what you already know

• Match by fieldId or by label. Labels compare case-insensitively.
• Skip empty values. Provide at least one field value or the route returns 400.
• A missing id or label returns Field … was not found on this envelope.
• An envelope with no marks returns This envelope has no fields to fill.

Leave signature and initials for the signer. Fill a title, an entity name, a date you already have. 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. Locked statuses refuse fill with This envelope can no longer be edited. Do not fill a sent envelope hoping to rewrite history.

Idempotency on fill

Send an Idempotency-Key on create, fill, fields, and send if the client may retry. The same key with the same body returns the original response. A different body with the same key returns 409. Void, resend, and correct do not use that header. A replayed fill is not a second envelope. A replayed send with a new key is. Idempotency-Key on API sends is that 409.

Send is the envelope

POST /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. Copy the signing link after mail skips is that box. Send accepts reminder interval, expiration, an optional access code, recipients, and routingMode. One multi-signer envelope is one envelope, not one envelope per recipient.

Do not POST send twice because fill felt incomplete. Fill again on the draft, then send once. Do not POST create again because send returned emailSent false. Stay on the same id. Correct or resend after send if the recipient or the inbox was wrong — correct an envelope mid-flight.

What fill-then-send is not

• Not a hidden Web Form. Strangers start at /form/SLUG — they do not call /fill.
• Not a field-detection API. Suggest starting layout is a desk heuristic.
• Not a Bearer token in a browser bundle.
• Not HTTP 429 for traffic. The send guard is HTTP 402 ENVELOPE_LIMIT.

The click-path

1. Save a template with marks on the desk. Mint an ip_… token in Settings.
2. POST /api/v1/packets with templateId and an Idempotency-Key.
3. POST /fill with the values you already have. Read the updated fields.
4. POST /send. Read signingUrl and emailSent. Copy the URL if mail skips.
5. Do not treat the fill 200 as a send. Do not create a twin to “retry fill.”

Members can send from the desk. They cannot mint tokens. Owners and admins mint at /desk/settings#tokens. Successful calls update last-used time. Mint and revoke is the secret loop. Webhooks hear sent after this sequence, not after fill.

Caps and what is not open yet

Fill does not count. Send does. Free allows 5 packets a month. Free at 5 packets a month is the live cap desk send, bulk rows, Web Form fills, and API send share. Hitting it returns HTTP 402 ENVELOPE_LIMIT. Starter is 20 envelopes — more than Free — plus 3 published Web Forms. Seat counts are planning numbers; invite does not refuse when a workspace is full.

Billing is published, not charging. Checkout is not open. Text-message (SMS) is coming soon. Drive missing: Drive not configured. Stripe off: Payments not live. Those flags do not turn a fill into a send or waive the 402. The FAQ and Public API use fill fields, and send in the same words.

Create. Fill. Send. Stay on that id. Open a workspace on Free — see published pricing — and run one worker envelope so fill-then-send is a pair of POSTs you have watched before a production destination depends on them.