API Integration

Integrate Chaindoc into your applications with our powerful REST API and SDKs. Automate document workflows, collect signatures, and sync events in real-time.

Overview

Chaindoc provides a comprehensive REST API that enables you to build custom document signing workflows, automate processes, and integrate with your existing systems. The API is designed for developers with full TypeScript support and automatic retries.

Getting Started

1. Get API Access

2. Choose Integration Method

Chaindoc offers three integration approaches:

• REST API - Direct HTTP requests for maximum flexibility
• Server SDK - Type-safe Node.js SDK with automatic retries (@chaindoc_io/server-sdk)
• Embed SDK - Frontend signing interface for web apps (@chaindoc_io/embed-sdk)

3. Quick Example

curl -X POST https://api.chaindoc.io/api/v1/documents \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contract",
    "description": "Service agreement",
    "status": "published",
    "hashtags": ["#contract"],
    "meta": []
  }'

Core API Concepts

Authentication

All API requests require authentication using API keys in the Authorization header:

Authorization: Bearer sk_live_xxxxxxxxxxxxx

• Public Keys (pk_) - Read-only access for frontend applications
• Secret Keys (sk_) - Full read/write access for backend servers
• Test Keys (pk_test_, sk_test_) - For staging/development
• Live Keys (pk_live_, sk_live_) - For production

Rate Limits

API endpoints have rate limits to ensure fair usage:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 8
X-RateLimit-Reset: 1640000000

• General endpoints: 3 requests per 10 seconds
• Media upload: 3 requests per 10 seconds
• Read operations: 10 requests per 60 seconds
• Signature creation: 20 requests per 3 seconds

Error Handling

API returns standard HTTP status codes with detailed error messages:

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request",
  "details": [
    {
      "field": "name",
      "message": "name must be a string"
    }
  ]
}

Common Integration Patterns

Document Upload & Signing Flow

Backend-Only Workflow

For scenarios where signers don't use your interface:

// Create signature request with email notifications
const sigRequest = await chaindoc.signatures.createRequest({
  versionId: documentVersionId,
  recipients: [{ email: 'signer@example.com' }],
  deadline: new Date('2024-12-31'),
  embeddedFlow: false, // Signers use Chaindoc email links
  message: 'Please review and sign this document',
});

// Chaindoc sends emails to recipients
// Track status via webhooks or API polling

Bulk Document Processing

// Process multiple documents in batch
const documents = ['doc1.pdf', 'doc2.pdf', 'doc3.pdf'];

for (const file of documents) {
  const buffer = await readFile(file);
  const blob = new Blob([buffer], { type: 'application/pdf' });
  
  const { media } = await chaindoc.media.upload([blob]);
  
  await chaindoc.documents.create({
    name: file,
    description: 'Batch processed document',
    media: media[0],
    status: 'published',
    hashtags: ['#batch'],
    meta: [{ key: 'batch', value: 'import-2024' }],
  });
}

Advanced Features

Webhooks

Receive real-time notifications for document events:

// Configure webhook endpoint
app.post('/webhooks/chaindoc', async (req, res) => {
  const event = req.headers['x-webhook-event'];
  
  switch (event) {
    case 'document.verified':
      await handleBlockchainVerification(req.body);
      break;
    case 'signature.request.completed':
      await notifyAllParties(req.body);
      break;
  }
  
  res.status(200).send('OK');
});

KYC Integration

Integrate identity verification for high-security workflows:

// Create signature request with KYC required
const sigRequest = await chaindoc.signatures.createRequest({
  versionId: documentVersionId,
  recipients: [{ 
    email: 'signer@example.com',
    shareToken: 'sumsub_token_here' // Optional: pre-verified KYC
  }],
  deadline: new Date('2024-12-31'),
  isKycRequired: true, // Enforce identity verification
});

Access Control

Manage document permissions with granular access control:

// Update document access rights
await chaindoc.documents.updateRights(documentId, {
  accessType: 'restricted',
  accessEmails: [
    { email: 'viewer@company.com', level: 'read' },
    { email: 'editor@company.com', level: 'write' },
  ],
  accessRoles: [
    { roleId: 1, level: 'read' }, // Team role
  ],
});

Best Practices

• Store API keys in environment variables, never in code
• Use test keys for development, live keys for production
• Implement exponential backoff for rate limit handling
• Verify webhook signatures to prevent replay attacks
• Cache API responses when appropriate
• Upload files before creating documents for better performance
• Use pagination for large datasets
• Monitor rate limit headers and adjust request frequency

Example Integrations

E-commerce Platform

Automatically generate and sign purchase agreements for high-value orders.

HR System

Integrate with HRIS for automated employment contract signing during onboarding.

CRM Integration

Create signature requests directly from customer records in Salesforce, HubSpot, or custom CRM.

Document Management System

Add blockchain verification to existing DMS for tamper-proof audit trails.

Resources

• API Documentation - Complete REST API reference with all endpoints
• SDKs - Server SDK and Embed SDK documentation with framework examples
• Webhooks - Real-time event notifications setup guide
• Quick Start - Get your first integration running in 10 minutes
• GitHub Examples - Sample integrations and code snippets