# Document Signing API

The Document Signing API enables you to create, manage, and track electronic signature workflows for your documents.

## Base URL

```
https://api.zaits.net/v1/signing
```

## Authentication

All requests require your API key in the Authorization header:

```http
Authorization: Bearer YOUR_API_KEY
```

***

## Create Document

Create a new document for electronic signatures.

### Endpoint

```http
POST /v1/signing/documents
```

### Parameters

| Parameter     | Type   | Required | Description                  |
| ------------- | ------ | -------- | ---------------------------- |
| `document`    | file   | Yes      | PDF document to be signed    |
| `title`       | string | Yes      | Document title               |
| `description` | string | No       | Document description         |
| `signers`     | array  | Yes      | List of signers              |
| `message`     | string | No       | Custom message for signers   |
| `expiry_date` | string | No       | Expiration date (YYYY-MM-DD) |

### Signer Object Structure

```json
{
  "email": "john@example.com",
  "name": "John Doe",
  "role": "signer",
  "order": 1
}
```

### Request Example

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST https://api.zaits.net/v1/signing/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "document=@contract.pdf" \
  -F "title=Service Agreement 2025" \
  -F "description=Annual service agreement" \
  -F 'signers=[{"email":"john@example.com","name":"John Doe","role":"signer","order":1}]' \
  -F "message=Please review and sign the attached service agreement." \
  -F "expiry_date=2025-12-31"
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const formData = new FormData();
formData.append("document", pdfFile);
formData.append("title", "Service Agreement 2025");
formData.append("description", "Annual service agreement");
formData.append(
  "signers",
  JSON.stringify([
    {
      email: "john@example.com",
      name: "John Doe",
      role: "signer",
      order: 1,
    },
  ])
);
formData.append(
  "message",
  "Please review and sign the attached service agreement."
);
formData.append("expiry_date", "2025-12-31");

const response = await fetch("https://api.zaits.net/v1/signing/documents", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
  },
  body: formData,
});

const result = await response.json();
```

{% endtab %}

{% tab title="Python" %}

```python
import requests
import json

files = {'document': open('contract.pdf', 'rb')}
data = {
    'title': 'Service Agreement 2025',
    'description': 'Annual service agreement',
    'signers': json.dumps([
        {
            'email': 'john@example.com',
            'name': 'John Doe',
            'role': 'signer',
            'order': 1
        }
    ]),
    'message': 'Please review and sign the attached service agreement.',
    'expiry_date': '2025-12-31'
}

response = requests.post(
    'https://api.zaits.net/v1/signing/documents',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    files=files,
    data=data
)

result = response.json()
```

{% endtab %}
{% endtabs %}

### Response

```json
{
  "success": true,
  "data": {
    "document_id": "doc_abc123xyz",
    "title": "Service Agreement 2025",
    "description": "Annual service agreement",
    "status": "draft",
    "created_at": "2024-01-15T10:30:00Z",
    "expiry_date": "2025-12-31T23:59:59Z",
    "signers": [
      {
        "id": "signer_xyz789",
        "email": "john@example.com",
        "name": "John Doe",
        "role": "signer",
        "order": 1,
        "status": "pending"
      }
    ],
    "file": {
      "name": "contract.pdf",
      "size": 245678,
      "pages": 5
    },
    "signing_url": "https://sign.zaits.net/doc/abc123xyz"
  }
}
```

***

## Send Invitations

Send signing invitations to all signers via email.

### Endpoint

```http
POST /v1/signing/documents/{document_id}/send-invitations
```

### Parameters

| Parameter        | Type   | Required | Description                         |
| ---------------- | ------ | -------- | ----------------------------------- |
| `reminder_days`  | number | No       | Days between reminders (default: 3) |
| `custom_message` | string | No       | Additional message for email        |

### Request Example

```bash
curl -X POST https://api.zaits.net/v1/signing/documents/doc_abc123xyz/send-invitations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reminder_days": 3,
    "custom_message": "Please sign at your earliest convenience."
  }'
```

### Response

```json
{
  "success": true,
  "data": {
    "invitations_sent": 1,
    "document_status": "sent",
    "sent_at": "2024-01-15T10:35:00Z",
    "signers_notified": [
      {
        "email": "john@example.com",
        "status": "sent",
        "sent_at": "2024-01-15T10:35:00Z"
      }
    ]
  }
}
```

***

## Get Document Status

Retrieve document details and signing status.

### Endpoint

```http
GET /v1/signing/documents/{document_id}
```

### Request Example

```bash
curl -X GET https://api.zaits.net/v1/signing/documents/doc_abc123xyz \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response

```json
{
  "success": true,
  "data": {
    "document_id": "doc_abc123xyz",
    "title": "Service Agreement 2025",
    "status": "partially_signed",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T14:30:00Z",
    "expiry_date": "2025-12-31T23:59:59Z",
    "signers": [
      {
        "id": "signer_xyz789",
        "name": "John Doe",
        "email": "john@example.com",
        "status": "signed",
        "signed_at": "2024-01-15T14:30:00Z",
        "ip_address": "192.168.1.1",
        "signature_id": "sig_abc123"
      },
      {
        "id": "signer_def456",
        "name": "Jane Smith",
        "email": "jane@example.com",
        "status": "pending",
        "reminder_sent_at": "2024-01-18T10:00:00Z"
      }
    ],
    "audit_trail": [
      {
        "event": "document_created",
        "timestamp": "2024-01-15T10:30:00Z",
        "user": "API User"
      },
      {
        "event": "invitations_sent",
        "timestamp": "2024-01-15T10:35:00Z",
        "recipients": ["john@example.com", "jane@example.com"]
      },
      {
        "event": "document_signed",
        "timestamp": "2024-01-15T14:30:00Z",
        "signer": "john@example.com"
      }
    ]
  }
}
```

***

## List Documents

Get a list of all your signing documents.

### Endpoint

```http
GET /v1/signing/documents
```

### Query Parameters

| Parameter  | Type   | Description                                            |
| ---------- | ------ | ------------------------------------------------------ |
| `status`   | string | Filter by status: `draft`, `sent`, `signed`, `expired` |
| `page`     | number | Page number (default: 1)                               |
| `per_page` | number | Items per page (default: 25, max: 100)                 |
| `sort`     | string | Sort by: `created_at`, `updated_at`, `title`           |
| `order`    | string | Sort order: `asc`, `desc`                              |

### Request Example

```bash
curl -X GET "https://api.zaits.net/v1/signing/documents?status=sent&page=1&per_page=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response

```json
{
  "success": true,
  "data": {
    "documents": [
      {
        "document_id": "doc_abc123xyz",
        "title": "Service Agreement 2025",
        "status": "sent",
        "created_at": "2024-01-15T10:30:00Z",
        "signers_count": 2,
        "signed_count": 0
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 10,
      "total": 45,
      "total_pages": 5
    }
  }
}
```

***

## Finalize Document

Finalize a signed document and lock it from further changes.

### Endpoint

```http
POST /v1/signing/documents/{document_id}/finalize
```

### Request Example

```bash
curl -X POST https://api.zaits.net/v1/signing/documents/doc_abc123xyz/finalize \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response

```json
{
  "success": true,
  "data": {
    "document_id": "doc_abc123xyz",
    "status": "completed",
    "finalized_at": "2024-01-16T10:00:00Z",
    "download_url": "https://api.zaits.net/v1/signing/documents/doc_abc123xyz/download",
    "certificate_url": "https://api.zaits.net/v1/signing/documents/doc_abc123xyz/certificate"
  }
}
```

***

## Download Signed Document

Download the completed signed document.

### Endpoint

```http
GET /v1/signing/documents/{document_id}/download
```

### Query Parameters

| Parameter | Type   | Description                              |
| --------- | ------ | ---------------------------------------- |
| `format`  | string | Download format: `pdf`, `pdf_with_audit` |

### Request Example

```bash
curl -X GET "https://api.zaits.net/v1/signing/documents/doc_abc123xyz/download?format=pdf_with_audit" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o signed_document.pdf
```

### Response

Binary PDF file download

***

## Delete Document

Delete a signing document and all associated data.

### Endpoint

```http
DELETE /v1/signing/documents/{document_id}
```

### Request Example

```bash
curl -X DELETE https://api.zaits.net/v1/signing/documents/doc_abc123xyz \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response

```json
{
  "success": true,
  "data": {
    "message": "Document deleted successfully",
    "document_id": "doc_abc123xyz"
  }
}
```

***

## Public Preview

Get a public preview link for the document (no signature capability).

### Endpoint

```http
GET /v1/signing/documents/{document_id}/public-preview
```

### Request Example

```bash
curl -X GET https://api.zaits.net/v1/signing/documents/doc_abc123xyz/public-preview \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response

```json
{
  "success": true,
  "data": {
    "preview_url": "https://sign.zaits.net/preview/abc123xyz",
    "expires_at": "2024-01-20T10:00:00Z"
  }
}
```

***

## Document Statuses

| Status             | Description                        |
| ------------------ | ---------------------------------- |
| `draft`            | Document created but not sent      |
| `sent`             | Invitations sent to signers        |
| `partially_signed` | Some signers have signed           |
| `signed`           | All signers have signed            |
| `completed`        | Document finalized and locked      |
| `expired`          | Document expired before completion |
| `cancelled`        | Document cancelled by owner        |

## Error Responses

### Common Errors

| Error Code           | HTTP Status | Description                          |
| -------------------- | ----------- | ------------------------------------ |
| `document_not_found` | 404         | Document ID doesn't exist            |
| `document_expired`   | 400         | Document has expired                 |
| `already_signed`     | 400         | Document already signed by this user |
| `invalid_signer`     | 400         | Signer email not valid               |
| `document_locked`    | 400         | Document is finalized and locked     |
| `pdf_corrupted`      | 400         | PDF file is corrupted or invalid     |

### Error Response Format

```json
{
  "success": false,
  "error": {
    "code": "document_expired",
    "message": "This document has expired and can no longer be signed",
    "details": {
      "document_id": "doc_abc123xyz",
      "expired_at": "2024-12-31T23:59:59Z"
    }
  }
}
```

## Best Practices

### Document Security

* Documents are encrypted at rest
* Audit trail maintains complete signing history
* IP addresses and timestamps recorded for compliance
* Signed documents include tamper-evident seal

### Workflow Tips

* Set appropriate expiry dates for time-sensitive documents
* Use reminder\_days to automate follow-ups
* Include clear descriptions for better organization
* Test thoroughly before production deployment

***

**Next:** [Webhook API Documentation](/api/api-reference/webhooks.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://zaits.gitbook.io/api/api-reference/document-signing.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.