Python SDK

The insigner-python SDK provides a Pythonic client for the inSigner Cloud API with type hints, automatic pagination, and retry handling.

Installation

pip install insigner

Quick start

from insigner import InSigner

client = InSigner(api_key="isk_YOUR_API_KEY")

# Create and send a document
doc = client.documents.create(
    name="Sales Agreement Q3",
    signing_type="sequential"
)

# Upload PDF
client.documents.upload(doc.id, file_path="./sales-agreement.pdf")

# Add signers
client.documents.add_signer(doc.id,
    email="jane@acme.com",
    name="Jane Smith",
    role="signer",
    order=0
)

# Add signature field
client.documents.add_field(doc.id,
    type="signature",
    label="Client Signature",
    page=1, x=100, y=650,
    width=200, height=60
)

# Send for signing
client.documents.send(doc.id)

Using requests directly

Until the SDK is released, use the REST API with requests:

import requests

INSIGNER_API = "https://app.insigner.co/api/v1"
API_KEY = "isk_YOUR_API_KEY"

def insigner_request(method, path, **kwargs):
    """Convenience wrapper for the inSigner API."""
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    }
    res = requests.request(
        method,
        f"{INSIGNER_API}{path}",
        headers=headers,
        **kwargs
    )
    res.raise_for_status()
    if res.status_code == 204:
        return None
    return res.json()

# List documents
result = insigner_request("GET", "/documents", params={"limit": 10})
for doc in result["data"]:
    print(doc["name"], doc["status"])

# Create a document
doc = insigner_request("POST", "/documents", json={"name": "My Document"})
print(f"Created: {doc['data']['id']}")

Pagination helper

def fetch_all(path, params=None):
    """Fetch all pages from a paginated endpoint."""
    all_items = []
    cursor = None
    params = params or {}

    while True:
        if cursor:
            params["cursor"] = cursor
        result = insigner_request("GET", path, params=params)
        all_items.extend(result["data"])

        if not result["meta"]["hasMore"]:
            break
        cursor = result["meta"]["nextCursor"]

    return all_items

# Get all completed documents
docs = fetch_all("/documents", {"status": "completed", "limit": 100})
print(f"Total completed: {len(docs)}")

Error handling

try:
    result = insigner_request("GET", "/documents/invalid-id")
except requests.HTTPError as e:
    error = e.response.json()
    print(f"Error {error['status']}: {error['detail']}")

    if error["type"] == "https://docs.insigner.com/errors/not-found":
        print("Document not found")
    elif error["type"] == "https://docs.insigner.com/errors/rate-limited":
        retry_after = int(e.response.headers.get("Retry-After", 60))
        print(f"Rate limited. Retry in {retry_after}s")