Getting Started with SignYourDocuments.com API

The SignYourDocuments.com API allows you to integrate our digital document signing functionality into your own applications. This guide will help you get started with implementing our API.

Base URL

https://api.signyourdocuments.com/v1

API Keys

To use the SignYourDocuments.com API, you'll need an API key. You can get your API key from your account dashboard after logging in. Keep your API key confidential and secure.

Our API is available only for Professional and Enterprise plans.

Authentication

All API requests must include your API key for authentication. There are two ways to include your API key:

1. Authorization Header

Authorization: Bearer YOUR_API_KEY

2. Query Parameter

https://api.signyourdocuments.com/v1/documents?api_key=YOUR_API_KEY
We recommend using the Authorization header method as it's more secure.

API Endpoints

SignYourDocuments.com API provides several endpoints for managing documents, signatures, templates, and users.

Documents

Endpoint Method Description
/documents GET List all documents
/documents/{id} GET Get a specific document
/documents POST Create a new document
/documents/{id} PUT Update a document
/documents/{id} DELETE Delete a document

Example Request - Create Document

{
  "name": "Contract Agreement",
  "file_content": "base64_encoded_file_content",
  "file_type": "pdf",
  "recipients": [
    {
      "email": "recipient@example.com",
      "name": "John Doe",
      "role": "signer"
    }
  ],
  "expiration_days": 14
}

Example Response

{
  "id": "doc_12345",
  "name": "Contract Agreement",
  "status": "pending",
  "created_at": "2023-06-01T12:00:00Z",
  "expires_at": "2023-06-15T12:00:00Z",
  "recipients": [
    {
      "id": "rec_67890",
      "email": "recipient@example.com",
      "name": "John Doe",
      "role": "signer",
      "status": "pending"
    }
  ],
  "document_url": "https://api.signyourdocuments.com/v1/documents/doc_12345/download"
}

Signatures

Endpoint Method Description
/documents/{id}/signatures GET List all signatures for a document
/signatures/{id} GET Get a specific signature
/documents/{id}/signatures POST Add a signature to a document

Templates

Endpoint Method Description
/templates GET List all templates
/templates/{id} GET Get a specific template
/templates POST Create a new template
/templates/{id} PUT Update a template
/templates/{id} DELETE Delete a template
/templates/{id}/use POST Create a document from a template

Users

Endpoint Method Description
/users GET List all users (Enterprise plan only)
/users/{id} GET Get a specific user
/users POST Create a new user (Enterprise plan only)
/users/{id} PUT Update a user
/users/{id} DELETE Delete a user (Enterprise plan only)

Webhooks

SignYourDocuments.com can send webhook notifications to your server when certain events occur, such as when a document is signed or when a signature request expires.

Setting Up Webhooks

You can configure webhook endpoints in your account dashboard. Specify the URL where you want to receive webhook events.

Webhook Payload

{
  "event_type": "document.signed",
  "timestamp": "2023-06-01T12:30:00Z",
  "data": {
    "document_id": "doc_12345",
    "document_name": "Contract Agreement",
    "signer": {
      "id": "rec_67890",
      "email": "recipient@example.com",
      "name": "John Doe"
    }
  }
}

Webhook Events

Event Type Description
document.created A new document has been created
document.viewed A document has been viewed by a recipient
document.signed A document has been signed by a recipient
document.completed All recipients have signed a document
document.expired A document has expired without being completed

Error Handling

The SignYourDocuments.com API uses standard HTTP status codes to indicate the success or failure of an API request.

HTTP Status Codes

Status Code Description
200 - OK The request was successful
201 - Created The resource was successfully created
400 - Bad Request The request was invalid or cannot be served
401 - Unauthorized Authentication failed or user doesn't have permissions
403 - Forbidden The request is valid but the server is refusing action
404 - Not Found The requested resource could not be found
429 - Too Many Requests You've exceeded the rate limit
500 - Internal Server Error An error occurred on the server

Error Response Format

{
  "error": {
    "code": "invalid_request",
    "message": "The request is missing a required parameter",
    "details": "Parameter 'file_content' is required"
  }
}

Code Examples

Here are some examples to help you get started with the SignYourDocuments.com API in different programming languages.

JavaScript

// Create a new document
const createDocument = async () => {
  const apiKey = 'YOUR_API_KEY';
  const url = 'https://api.signyourdocuments.com/v1/documents';
  
  const documentData = {
    name: 'Contract Agreement',
    file_content: 'base64_encoded_file_content',
    file_type: 'pdf',
    recipients: [
      {
        email: 'recipient@example.com',
        name: 'John Doe',
        role: 'signer'
      }
    ],
    expiration_days: 14
  };
  
  try {
    const response = await fetch(url, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(documentData)
    });
    
    const data = await response.json();
    
    if (!response.ok) {
      throw new Error(data.error.message || 'Something went wrong');
    }
    
    console.log('Document created successfully:', data);
    return data;
  } catch (error) {
    console.error('Error creating document:', error);
    throw error;
  }
};

PHP

<?php
// Create a new document
function createDocument() {
    $apiKey = 'YOUR_API_KEY';
    $url = 'https://api.signyourdocuments.com/v1/documents';
    
    $documentData = [
        'name' => 'Contract Agreement',
        'file_content' => 'base64_encoded_file_content',
        'file_type' => 'pdf',
        'recipients' => [
            [
                'email' => 'recipient@example.com',
                'name' => 'John Doe',
                'role' => 'signer'
            ]
        ],
        'expiration_days' => 14
    ];
    
    $ch = curl_init($url);
    
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($documentData));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json'
    ]);
    
    $response = curl_exec($ch);
    $statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    
    curl_close($ch);
    
    $responseData = json_decode($response, true);
    
    if ($statusCode >= 400) {
        throw new Exception($responseData['error']['message'] ?? 'Something went wrong');
    }
    
    echo "Document created successfully: " . print_r($responseData, true);
    return $responseData;
}

try {
    $document = createDocument();
} catch (Exception $e) {
    echo "Error creating document: " . $e->getMessage();
}
?>

Python

import requests
import json

# Create a new document
def create_document():
    api_key = 'YOUR_API_KEY'
    url = 'https://api.signyourdocuments.com/v1/documents'
    
    document_data = {
        'name': 'Contract Agreement',
        'file_content': 'base64_encoded_file_content',
        'file_type': 'pdf',
        'recipients': [
            {
                'email': 'recipient@example.com',
                'name': 'John Doe',
                'role': 'signer'
            }
        ],
        'expiration_days': 14
    }
    
    headers = {
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'application/json'
    }
    
    try:
        response = requests.post(url, headers=headers, data=json.dumps(document_data))
        response.raise_for_status()  # Raise exception for 4XX/5XX status codes
        
        data = response.json()
        print('Document created successfully:', data)
        return data
    except requests.exceptions.HTTPError as e:
        error_data = e.response.json()
        print('Error creating document:', error_data.get('error', {}).get('message', str(e)))
        raise

try:
    document = create_document()
except Exception as e:
    print('Exception:', str(e))

Best Practices

Follow these best practices to ensure optimal integration with the SignYourDocuments.com API:

Secure Your API Key

Never expose your API key in client-side code. Always make API calls from your server.

Implement Retry Logic

Implement exponential backoff retry logic for failures to handle temporary issues.

Monitor Rate Limits

Our API has rate limits. Monitor the rate limit headers to avoid hitting limits.

Use Webhooks for Real-time Updates

Instead of polling our API, use webhooks to receive real-time notifications.

Validate Webhook Signatures

Verify webhook payloads using the signature header to ensure authenticity.

Need Additional Help?

Our support team is ready to answer any questions you have about integrating with our API.