How to integrate an e-signature API in your app
Integrating an e-signature API into your own application means deciding where in your product the signing step happens, writing the code that creates and tracks signature requests, and handling the cases where something doesn't go as expected — a signer who never completes their part, an upload that fails, a webhook your server didn't receive in time. This article walks through that integration from a practical, where-do-I-start perspective.
Step 1: decide where signing fits in your flow
Before writing any integration code, map out exactly where in your application a document needs to get signed. Common patterns include: a document generated at the end of a workflow (an order confirmation, a service agreement) that then needs a customer's signature; an onboarding step where a new user or employee needs to sign a policy or contract before continuing; or a background process that periodically needs to send out renewal or compliance documents. Each of these has a different natural trigger point in your code — a button click, a status change, a scheduled job — and getting that trigger right matters more than any API detail.
Step 2: decide whether to embed request management in your app
Signers always complete a document through the standard secure link delivered by email, regardless of how the request was created. What you do get to choose is whether the sending and tracking side lives in Esignapi's own dashboard or inside your own application: Esignapi's embed API lets you render a document and request management panel directly inside your product, authenticated with its own dedicated token. That's worth considering if your own users are the ones sending documents and you don't want them bouncing out to a separate dashboard — it doesn't change anything about how the people who receive and sign documents experience that part. See Embedded signing vs email signing: when to use each for the fuller distinction.
Step 3: build the core request flow
At minimum, your integration needs to: upload the document (or reference one you've already uploaded), create a signature request with the correct signers and fields, and store the resulting request identifier somewhere in your own database so you can look it up later. This last part is easy to skip when you're focused on getting the happy path working, but it's what lets you connect an incoming webhook event back to the right record in your own system.
Step 4: handle the asynchronous part
Signing doesn't happen instantly — a signer might open the link five minutes later, or three days later. Your integration needs a plan for this gap: either polling the request's status periodically, or (more commonly) setting up a webhook endpoint that Esignapi calls when a signer completes a document or the request finishes. See E-signature webhooks explained for what to actually expect from webhook delivery, including an important limitation worth knowing about before you rely on it.
Step 5: plan for the unhappy paths
A production-ready integration accounts for more than the case where everything works:
- A signer never completes their part. Esignapi sends automatic reminders, but your own application may also want to surface this to whoever's waiting on the document internally.
- An upload fails. Check the response status and error message rather than assuming success, and give your own users a clear retry path.
- A webhook doesn't arrive. Since webhook delivery isn't automatically retried if your endpoint is briefly down, build in a periodic reconciliation check — looking up the status of requests you're still waiting on — rather than relying on webhooks as your only source of truth. See Error handling and idempotency in e-signature APIs for more on this.
A minimal integration, conceptually
A bare-bones integration can be three functions: one that uploads a document and returns its ID, one that creates a signature request from that ID plus a signer list, and one that checks a request's current status. Everything else — retry logic, webhook handling, storing request IDs against your own records — is what turns that minimal version into something you'd actually run in production.
Testing your integration before going live
Since there's no separate sandbox environment, the practical way to test an integration end to end is to actually send a real document to an email address you control, walk through the signing flow yourself, and confirm your webhook endpoint (if you're using one) receives and correctly processes the resulting event. See Testing e-signature integrations safely for a fuller testing checklist.
A common mistake: hardcoding assumptions about signer count
It's tempting to write an integration that assumes a fixed number of signers (just the customer, say), and that assumption tends to break the first time a document genuinely needs two or three. Structuring your integration around a list of signers from the start, even if it usually has just one entry, saves a rewrite later when a second signer inevitably comes up — a countersignature from a manager, a co-signer on a lease, a witness.
Keeping your integration in sync with field changes
If the document template you're sending changes — a new clause added, a field repositioned — any hardcoded field coordinates in your integration need to be updated to match, or signers will see misplaced fields on the new version. It's worth treating field positions as something that lives alongside your document templates, not as a one-time setting you configure once and forget.
A reasonable order to build things in
If you're starting from nothing, a practical build order is: get authentication working with a single successful status check, then build the upload-and-create flow with yourself as the only signer, then add real field positioning, then add multiple signers and whatever signing order your documents need, and only then layer in webhook handling and production-grade error handling. Building in roughly that order means each step is verifiable on its own before you add the next layer of complexity on top of it, rather than debugging several new pieces at once when something doesn't work.
Get started
Esignapi's API documentation has the exact request and response formats for every step described here, with working examples to adapt into your own integration.
Frequently asked questions
How long does a typical integration take to build?
For a straightforward single-document, single-signer flow, a basic integration can usually be built in a short amount of developer time, since the core request flow is just a few API calls. Handling webhooks, retries, and edge cases properly is what extends the timeline.
Do I need to build a custom UI for signers, or does Esignapi provide one?
Esignapi provides the signing interface itself, delivered through the signer's unique link, so you don't need to build signature capture, field validation, or document rendering yourself. What you can additionally embed in your own app is the sender-side request management experience, not a separate signer-facing component.
Can I integrate e-signature into a mobile app?
Yes, since the signing experience works through a standard web browser, it can be opened from a mobile app via an in-app browser or an external link. The embeddable management panel can also be rendered within a mobile app's webview if your own users need to send and track requests from inside the app.
What's the biggest mistake teams make when integrating an e-signature API?
Relying solely on webhooks without any fallback reconciliation, and discovering later that a webhook delivery failure silently left their system out of sync with the actual signing status.
Should I store signed documents myself, or just rely on Esignapi to hold them?
That depends on your own retention and compliance requirements — downloading and storing a copy of the final signed document and certificate in your own systems is a reasonable practice if you need guaranteed long-term access independent of any one vendor.