API Docs

AI Toolkit

Pricing

$0.25

API Docs

AI Toolkit

Changelog

Pricing

$0.25

All posts
Guides

How to add e-signatures to your app in an afternoon

A step-by-step plan for adding document signing to your product with the SignatureAPI REST API, from a free test key to a signed PDF stored in your own system.

Most products reach a point where a user needs to sign something: an offer letter, a lease, a service agreement, a consent form. The first instinct is often to email a PDF and ask for a scan back. The second is to look at an e-signature API and wonder how long the integration will take.

With SignatureAPI the integration is a handful of HTTP calls. This post walks through the plan we would follow to ship a first version in an afternoon. Every step works with a free test key, so you can build the whole flow before you pay for anything or email a real person.

The model in five nouns

SignatureAPI organizes signing around five concepts. Learning them first saves time later, because every request and every event uses the same words.

ConceptWhat it is
EnvelopeThe container for one signing workflow. It holds documents and recipients.
DocumentA PDF or DOCX file inside the envelope.
RecipientA person who acts on the envelope: a signer, an approver, a preparer, and a few more types.
CeremonyThe guided session where one recipient reviews and signs.
DeliverableThe signed PDF, with an audit log, produced when every recipient has finished.

Places tie these together. A place is an area on a document where a recipient does something, such as a signature, initials or a text input, or where SignatureAPI writes a value for you, such as the completion date.

Hour one: get a test key and send an envelope

Sign up and copy your test API key from the Dashboard. Test keys start with key_test_. If you work from a terminal, npx signatureapi init signs you in and writes the test key into your project’s .env file without printing it.

Test mode is the safe place to build. Test envelopes don’t send email to recipients (you preview the emails in the Dashboard instead), the documents carry a watermark that makes them non-binding, and we don’t bill for them.

Now create an envelope. The request below sends our sample service agreement to one signer. The sample has no placeholder text, so the request positions the signature place with a fixed position: a page number and the distance from the top and left edges of the page. Hour two explains both options.

Terminal
curl -X POST https://api.signatureapi.com/v1/envelopes \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: key_test_xxxxxxxx' \
  -d '{
    "title": "Service Agreement",
    "documents": [
      {
        "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
        "fixed_positions": [
          { "place_key": "client_signature", "page": 1, "top": 152, "left": 190 }
        ],
        "places": [
          { "key": "client_signature", "type": "signature", "recipient_key": "client" }
        ]
      }
    ],
    "recipients": [
      { "key": "client", "type": "signer", "name": "Jane Doe", "email": "jane@example.com" }
    ]
  }'

The response is the envelope, with an id (a UUID) and a status of processing. Open the envelope in the Dashboard, find the email that would have gone to Jane, and click through to sign as her. That is the full signer experience your users will see.

Hour two: decide where signatures go

You have two ways to position places, and the choice depends on who owns the document.

Placeholders are text strings like [[signer_signs_here]] inside the document. They suit documents you generate or control, because the position moves with the text when the layout changes. Set the placeholder text color to white and recipients won’t see it.

Fixed positions are coordinates: a page number plus the distance from the top and left edges in points (1/72 of an inch). They suit documents you receive from elsewhere and can’t edit.

If your documents start life as Word files, look at document templates. You put {{field}} tags in a DOCX file, send the values in the data property, and SignatureAPI merges them before signing. One template can then produce every offer letter or order form you send.

Hour three: listen for events

Polling works for a demo, but production code should react to events. Register a webhook endpoint in the Dashboard and pick the events you care about. For a first version, two are enough:

  • envelope.completed fires when every recipient has finished.
  • deliverable.generated fires when the signed PDF is ready. Its payload carries a download link that expires after an hour.

Every webhook request carries an HMAC signature in the webhook-signature header, following the Standard Webhooks specification. Verify it with the Standard Webhooks library for your language before you trust the payload. Deliveries can arrive out of order, and failed deliveries are retried for up to 48 hours, so make your handler safe to run twice for the same event.

To test locally, npx signatureapi listen forwards test-mode events to a handler on your machine and saves the endpoint’s signing secret into your .env file.

Put your own identifiers in the envelope’s metadata (up to 10 key-value pairs). The metadata comes back in every webhook payload as envelope_metadata, so your handler can find the matching order, user or contract without a lookup table.

Hour four: keep users in your app

By default, SignatureAPI emails each recipient a link to their ceremony. That is the right choice when the signer is outside your product. When the signer is already logged into your app, you can embed the ceremony instead.

Create the recipient with custom authentication, which tells SignatureAPI that your app already knows who the user is. Set ceremony.embeddable_in to your app’s origin. The response then includes a ceremony URL. Load it in an iframe with embedded=true&event_delivery=message appended, and listen for ceremony.completed messages from https://sign.signatureapi.com. On mobile, the same URL works in a WebView or WKWebView with no extra dependencies.

Keep the API key on your server. The browser only ever sees the ceremony URL.

Before you go live

Switching to a live key (key_live_) is the only code change. Before you do, check a few things:

  • Register your webhook endpoints again for live mode. Test and live endpoints are separate.
  • Add a sender with your team’s address, so replies to signing emails reach you.
  • Decide whether you want envelope branding: your logo and accent color on the ceremony and the emails.
  • Store the deliverable in your own system when deliverable.generated arrives. It is your record of the signature.

The quickstart covers the first envelope in more detail, and the webhooks guide has the verification libraries for each language.

START FOR FREE

Ready to get started?
Create an account instantly, no credit card required.

Get Started