When the website isn't the product

The hosted signing UI is great when a human sends a document. But if signing is a step inside your own application — onboarding a customer, accepting a quote, completing an application — you don't want a person logging into a dashboard. You want your code to create the signature request, hand it to the user in your own interface, and react when it's done. That's what an e-signature API is for.

This is a developer's-eye tour of the moving parts: how envelopes get created in code, how fields get placed without a drag-and-drop editor, how signers sign without leaving your app, and how your backend finds out it's finished. It assumes you've read choosing an e-signature platform and decided API access is a hard requirement, not a nice-to-have.

The unit of work: the envelope

Everything in the API revolves around the envelope — a document (or set of documents), its fields, and its recipients, tracked as one signing transaction. The typical create call, from your server, looks conceptually like this:

POST /api/envelopes
{
  "document": <uploaded file id or template id>,
  "recipients": [
    { "name": "Dana Lee", "email": "dana@acme.com", "role": "signer", "order": 1 }
  ],
  "fields": [ ... ],
  "options": { "reminders": [2, 5, 9], "expires_in_days": 14 }
}

You get back an envelope ID and a per-signer signing session you can use to bring the signer into the flow. Two rules to internalize up front:

  • Create envelopes server-side only. Your API key can spend credits and create binding requests — it never belongs in browser code. The browser only ever gets a single scoped signing session.
  • A credit is consumed on send, not on completion. Create the envelope when the signer is actually ready, not speculatively on page load. We cover the billing implications in bulk send; the same rule governs API sends.

Placing fields without a mouse

The hosted editor places fields by dragging. In code you have two cleaner options:

  1. Start from a template. Place the fields once in the UI, then reference the template ID in your API call. Every envelope inherits the layout and routing. Best when the document is stable.
  2. Use field tags. Embed markers like {{signature}} and {{text:Job Title}} in the PDF your system generates. On upload, the field-tag API reads the text layer and places real fields exactly where the markers sit. Best when your software generates the document and the layout varies.

Template-plus-tags is the combination most integrations land on: tags for generated contracts, templates for the standard forms.

Bringing the signer into your app

You don't have to bounce the signer to an external site. With embedded signing, you render the signing widget inside your own page via a JS SDK and iframe, pass whitelabel: true to hide vendor branding, and the signer never leaves your product. The signature is exactly as defensible as a hosted one — same audit trail, same cryptographic seal — because validity comes from intent, consent, and the record, not from which domain rendered the page.

If you're integrating across more than one product, use scoped integration keys — one per surface — so a leaked key is a one-integration rotation, not a company-wide incident.

Closing the loop: don't poll, listen

The most common API mistake is polling GET /envelopes/:id on a timer to see if it's signed yet. Don't. Subscribe to webhooks instead. Your endpoint receives an HTTP POST the instant an event fires — envelope.completed is the one most automations key off. The discipline that keeps webhook consumers correct:

  • Verify the HMAC-SHA-256 signature on every payload, over the raw request body, before you act on it. An unverified endpoint that provisions accounts is a remote-control button for anyone who finds the URL.
  • Be idempotent. Retries mean you will see duplicate deliveries. Record processed event IDs and make handling the same event twice a no-op.
  • Respond 2xx fast, then do slow work asynchronously, so you don't trip delivery timeouts.

For the long tail of internal glue, the webhooks are Zapier-compatible — non-engineers can wire "on completed, do X" without a deploy.

A minimal end-to-end integration

The smallest real integration is four steps:

  1. Server-side, POST /api/envelopes from a template when the user reaches the signing step.
  2. Render the embedded widget with the returned signing session.
  3. The user signs in your UI.
  4. Your envelope.completed webhook handler verifies the HMAC, pulls the signed PDF and audit certificate, and advances your workflow.

That's the whole pattern. Everything else — bulk operations, multi-party routing, reminder cadences — is configuration layered on top of those same primitives.

The takeaway

A good e-signature API lets your software treat signing as just another step in a flow you control: create the envelope in code, place fields from templates or tags, sign inside your own UI, and react over a verified webhook. Keep the key on the server, listen instead of polling, and make your handlers idempotent — and the signatures that come back carry exactly the same court-ready evidence as any signed by hand.