E-signature API with real-time webhooks
The Dastawez e-signature API lets your software upload PDFs, send signature requests, and download sealed documents, through the same REST API the Dastawez dashboard uses. Real-time webhooks tell your system the moment a recipient views, signs, approves, or declines.
It is a document signing API built for Pakistan, for HR systems, lenders, and the software houses that build for them.
What your software can do through the API
Anything the dashboard can do with a signature request, your own system can do too:
- upload PDFs, and join several into one document;
- create a signature request and send it in one call;
- send from a saved template, or in bulk from a spreadsheet;
- track every request, send reminders, and cancel;
- read the full audit trail of a request;
- download the original and the sealed PDF, through links that expire after 5 minutes;
- look up a sealed document's public record through the verification endpoint, to compare it with a copy you hold.
Create and send a signature request in one call
This call creates a request for one candidate, places a signature field on the first page, and sends it straight away. The document was uploaded beforehand, and document_ids names it.
curl https://api.dastawez.pk/v1/signature-requests \
-H "Authorization: Bearer $DASTAWEZ_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"title": "Offer letter, Ali Raza",
"document_ids": ["doc_3f2a6c1e9b8d4f7a8c5e2d1b0a9f8e7d"],
"recipients": [
{"key": "candidate", "name": "Ali Raza", "email": "ali.raza@example.com"}
],
"fields": [
{"recipient": "candidate", "type": "signature", "page": 1,
"x": 0.1, "y": 0.8, "w": 0.3, "h": 0.06}
],
"send": true
}' Each recipient has a key of your choosing, and each field names the recipient who fills it. Field positions and sizes are fractions of the page, measured from its top-left corner, so they do not depend on the PDF's units. Leave out "send": true and the request stays a draft until you send it.
API keys and permissions
Owners and admins create keys in Settings. Each key carries only the permissions you give it:
requests:read, to read signature requests;requests:write, to create and send them;webhooks:manage, to manage webhooks.
A key is shown once, when it is made. Dastawez stores only a hash of it, so a lost key cannot be recovered; you revoke it and make another. Send the key in the Authorization header as a bearer token, from your own server only, never from code that runs on your customers' devices.
Test mode
Every organization has a test mode beside its live one. Test keys are free. Their requests go through the whole flow, sealing included, but nobody is emailed, no credits are used, and every page of the PDF is marked "TEST — not a signed document". Test requests and test webhooks are kept apart from live ones, so you can build against the real API without touching real data.
E-signature webhooks for each step
Instead of asking the API over and over whether something has changed, add a webhook endpoint and Dastawez calls your system as each step happens. These are the events:
- signature_request.sent
- Sent when a request goes out to its recipients.
- recipient.viewed
- Sent when a recipient opens their signing link.
- recipient.signed
- Sent when a signer finishes signing.
- recipient.approved
- Sent when an approver approves.
- recipient.declined
- Sent when a recipient declines, which ends the request.
- signature_request.completed
- Sent when everyone has finished and the sealed PDF is ready.
- signature_request.cancelled
- Sent when the sender cancels the request.
- signature_request.expired
- Sent when the deadline passes before everyone has finished.
Each delivery describes the request as it stands at that moment, so your system rarely needs a second call.
Webhook reliability
- Signed deliveries. Every delivery carries a
Dastawez-Signatureheader, an HMAC-SHA256 signature made with your endpoint's own secret, so your system can check that it came from Dastawez. - Automatic retries. If your endpoint is down or answers with an error, Dastawez tries again, 10 tries in all over about 24 hours.
- A delivery log. Each endpoint has a log of every delivery and its answer, with one-click resend.
- Test events. Send a test event to a new endpoint to see your receiver work before real traffic arrives.
- Secret rotation. Replace an endpoint's secret whenever you need to. Secrets are stored encrypted and shown only once.
- Safe addresses. Endpoints must be public HTTPS addresses.
Safe retries and clear errors
- Idempotency keys. Send an
Idempotency-Keyheader with any call that creates or sends, and a retried call never acts twice. - Rate limits you can see. Every response states your limit in its headers: 300 calls a minute for a live key, 100 for a test key.
- One error format. Every error has the same shape: an
errorobject with a stable, namedcode, a readablemessage, thefieldit concerns, and arequest_idto quote if you need help.
How to start, in three steps
- Sign up and create a test key. Make a free account, then create a test key in Settings.
- Build in test mode. Upload a PDF, send a request, sign it from the test signing link, and receive your webhooks, without emailing anyone or spending a credit.
- Switch to a live key. When everything works, create a live key and replace the test one. Live requests email your recipients and use credits.
Coming soon
- Coming soon
Embedded signing
For API customers, signing inside your own app or website, without leaving it.
Documentation
- The Dastawez API reference, with every endpoint, field, and error code
API questions and answers
Is there a test mode?
Yes, and it costs nothing. A test key creates test requests that email nobody, use no credits, and carry "TEST — not a signed document" on every page. Test data never mixes with live data.
What are the rate limits?
300 calls a minute for a live key and 100 for a test key. Every response states your limit, what remains, and when it resets, in the X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. A 429 response says how long to wait in Retry-After.
How do idempotency keys work?
Send a unique Idempotency-Key header with a call that creates or sends something. If the same key arrives again within 24 hours, Dastawez returns the first answer instead of acting twice, so retrying after a timeout never sends a request twice.
How do I know a webhook came from Dastawez?
Every delivery is signed with HMAC-SHA256, using your endpoint's own secret, in the Dastawez-Signature header. Check it before trusting the body.
How is API use priced?
Requests sent through the API use the same credits as the dashboard, one for each completed signature request, and test keys are free.
For high volumes, talk to us at dastawez.official@gmail.com.