Developer Documentation

Introduction

The PaperSignMan API allows you to integrate our digital document signing capabilities into your own applications. With our API, you can:

• Upload and manage documents
• Create and use templates
• Send documents for signature
• Track document status
• Manage users and teams

Our API follows RESTful principles and uses standard HTTP methods. All responses are returned in JSON format.

Authentication

The PaperSignMan API uses API keys for authentication. You can generate an API key from your account dashboard.

Include your API key in the request header:

Authorization: Bearer YOUR_API_KEY

Rate Limits

To ensure the stability of our service, we implement rate limiting on API requests. The current limits are:

Rate limit information is included in the response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1620000000

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of a request. In case of an error, the response body will contain additional information.

{
  "error": {
    "code": "invalid_request",
    "message": "The request was invalid",
    "details": "Document ID is required"
  }
}

Common error codes:

Documents API

The Documents API allows you to create, read, update, and delete documents in your account.

Create a Document

Upload a new document to your account.

POST /documents

Request Body:

{
  "name": "Contract Agreement",
  "file": "base64_encoded_file_content",
  "file_type": "pdf",
  "folder_id": "folder_123",
  "tags": ["contract", "agreement"]
}

Response:

{
  "id": "doc_123456",
  "name": "Contract Agreement",
  "file_type": "pdf",
  "status": "uploaded",
  "created_at": "2023-01-15T10:30:00Z",
  "updated_at": "2023-01-15T10:30:00Z",
  "folder_id": "folder_123",
  "tags": ["contract", "agreement"],
  "download_url": "https://api.thepapersignman.com/v1/documents/doc_123456/download"
}

Send Document for Signature

Send a document to recipients for signature.

POST /documents/{document_id}/send

Request Body:

{
  "recipients": [
    {
      "email": "john@example.com",
      "name": "John Doe",
      "role": "signer",
      "order": 1
    },
    {
      "email": "jane@example.com",
      "name": "Jane Smith",
      "role": "signer",
      "order": 2
    }
  ],
  "message": "Please sign this contract agreement",
  "subject": "Contract Agreement for Signature",
  "expires_in_days": 30,
  "reminder_frequency": "3_days"
}

Response:

{
  "id": "env_789012",
  "document_id": "doc_123456",
  "status": "sent",
  "created_at": "2023-01-15T11:00:00Z",
  "expires_at": "2023-02-14T11:00:00Z",
  "recipients": [
    {
      "id": "rec_123",
      "email": "john@example.com",
      "name": "John Doe",
      "role": "signer",
      "order": 1,
      "status": "pending",
      "signing_url": "https://sign.thepapersignman.com/s/abc123"
    },
    {
      "id": "rec_456",
      "email": "jane@example.com",
      "name": "Jane Smith",
      "role": "signer",
      "order": 2,
      "status": "pending"
    }
  ]
}

Quick Start Guide

This guide will help you get started with the PaperSignMan API by walking through a simple integration example.

Step 1: Get Your API Key

Log in to your PaperSignMan account and navigate to the API section in your dashboard to generate an API key.

Step 2: Upload a Document

First, let's upload a document to your account:

// Example using JavaScript and Node.js
const axios = require('axios');
const fs = require('fs');

async function uploadDocument() {
  const apiKey = 'YOUR_API_KEY';
  const filePath = './contract.pdf';
  
  // Read file and convert to base64
  const fileContent = fs.readFileSync(filePath);
  const base64File = fileContent.toString('base64');
  
  try {
    const response = await axios.post('https://api.thepapersignman.com/v1/documents', {
      name: 'Contract Agreement',
      file: base64File,
      file_type: 'pdf',
      tags: ['contract', 'agreement']
    }, {
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json'
      }
    });
    
    console.log('Document uploaded successfully:', response.data);
    return response.data.id;
  } catch (error) {
    console.error('Error uploading document:', error.response ? error.response.data : error.message);
  }
}

Step 3: Send Document for Signature

Now, let's send the uploaded document for signature:

async function sendDocumentForSignature(documentId) {
  const apiKey = 'YOUR_API_KEY';
  
  try {
    const response = await axios.post(`https://api.thepapersignman.com/v1/documents/${documentId}/send`, {
      recipients: [
        {
          email: 'john@example.com',
          name: 'John Doe',
          role: 'signer',
          order: 1
        },
        {
          email: 'jane@example.com',
          name: 'Jane Smith',
          role: 'signer',
          order: 2
        }
      ],
      message: 'Please sign this contract agreement',
      subject: 'Contract Agreement for Signature',
      expires_in_days: 30,
      reminder_frequency: '3_days'
    }, {
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json'
      }
    });
    
    console.log('Document sent for signature:', response.data);
    return response.data;
  } catch (error) {
    console.error('Error sending document:', error.response ? error.response.data : error.message);
  }
}

// Usage
async function main() {
  const documentId = await uploadDocument();
  if (documentId) {
    await sendDocumentForSignature(documentId);
  }
}

main();

Step 4: Track Document Status

You can track the status of your document and its signatures:

async function getDocumentStatus(documentId) {
  const apiKey = 'YOUR_API_KEY';
  
  try {
    const response = await axios.get(`https://api.thepapersignman.com/v1/documents/${documentId}`, {
      headers: {
        'Authorization': `Bearer ${apiKey}`
      }
    });
    
    console.log('Document status:', response.data);
    return response.data;
  } catch (error) {
    console.error('Error getting document status:', error.response ? error.response.data : error.message);
  }
}