Skip to main content

​
Signatures API

API endpoints for DigiSigner digital signature workflows, including signature requests, status tracking, and webhook handling. Base Path: /api (signature endpoints in main routes)
Code Reference: app/services/signature_service.py, app/api/routes.py (signature endpoints)

​
Signature Requests

​
Request Document Signature

Request signatures for a document via DigiSigner. Request Body: 
{
  "signers": [
    {
      "email": "signer1@example.com",
      "name": "John Doe",
      "role": "Borrower"
    },
    {
      "email": "signer2@example.com",
      "name": "Jane Smith",
      "role": "Lender"
    }
  ],
  "subject": "Please sign the credit agreement",
  "message": "Please review and sign the attached credit agreement",
  "expires_in_days": 30,
  "urgency": "standard"
}
Response: 
{
  "signature_id": 123,
  "signature_request_id": "req_abc123",
  "digisigner_request_id": "req_abc123",
  "digisigner_document_id": "doc_xyz789",
  "status": "pending",
  "signers": [
    {
      "email": "signer1@example.com",
      "name": "John Doe",
      "role": "Borrower",
      "status": "pending"
    },
    {
      "email": "signer2@example.com",
      "name": "Jane Smith",
      "role": "Lender",
      "status": "pending"
    }
  ],
  "requested_at": "2026-01-15T10:00:00Z",
  "expires_at": "2026-12-31T23:59:59Z"
}
Code Reference: app/api/routes.py (request_document_signature)

​
Signature Status

​
Get Document Signatures

Get all signature requests for a document. Response: 
{
  "signatures": [
    {
      "signature_id": 123,
      "signature_request_id": "req_abc123",
      "status": "completed",
      "signers": [...],
      "completed_at": "2026-01-15T11:00:00Z"
    }
  ]
}

​
Get Signature Details

Get detailed information about a specific signature request. Response: Complete signature request details including signer status

​
Signed Documents

​
Download Signed Document

Download the signed document. Response: File download (PDF) Code Reference: app/api/routes.py (download_signed_document)

​
Webhook Endpoint

​
DigiSigner Webhook

DigiSigner webhook endpoint for signature status updates. Events Handled:
  • DOCUMENT_SIGNED: Individual signer signed
  • SIGNATURE_REQUEST_COMPLETED: All signers completed
Request Body (DOCUMENT_SIGNED): 
{
  "event_time": 1435228059867,
  "event_type": "DOCUMENT_SIGNED",
  "document_id": "5be88823-3ff5-4ec4-8175-459dee50f7fb",
  "signer_email": "signer@example.com"
}
Request Body (SIGNATURE_REQUEST_COMPLETED): 
{
  "event_time": 1435228059868,
  "event_type": "SIGNATURE_REQUEST_COMPLETED",
  "signature_request": {
    "signature_request_id": "req_abc123",
    "is_completed": true,
    "documents": [...]
  }
}
Response: 
DIGISIGNER_EVENT_ACCEPTED
Code Reference: app/api/routes.py (digisigner_webhook)

​
Signature Status Values

  • pending: Signature request created, awaiting signers
  • in_progress: Some signers have signed, others pending
  • completed: All signers have completed signing
  • declined: One or more signers declined to sign
  • expired: Signature request expired
Code Reference: app/db/models.py (DocumentSignature model)

​
Error Responses

​
400 Bad Request

  • Invalid signer email addresses
  • Missing required fields
  • Document file not found

​
404 Not Found

  • Document not found
  • Signature request not found

​
500 Internal Server Error

  • DigiSigner API error
  • Document upload failure
  • Webhook processing error

​
Configuration

​
Environment Variables

​
DIGISIGNER_API_KEY
string
DigiSigner API key
​
DIGISIGNER_BASE_URL
string
DigiSigner API base URL. Default: https://api.digisigner.com/v1
​
DIGISIGNER_WEBHOOK_SECRET
string
Webhook secret for signature verification (optional but recommended)
Setup Guide: See DigiSigner Setup Guide

​
Webhook Security

For production, implement webhook signature verification:
  1. Get webhook secret from DigiSigner account settings
  2. Implement HMAC signature verification
  3. Compare signature in X-DigiSigner-Signature header
  4. Reject requests with invalid signatures
Note: Current implementation accepts all webhooks. Signature verification should be added for production.

​
Additional Resources

Last Updated: 2026-01-14
Code Reference: app/services/signature_service.py, app/api/routes.py