# How to add e-signature to an app

Call an API to create the document, let the signer use a hosted page, listen for a webhook, and store the sealed file. You can do that in an afternoon. Don't build the signing page yourself, because the evidence is the hard part.

## Build or buy

Drawing a signature on a canvas takes an hour. The product is everything around it: consent, a log nobody can edit, a seal, delivery, and being able to explain it all in five years. Our view is that most apps should rent this and spend their time on what makes them different.

## The five steps

**1. Create.** Your backend sends the PDF and signers. Keep the key on your server, never in browser code.

```
curl https://docuinked.com/v1/documents \
  -H "Authorization: Bearer $DOCUINKED_API_KEY" \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{"title": "Order 1042", "pdf_url": "https://example.com/1042.pdf",
       "signers": [{"name": "Dana Reed", "email": "dana@example.com"}],
       "metadata": {"order": "1042"}}'
```

**2. Place the fields.** You have three ways. Tags such as `{{signature:1}}` in the PDF are the best for templates you control. Anchors find text such as `Signature:`. Coordinates are fractions of the page. If you give none, fields go on the document's own Signature, Date and Name lines; with no such lines, each signer gets a field on the last page.

**3. Send.** Call `send_document`. The signer gets an email with their own link. If you want signing inside your own app, your server can call `create_signing_link` for a sent document and show it to the right user. Treat that link like a password.

**4. Listen.** Add a [webhook](/docs/webhooks) and verify the signature. Update your record on `document.completed`.

**5. Store.** Fetch the signed PDF and the evidence, and keep both. Don't count on any vendor, us included, being there in ten years.

## Mistakes to avoid

- **Retries with no idempotency key.** This is how people get two contracts.
- **Polling for status.** Use webhooks.
- **A shared link for several signers.** Each signer needs their own, or your evidence means little.
- **Blocking the signer's copy.** Everyone needs to be able to keep the record.
- **Calling your flow legally safe.** Check your documents with a lawyer.

## Test it first

Use a [test key](/docs/test-mode) so no email goes out. `sign@test.docuinked.com` signs by itself, so your whole flow can run in a CI job.

## Common questions

### Can users sign inside my app without leaving it?

Your server can create a signing link and send the user to it. The page itself is ours and can't be framed, because the signing step has to be the same trusted page for everyone.

### How long does an integration take?

The calls above are a small job. Plan more time for your own edge cases: declined documents, expired links and changed terms. Those are what take the time.

### Do my users need a docuinked account?

No. Signers never need an account. Only the people who run your integration do.