---
title: Send a document for signature from Python
description: Send a document for signature from Python, with a program that was run against Docustay before it was put here.
---

# Send a document for signature from Python

pip install docustay

The package has no dependencies and needs Python 3.9 or newer. Calls are synchronous and return plain dictionaries. Every POST gets an idempotency key made for it and reused on retries. Pass base_url only when you point at a self-hosted install.

```python
import os
from docustay import Docustay

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

It reads DOCUSTAY_API_KEY and DOCUSTAY_TEMPLATE_ID from the environment. Use a test key first: it sends nothing real and bills nothing.

## Install into a virtual environment

Make a virtual environment, activate it, and install the docustay package with pip. It supports Python 3.9 and later and depends only on the standard library plus one HTTP client. Put the key and the template id in environment variables before you run the script; os.environ raises a KeyError if one is missing, which is a clear way to find out.

## What a call returns

The client returns plain dictionaries, so the document you get back is something you can print, log or store as JSON. Errors raise an exception that carries the HTTP status, the error kind and the request id. A repeated send with the same idempotency key returns the original document, which lets a worker retry after a timeout without worrying.

## Verifying webhooks

In a Flask or Django view, read the raw request body before any JSON parsing, then call verify_webhook with the secret, the three headers and the body. It raises if the signature, the body or the timestamp is wrong. Only after that do you look at the event, and a documents.document.executed event is your cue to fetch the signed PDF.

## Questions people ask

**Does a test key send real email?**

No. A test key emails only you, stamps the document TEST and is never counted against your plan.

**Does it work with asyncio?**

The client is synchronous. In an async program run it in a thread with asyncio.to_thread, or call the API with httpx; both work.

**Where do I see the result?**

In Documents in the app, and in the API log under Developers.

## Keep reading

- [Quick start](/docs/quickstart)
- [API reference](/docs/api-reference)
- [Webhooks](/docs/webhooks)
- [SDKs](/developers/sdks)
- [Test mode](/docs/test-mode)
- [Sending](/product/sending)