Chaindoc REST API Reference

Complete reference for integrating Chaindoc's REST API into your applications. Manage documents, signatures, blockchain verification, and embedded signing workflows.

Overview

Chaindoc REST API provides programmatic access to document management, blockchain verification, and digital signature functionality. The API is designed for server-to-server integration and supports both public and secret API keys.

Key Features

• Document Management - Create, update, and manage documents with blockchain verification
• Digital Signatures - Request and collect digital signatures from multiple parties
• Blockchain Verification - Verify document authenticity on blockchain networks
• Embedded Sessions - Create secure sessions for frontend signing workflows
• Media Upload - Upload files (PDF, images, videos) for document creation
• KYC Integration - Share and verify identity data with Sumsub

Authentication

Chaindoc API uses API keys for authentication. There are two types of keys with different access levels.

API Key Types

• Public Key (pk_) - Read-only access for frontend apps and verification
• Secret Key (sk_) - Full read & write access for backend servers

Obtaining API Keys

Using API Keys

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

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:

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

{
  "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