Quick start guide

Get up and running with Chaindoc in under 10 minutes. This guide walks you through both the web interface and the API, so you can pick whichever path fits.

Signing through the web interface

You don't need any code to send your first signature request. The web app handles everything: upload, recipients, signing flow, and blockchain verification.

Step-by-step: your first signature

Want to understand the different signature types (simple, advanced, qualified)? That matters for compliance. Most business contracts work fine with simple e-signatures, but regulated industries often need advanced or qualified.

Integrating via the API

If you're building signing into your own app, you'll use the REST API and TypeScript SDKs. The flow is the same as the web interface, just automated.

1. Get your API keys

API access requires a Business plan. Go to Settings > API Access in your dashboard and create two keys:

• Public key (`pk_`) for frontend use with the Embed SDK
• Secret key (`sk_`) for backend use with the Server SDK. Keep this one out of client-side code.

2. Install the SDK

Pick the SDK that matches your use case. Most apps need both: the Server SDK for creating documents and the Embed SDK for the signing UI.

# Node.js 18+ required
npm install @chaindoc_io/server-sdk

For detailed framework setup (React, Vue, Angular, Next.js), check the installation guide.

3. Upload and create a document

import { Chaindoc } from '@chaindoc_io/server-sdk';
import { readFile } from 'fs/promises';

// Initialize SDK
const chaindoc = new Chaindoc({
  secretKey: process.env.CHAINDOC_SECRET_KEY!,
});

// 1. Upload document
const buffer = await readFile('./contract.pdf');
const file = new Blob([buffer], { type: 'application/pdf' });
const { media } = await chaindoc.media.upload([file]);

// 2. Create document record
const doc = await chaindoc.documents.create({
  name: 'Service Agreement',
  description: 'Q4 2024 Contract',
  media: media[0],
  status: 'published', // Triggers blockchain verification
  hashtags: ['#contract', '#2024'],
  meta: [{ key: 'client', value: 'Acme Corp' }],
});

console.log('Document created:', doc.documentId);

Setting `status: 'published'` triggers blockchain verification automatically. If you want to hold off, use `'draft'` and publish later.

4. Create a signature request

// Create signature request for multiple signers
const sigRequest = await chaindoc.signatures.createRequest({
  versionId: doc.document.versions[0].uuid,
  recipients: [
    { email: 'signer1@example.com' },
    { email: 'signer2@example.com' },
  ],
  deadline: new Date('2024-12-31'),
  message: 'Please review and sign this agreement',
  embeddedFlow: true, // Enable for frontend integration
});

console.log('Signature request created:', sigRequest.signatureRequest.uuid);

Set `embeddedFlow: true` if you're going to show the signing UI inside your app. Without it, signers get a link to Chaindoc's hosted signing page instead.

5. Show the signing interface (frontend)

This is optional. If you set `embeddedFlow: true`, you can open the signing UI right inside your app. First, create a session on the backend, then pass the session ID to the frontend.

// Create embedded session for signer
const session = await chaindoc.embedded.createSession({
  email: 'signer1@example.com',
  metadata: {
    documentId: doc.documentId,
    signatureRequestId: sigRequest.signatureRequest.uuid,
  },
});

// Return sessionId to frontend
res.json({ sessionId: session.sessionId });

6. Check status and listen for events

You can poll the status, but webhooks are a better option for production. They'll notify your server the moment something happens.

// Poll approach (fine for testing)
const status = await chaindoc.signatures.getRequestStatus(
  sigRequest.signatureRequest.uuid
);

if (status.signatureRequest.status === 'completed') {
  console.log('All signatures collected!');
}

7. Set up webhooks (recommended)

Webhooks push events to your server in real time, so you don't have to keep checking. Here's a basic Express handler:

// Configure webhook endpoint
app.post('/webhooks/chaindoc', (req, res) => {
  const event = req.headers['x-webhook-event'];
  const payload = req.body;
  
  switch (event) {
    case 'document.verified':
      console.log('Document verified on blockchain:', payload.txHash);
      break;
    case 'signature.request.completed':
      console.log('All signatures collected!');
      // Send notifications, update status, etc.
      break;
  }
  
  res.status(200).send('OK');
});

In production, you should verify webhook signatures with HMAC to make sure the payload actually came from Chaindoc. The webhooks guide covers that in detail.

Full workflow example

This puts it all together: upload, create, sign, verify. Copy it, swap in your API keys, and you've got a working prototype.

import { Chaindoc } from '@chaindoc_io/server-sdk';
import { readFile } from 'fs/promises';

async function createSigningWorkflow() {
  const chaindoc = new Chaindoc({
    secretKey: process.env.CHAINDOC_SECRET_KEY!,
  });
  
  // Step 1: Upload document
  const buffer = await readFile('./contract.pdf');
  const file = new Blob([buffer], { type: 'application/pdf' });
  const { media } = await chaindoc.media.upload([file]);
  
  // Step 2: Create document
  const doc = await chaindoc.documents.create({
    name: 'Service Agreement',
    description: 'Contract for consulting services',
    media: media[0],
    status: 'published',
    hashtags: ['#contract'],
    meta: [],
  });
  
  // Step 3: Create signature request
  const sigRequest = await chaindoc.signatures.createRequest({
    versionId: doc.document.versions[0].uuid,
    recipients: [{ email: 'signer@example.com' }],
    deadline: new Date('2024-12-31'),
    embeddedFlow: true,
  });
  
  // Step 4: Create session for frontend
  const session = await chaindoc.embedded.createSession({
    email: 'signer@example.com',
    metadata: {
      documentId: doc.documentId,
      signatureRequestId: sigRequest.signatureRequest.uuid,
    },
  });
  
  return {
    documentId: doc.documentId,
    sessionId: session.sessionId,
  };
}

// Usage
const { documentId, sessionId } = await createSigningWorkflow();
console.log('Ready for signing:', { documentId, sessionId });

Where to go next

Now that you've got the basics down, here's what to dig into depending on what you're building:

• Installation — framework-specific setup for React, Vue, Angular, and Next.js
• API documentation — full endpoint reference with request/response examples
• SDKs — Server SDK and Embed SDK, with per-framework integration guides
• Webhooks — real-time event notifications for production apps
• Security best practices — what to lock down before going live

Common questions

How long does blockchain verification take?

Usually 1-5 minutes, depending on the network. Your document is available right away though. Verification runs in the background and you'll get a webhook event when it's done.

Can I test the API without paying?

The free plan gives you access to the web interface. API access needs a Business plan, but the sandbox environment lets you test everything without affecting real data or using up quota.

Are these signatures legally binding?

Yes. Chaindoc signatures comply with eIDAS in Europe, the ESIGN Act and UETA in the US, and equivalent regulations in most other jurisdictions. The blockchain verification adds an extra layer of evidence on top of that, which can matter in disputes. See the signatures docs for details on which signature type fits your compliance needs.

What file formats can I upload?

PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT, JPG, PNG, GIF, WEBP, SVG, MP4, AVI, MOV, and WMV. Max file size is 50MB.