Documentation

Technical guides and API references for integrating with DocumentsScanned

Getting Started

Welcome to the DocumentsScanned API. This guide will help you get started with integrating our digital document signing services into your application.

Prerequisites

Before you begin, you'll need:

  • A DocumentsScanned account with API access (available on Professional and Enterprise plans)
  • Your API key (available in your account dashboard)
  • Basic knowledge of REST APIs and your preferred programming language

API Base URL

All API requests should be made to the following base URL:

https://api.documentsscanned.com/v1/

Rate Limits

Rate limits vary by plan:

  • Professional: 100 requests per minute
  • Enterprise: 500 requests per minute

If you exceed these limits, the API will return a 429 Too Many Requests response.

Authentication

All API requests require authentication using your API key.

API Key Authentication

Include your API key in the request headers:

GET /v1/documents HTTP/1.1
Host: api.documentsscanned.com
X-API-Key: your_api_key_here
Content-Type: application/json

Replace your_api_key_here with your actual API key.

Never share your API key or include it in client-side code. Always make API calls from your server.

API Reference

Explore our API endpoints and learn how to integrate with our services.

Document Endpoints

Create a Document

POST /v1/documents

Upload a new document for signing.

Request Body:
{
  "name": "Contract Agreement",
  "file_content": "base64_encoded_file_content",
  "file_type": "pdf",
  "signers": [
    {
      "email": "signer1@example.com",
      "name": "John Doe",
      "role": "Client"
    },
    {
      "email": "signer2@example.com",
      "name": "Jane Smith",
      "role": "Agent"
    }
  ],
  "signature_fields": [
    {
      "signer_index": 0,
      "page": 1,
      "x": 100,
      "y": 100,
      "width": 200,
      "height": 50
    },
    {
      "signer_index": 1,
      "page": 1,
      "x": 100,
      "y": 200,
      "width": 200,
      "height": 50
    }
  ]
}
Response:
{
  "document_id": "doc_123abc456def",
  "status": "created",
  "signing_url": "https://sign.documentsscanned.com/doc_123abc456def",
  "signers": [
    {
      "signer_id": "sgr_123abc",
      "email": "signer1@example.com",
      "status": "pending"
    },
    {
      "signer_id": "sgr_456def",
      "email": "signer2@example.com",
      "status": "pending"
    }
  ],
  "created_at": "2023-07-15T14:30:00Z",
  "expires_at": "2023-08-15T14:30:00Z"
}

Get Documents

GET /v1/documents

Retrieve a list of all documents.

Response:
{
  "documents": [
    {
      "document_id": "doc_123abc456def",
      "name": "Contract Agreement",
      "status": "in_progress",
      "created_at": "2023-07-15T14:30:00Z"
    },
    {
      "document_id": "doc_789ghi101jkl",
      "name": "NDA Document",
      "status": "completed",
      "created_at": "2023-07-10T09:15:00Z"
    }
  ],
  "total": 2,
  "page": 1,
  "page_size": 10
}

Get Document Details

GET /v1/documents/{document_id}

Retrieve details of a specific document.

Response:
{
  "document_id": "doc_123abc456def",
  "name": "Contract Agreement",
  "status": "in_progress",
  "file_type": "pdf",
  "signers": [
    {
      "signer_id": "sgr_123abc",
      "email": "signer1@example.com",
      "name": "John Doe",
      "status": "signed",
      "signed_at": "2023-07-15T15:45:00Z"
    },
    {
      "signer_id": "sgr_456def",
      "email": "signer2@example.com",
      "name": "Jane Smith",
      "status": "pending"
    }
  ],
  "created_at": "2023-07-15T14:30:00Z",
  "expires_at": "2023-08-15T14:30:00Z"
}

Additional Endpoints

Endpoint Method Description
/v1/documents/{document_id}/download GET Download a signed document
/v1/documents/{document_id}/cancel POST Cancel a document signing process
/v1/documents/{document_id}/remind POST Send a reminder to pending signers
/v1/templates GET List available document templates
/v1/templates/{template_id}/use POST Create a document from a template

For complete API documentation, download our API Reference PDF.

Webhooks

Get real-time notifications about document events using webhooks.

Setting Up Webhooks

Configure webhook endpoints in your DocumentsScanned dashboard. We'll send HTTP POST notifications to your endpoint whenever specified events occur.

Sample Webhook Payload:

{
  "event_type": "document.signed",
  "document_id": "doc_123abc456def",
  "signer_id": "sgr_123abc",
  "signer_email": "signer1@example.com",
  "timestamp": "2023-07-15T15:45:00Z"
}

Available Event Types:

  • document.created - Document created
  • document.viewed - Document viewed by signer
  • document.signed - Document signed by a signer
  • document.completed - Document signed by all signers
  • document.declined - Document declined by signer
  • document.expired - Document signing period expired

SDKs & Libraries

Use our official client libraries to integrate more easily.

PHP SDK

Our PHP client library for easy integration.

composer require documentsscanned/php-sdk
PHP Documentation

JavaScript SDK

Our JavaScript client library for Node.js applications.

npm install documentsscanned-sdk
JavaScript Documentation

Python SDK

Our Python client library for easy integration.

pip install documentsscanned
Python Documentation

Java SDK

Our Java client library for enterprise applications.

implementation 'com.documentsscanned:sdk:1.0.0'
Java Documentation

Example Code

Here are some code examples to help you get started with our API.

Creating a Document in PHP

<?php
// Using the DocumentsScanned PHP SDK

require 'vendor/autoload.php';

use DocumentsScanned\Client;
use DocumentsScanned\Document;

// Initialize the client with your API key
$client = new Client('your_api_key_here');

// Prepare document data
$documentData = [
    'name' => 'Contract Agreement',
    'file_path' => '/path/to/your/document.pdf',
    'signers' => [
        [
            'email' => 'signer1@example.com',
            'name' => 'John Doe',
            'role' => 'Client'
        ],
        [
            'email' => 'signer2@example.com',
            'name' => 'Jane Smith',
            'role' => 'Agent'
        ]
    ],
    'signature_fields' => [
        [
            'signer_index' => 0,
            'page' => 1,
            'x' => 100,
            'y' => 100,
            'width' => 200,
            'height' => 50
        ],
        [
            'signer_index' => 1,
            'page' => 1,
            'x' => 100,
            'y' => 200,
            'width' => 200,
            'height' => 50
        ]
    ]
];

try {
    // Create the document
    $document = $client->documents->create($documentData);
    
    // Get the document ID and signing URL
    $documentId = $document->id;
    $signingUrl = $document->signing_url;
    
    echo "Document created with ID: $documentId\n";
    echo "Signing URL: $signingUrl\n";
} catch (\Exception $e) {
    echo "Error: " . $e->getMessage();
}
?>

Creating a Document in JavaScript (Node.js)

// Using the DocumentsScanned JavaScript SDK
const DocumentsScanned = require('documentsscanned-sdk');
const fs = require('fs');

// Initialize the client with your API key
const client = new DocumentsScanned('your_api_key_here');

// Read the file content and encode as base64
const filePath = '/path/to/your/document.pdf';
const fileContent = fs.readFileSync(filePath);
const base64File = fileContent.toString('base64');

// Prepare document data
const documentData = {
  name: 'Contract Agreement',
  file_content: base64File,
  file_type: 'pdf',
  signers: [
    {
      email: 'signer1@example.com',
      name: 'John Doe',
      role: 'Client'
    },
    {
      email: 'signer2@example.com',
      name: 'Jane Smith',
      role: 'Agent'
    }
  ],
  signature_fields: [
    {
      signer_index: 0,
      page: 1,
      x: 100,
      y: 100,
      width: 200,
      height: 50
    },
    {
      signer_index: 1,
      page: 1,
      x: 100,
      y: 200,
      width:.200,
      height: 50
    }
  ]
};

// Create the document
client.documents.create(documentData)
  .then(document => {
    console.log(`Document created with ID: ${document.document_id}`);
    console.log(`Signing URL: ${document.signing_url}`);
  })
  .catch(error => {
    console.error('Error:', error.message);
  });

Creating a Document in Python

# Using the DocumentsScanned Python SDK
import documentsscanned
import base64

# Initialize the client with your API key
client = documentsscanned.Client('your_api_key_here')

# Read the file content and encode as base64
file_path = '/path/to/your/document.pdf'
with open(file_path, 'rb') as file:
    file_content = file.read()
    base64_file = base64.b64encode(file_content).decode('utf-8')

# Prepare document data
document_data = {
    'name': 'Contract Agreement',
    'file_content': base64_file,
    'file_type': 'pdf',
    'signers': [
        {
            'email': 'signer1@example.com',
            'name': 'John Doe',
            'role': 'Client'
        },
        {
            'email': 'signer2@example.com',
            'name': 'Jane Smith',
            'role': 'Agent'
        }
    ],
    'signature_fields': [
        {
            'signer_index': 0,
            'page': 1,
            'x': 100,
            'y': 100,
            'width': 200,
            'height': 50
        },
        {
            'signer_index': 1,
            'page': 1,
            'x': 100,
            'y': 200,
            'width': 200,
            'height': 50
        }
    ]
}

try:
    # Create the document
    document = client.documents.create(document_data)
    
    # Get the document ID and signing URL
    document_id = document.document_id
    signing_url = document.signing_url
    
    print(f"Document created with ID: {document_id}")
    print(f"Signing URL: {signing_url}")
except Exception as e:
    print(f"Error: {str(e)}")

Developer FAQs

Common questions about using our API.

Our API supports multiple file formats including PDF, DOCX, XLSX, and PPTX. However, PDF is recommended for the most consistent signing experience. Non-PDF files will be automatically converted to PDF format before the signing process begins.

Each webhook request includes a X-DocumentsScanned-Signature header. This signature is created using HMAC-SHA256 with your webhook secret as the key and the request body as the message. You should compute this signature on your server and compare it with the one in the header to verify the webhook came from DocumentsScanned.

The maximum file size is 25MB. For larger documents, we recommend splitting them into smaller files or contacting our support team for assistance with special cases.

Document retention periods vary by plan. Basic plans include 30 days of storage, Professional plans include 1 year, and Enterprise plans include unlimited storage. After the retention period, documents are automatically deleted unless you download them. You can also use the API to download documents and store them in your own systems.

Yes, we provide a sandbox environment for testing your integration before going live. Use the base URL https://sandbox-api.documentsscanned.com/v1/ for your test requests. You'll need a separate sandbox API key, which you can generate in your account dashboard under the Developer section.

Ready to integrate with DocumentsScanned?

Sign up for an account to get your API key and start developing.