API Reference

Complete reference for the zSign REST API. Send documents, manage signing sessions, and integrate webhooks.

Base URL

https://api.zsign.io/api

Authentication

Bearer YOUR_API_KEY

Health & Status

API status and health check endpoints

GET

Check API Status

/

Verify the API is running.

Request

curl https://api.zsign.io/api

Response 200

API is running

{
  "message": "zSign API is running"
}

GET

Health Check

/health

Get detailed health status of the API.

Request

curl https://api.zsign.io/api/health

Response 200

Health status

{
  "status": "healthy"
}

Documents

Upload, send, and manage documents

GET

List Documents

/api/documents

Auth required

Retrieve documents with optional filtering.

Query Parameters

Name	Type	Description
`offset`	integer= 0	Pagination offset
`limit`	integer= 20	Items per page
`status`	string	Filter by status
`recipient`	string	Filter by recipient email

Request

curl -X GET "https://api.zsign.io/api/documents?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

List of documents

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Contract.pdf",
      "status": "pending",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 1,
  "offset": 0,
  "limit": 20
}

POST

Upload and Send Document

/api/documents/send

Auth required

Upload a PDF and send it for signing in one request. PDFs must include field annotations using {type:party:name} syntax (e.g., {signature:user}, {text:user:name}). Add * after type for required fields: {type*:party:name}. Supported types: signature, text, date, initials.

Request Body

Content-Type: multipart/form-data

Fields

Name	Type	Description
`file`required	file	PDF file to upload
`recipients`required	string	JSON array of recipients
`name`	string	Document name

Example

[
  {
    "email": "john@example.com",
    "name": "John Doe",
    "role": "Signer"
  }
]

Request

curl -X POST https://api.zsign.io/api/documents/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@contract.pdf" \
  -F 'recipients=[{"email":"john@example.com","name":"John Doe","role":"Signer"}]'

Response 201

Document sent successfully

{
  "document_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_id": "660e8400-e29b-41d4-a716-446655440000",
  "signing_urls": [
    {
      "recipient_email": "john@example.com",
      "signing_url": "https://app.zsign.io/sign/eyJ..."
    }
  ]
}

### PDF Field Annotation Requirements **Sample LLM prompt to format PDF documents with correct annotation syntax:** ``` Create a fillable PDF document with embedded form field annotations. The form fields must follow these specifications: ## Field Naming Syntax: {type:party:name} Format: `{type:party:name}` or `{type*:party:name}` for required fields **Field Types:** - `signature` - Signature field - `text` - Text input field - `date` - Date field - `initials` - Initials field **Components:** 1. **Type**: text, date, signature, or initials 2. **Party**: The role/party who fills it (e.g., user, borrower, employee, manager, landlord, tenant) 3. **Name**: Field identifier (e.g., name, email, address, company_name) **Required Fields:** Add `*` after the type to make a field required: - `{text*:user:name}` - Required text field - `{signature*:user}` - Required signature **Examples:** - `{text:user:full_name}` - `{text*:user:email}` - `{date:user:birthdate}` - `{signature:user}` - `{initials:user}` - `{text*:borrower:company_name}` - `{signature*:landlord}` ## Critical Technical Requirements The field name MUST be set directly on each widget annotation's `/T` attribute, NOT only in a parent AcroForm field object. Many PDF signing services read the `/T` value directly from page annotations. **Each annotation must have:** - `/Type`: `/Annot` - `/Subtype`: `/Widget` - `/FT`: `/Tx` (for text fields) - `/T`: The field name in `{type:party:name}` format (THIS IS CRITICAL) - `/F`: `4` (print flag) - `/Rect`: `[left, bottom, right, top]` coordinates ``` **Sample PDF:** [Download simple_contract_1.pdf](https://storage.googleapis.com/zsign-public/simple_contract_1.pdf)

Signing Sessions

Create and manage signing sessions

POST

Create Session

/api/sessions

Auth required

Create a new signing session.

Request Body

Content-Type: application/json

Fields

Name	Type	Description
`document_id`required	UUID	Document to sign
`document_type`required	string	template or one_off
`recipients`required	array	List of recipients

Example

{
  "document_id": "550e8400-e29b-41d4-a716-446655440000",
  "document_type": "one_off",
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "role": "Signer",
      "signing_order": 1
    }
  ]
}

Request

curl -X POST https://api.zsign.io/api/sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document_id": "550e8400-e29b-41d4-a716-446655440000",
    "document_type": "one_off",
    "recipients": [{
      "name": "John Doe",
      "email": "john@example.com",
      "role": "Signer",
      "signing_order": 1
    }]
  }'

Response 201

Session created

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "expires_at": "2024-02-14T10:30:00Z",
  "recipients": [
    {
      "recipient_id": "770e8400-e29b-41d4-a716-446655440000",
      "signing_url": "https://app.zsign.io/sign/eyJ..."
    }
  ]
}

GET

Get Session Status

/api/sessions/{session_id}/status

Auth required

Get lightweight session status.

Path Parameters

Name	Type	Description
`session_id`required	UUID	Session identifier

Request

curl -X GET "https://api.zsign.io/api/sessions/{session_id}/status" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

Session status

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "in_progress",
  "progress": {
    "completed": 1,
    "total": 2,
    "percentage": 50
  }
}

Webhooks

Configure webhook endpoints for real-time notifications

POST

Create Webhook

/api/webhooks

Auth required

Create or replace webhook configuration.

Request Body

Content-Type: application/json

Fields

Name	Type	Description
`url`required	string	Webhook endpoint URL (HTTPS)
`events`required	array	List of events to subscribe to

Example

{
  "url": "https://example.com/webhook",
  "events": [
    "document.signed",
    "document.completed"
  ]
}

Request

curl -X POST https://api.zsign.io/api/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhook",
    "events": ["document.signed", "document.completed"]
  }'

Response 201

Webhook created

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "url": "https://example.com/webhook",
  "events": [
    "document.signed",
    "document.completed"
  ],
  "enabled": true,
  "secret": "whsec_..."
}

API Reference

Health & Status

Check API Status

Request

Response 200

Health Check

Request

Response 200

Documents

List Documents

Query Parameters

Request

Response 200

Upload and Send Document

Request Body

Fields

Request

Response 201

Signing Sessions

Create Session

Request Body

Fields

Request

Response 201

Get Session Status

Path Parameters

Request

Response 200

Webhooks

Create Webhook

Request Body

Fields

Request

Response 201

Need Help?

Documentation

Email Support

Status Page