Tutorial: send a document from Python

This tutorial uses the Python SDK and nothing else, so it runs on any machine with Python 3. The finished program is docustay/examples/python/app.py.

1. What you need

A Docustay test API key, a template id, and Python 3.9 or newer.

pip install docustay
export DOCUSTAY_API_KEY=dsk_test_…
export DOCUSTAY_TEMPLATE_ID=<template id>

2. Send one document

import os
from docustay import Docustay

docustay = Docustay(os.environ["DOCUSTAY_API_KEY"])
doc = docustay.send_document(
    os.environ["DOCUSTAY_TEMPLATE_ID"],
    [{"seat": "signer_1", "name": "Pat Example", "email": "pat@example.com"}],
)
print(doc["id"], doc["state"])

With a test key, Pat is not emailed; the document is made so you can try the whole flow. To see it as the signer, call docustay.test_sign(doc["id"], "signer_1").

3. Wait for the result with a webhook

Polling works but a webhook is better. Docustay signs each delivery; verify_webhook refuses a changed body, a wrong secret and an old timestamp:

from docustay import verify_webhook

event = verify_webhook(secret, headers, raw_body)   # raw_body is the exact text received
if event["topic"] == "documents.document.executed":
    print("signed:", event["subject_id"])

Use the raw body. If you parse the JSON first and serialise it again, the signature will not match.

On your laptop, npx docustay listen --forward-to http://localhost:3000/webhooks forwards real signed events and prints the secret.

4. Download the signed copy

open("signed.pdf", "wb").write(docustay.download_signed_pdf(doc["id"]))

5. Errors and limits

Every failure raises DocustayError with the HTTP status and the message from Docustay. Network failures and 429 answers are retried for you. Pass idempotency_key= to a send if you might call it twice for the same event; the second call returns the first result instead of sending again.

6. Go further

The whole example, with the page that embeds the signing form, is docustay/examples/python/app.py. Swap in a live key only once the test flow works.