Chaindoc logoChaindoc

Chaindoc REST API reference

Full endpoint reference for the Chaindoc REST API. Covers authentication, documents, signatures, media uploads, embedded sessions, and blockchain verification.

Overview

The API gives you programmatic access to everything in Chaindoc: documents, signatures, blockchain verification, and team management. It's designed for server-to-server use and supports both public and secret API keys.

  • Documents — create, update, and verify documents on the blockchain
  • Signatures — send signature requests and track completion
  • Media — upload PDFs, images, and videos (max 10 per request)
  • Embedded sessions — create signing sessions for your frontend (uses the Embed SDK)
  • KYC — share and verify identity data via Sumsub integration

Authentication

Every request needs an API key in the Authorization header. There are two types:

Key types

  • Public key (`pk_`) — read-only, safe for frontend code
  • Secret key (`sk_`) — full read/write, backend only. Never expose in client-side code.

Getting your keys

1Subscribe to Business planOnly Business plan users can create API keys

2Navigate to API AccessGo to Settings → API Access in your dashboard

3Create API keyClick Create API Key button

4Store securelyStore the secret key securely (shown only once)

Using API keys

Include your API key in the Authorization header with Bearer authentication:

terminal
curl -X GET https://api.chaindoc.io/api/v1/me \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxx"

Rate limiting

API endpoints are rate-limited to prevent abuse. Rate limits vary by endpoint type.

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

When rate limit is exceeded, you'll receive a 429 Too Many Requests response. Rate limit headers are included in responses:

terminal
X-RateLimit-Limit: 3
X-RateLimit-Remaining: 2
X-RateLimit-Reset: 1640000000

Error handling

HTTP status codes

  • 200 - Success
  • 201 - Resource created successfully
  • 400 - Bad request (validation error)
  • 401 - Unauthorized (invalid or missing API key)
  • 403 - Forbidden (insufficient permissions)
  • 404 - Resource not found
  • 429 - Too many requests (rate limit exceeded)
  • 500 - Internal server error

Error response format

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

General API

Get API key info

Get information about the current API key.

GET /me

Authorization: Bearer sk_live_xxxxx

Health check

Verify API connectivity and key validity.

GET /health

Authorization: Bearer sk_live_xxxxx

Documents API

Create document

Create a new document with blockchain verification. When status is set to 'published', the document is automatically verified on blockchain.

POST /documents

Headers:
Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Update document

Update a document by creating a new version. Previous versions are preserved for audit trail.

PUT /documents/:documentId

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Update document access rights

Update document access control settings.

PUT /documents/:documentId/rights

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Verify document

Verify document authenticity using blockchain. Returns verification status with transaction hash and chain ID.

POST /documents/verify

{
  "versionHash": "0x123abc...",
  "certificateHash": "0x456def..."
}

Get verification status

Get blockchain verification status for a document version.

GET /documents/versions/:versionId/verification

Authorization: Bearer sk_live_xxxxx

Signatures API

Create signature request

Create a signature request for one or more recipients. Enable embedded flow for frontend integration.

curl -X POST https://api.chaindoc.io/api/v1/signatures/requests \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "versionId": "f0b7721f-0399-4035-9b69-7b95d3a367f0",
    "recipients": [{"email": "signer@example.com"}],
    "deadline": "2024-12-31T23:59:59Z",
    "embeddedFlow": true
  }'

Get signature request status

Check the status of a signature request and see which signers have completed signing.

GET /signatures/requests/:requestId/status

Authorization: Bearer sk_live_xxxxx

Sign document

Sign a document (if API key owner is a signatory).

POST /signatures/sign

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Get user signatures

Get all signatures for the authenticated user.

GET /signatures

Authorization: Bearer sk_live_xxxxx

Get signature requests

Get all signature requests for the authenticated user with pagination support.

GET /signatures/requests?pageNumber=1&pageSize=10

Authorization: Bearer sk_live_xxxxx

Media upload API

Upload files for use in document creation. Supports PDF, images, and videos. Maximum 10 files per request.

curl -X POST https://api.chaindoc.io/api/v1/media/upload \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -F "media=@contract.pdf"

KYC API

Share KYC data

Share KYC (Know Your Customer) data with recipients for identity verification.

POST /kyc/share

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Embedded sessions API

Create embedded sessions for document signing in your frontend application. Sessions are valid for 10 minutes.

POST /embedded/sessions

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

What to do next

  • API integration — common patterns, best practices, and full workflow examples
  • SDKs — Server SDK and Embed SDK with framework-specific guides
  • Webhooks — set up real-time event notifications
  • Installation — npm setup for all supported frameworks
  • Security — API key management and compliance