permissio

Official Python SDK for the Permissio Partner API. Build document-signing workflows directly into your product.

Installation

pip install permissio

Requires Python 3.9+ and httpx.

Quick start

from permissio import Permissio

client = Permissio(api_key="sk_live_…")  # or sk_test_… for sandbox

# 1. Upload a template PDF
result = client.templates.get_upload_url()
import httpx
httpx.put(
    result["upload_url"],
    content=open("nda.pdf", "rb").read(),
    headers={"Content-Type": "application/pdf"},
)

# 2. Create a template
template = client.templates.create(
    name="NDA — Mutual Confidentiality Agreement",
    document_url=result["object_path"],
    recipients=[
        {"role_name": "Disclosing Party", "signing_order": 1},
        {"role_name": "Receiving Party",  "signing_order": 2},
    ],
    variables=[
        {"name": "effective_date", "type": "date",   "required": True},
        {"name": "party_a_name",   "type": "string", "required": True},
    ],
)

# 3. Create an envelope (draft)
envelope = client.envelopes.create(
    template_id=template["id"],
    title="NDA — Acme Corp",
    signers=[
        {"role_name": "Disclosing Party", "email": "alice@example.com", "name": "Alice Nguyen"},
        {"role_name": "Receiving Party",  "email": "bob@example.com",   "name": "Bob Smith"},
    ],
    variables={
        "effective_date": "2026-05-04",
        "party_a_name": "Smartshares Limited",
    },
    expires_in_days=14,
)

# 4. Send it — dispatches signer invite emails
client.envelopes.send(envelope["id"])

# 5. Check status
detail = client.envelopes.get(envelope["id"])
print(detail["status"])  # "sent", "in_progress", "completed", …

# 6. Download the executed PDF when complete
if detail["status"] == "completed":
    response = client.envelopes.get_signed_document(envelope["id"])
    with open("signed.pdf", "wb") as f:
        f.write(response.content)

Async client

import asyncio
from permissio import AsyncPermissio

async def main():
    async with AsyncPermissio(api_key="sk_live_…") as client:
        envelope = await client.envelopes.create(
            template_id="tpl_…",
            signers=[{"role_name": "Signer", "email": "a@b.com", "name": "Alice"}],
        )
        await client.envelopes.send(envelope["id"])

asyncio.run(main())

Client options

client = Permissio(
    api_key="sk_live_…",                        # required
    base_url="https://app.permissio.us/api",    # optional — default shown
    timeout=30.0,                               # optional — seconds, default 30
    http_client=httpx.Client(...),              # optional — custom httpx client
)

Error handling

All API errors are raised as PermissioApiError:

from permissio import Permissio, PermissioApiError

try:
    client.envelopes.send("env_…")
except PermissioApiError as err:
    print(err.code)       # e.g. "invalid_state"
    print(err.status)     # HTTP status, e.g. 409
    print(err.request_id) # include in support tickets
    print(err.details)    # additional structured info

Common error codes

Idempotency

Write operations auto-generate a UUID as the Idempotency-Key header. Override to replay a specific request:

import uuid
key = str(uuid.uuid4())
envelope = client.envelopes.create(template_id="tpl_…", signers=[…], idempotency_key=key)
# Safe to retry with the same key — server returns the same envelope:
envelope2 = client.envelopes.create(template_id="tpl_…", signers=[…], idempotency_key=key)
assert envelope["id"] == envelope2["id"]

Webhooks

from flask import Flask, request, abort
from permissio.namespaces import WebhooksNamespace

app = Flask(__name__)

@app.post("/webhooks/permissio")
def handle_webhook():
    if not WebhooksNamespace.verify_signature(
        request.data,
        request.headers.get("Permissio-Signature", ""),
        ENDPOINT_SECRET,
    ):
        abort(400)
    event = request.json
    if event["type"] == "envelope.completed":
        print(f"Envelope {event['data']['envelope']['id']} completed!")
    return "", 200

Namespaces

Resources

• Full API reference
• Changelog
• Versioning & deprecation policy
• PyPI package