REST API v1.0

BlockSign API Documentation

Integrate digital signatures, document management, and webhook notifications into your applications with our powerful REST API.

Get Started OpenAPI Spec

Authentication

All API requests require authentication using a Bearer token. Your API key can be found in your profile settings.


                                Authorization: Bearer YOUR_API_KEY

Where to find your API key

Navigate to Profile Settings and look for the API Key section. You can regenerate your key at any time.

Signature Levels

BlockSign supports multiple signature levels to meet different compliance requirements under eIDAS regulation.

AES Advanced Electronic Signature

Standard advanced signature with Swisscom TSP. Suitable for most business documents.

AESB AES + Blockchain

Advanced signature with additional Cardano blockchain anchoring for tamper evidence.

QES Qualified Electronic Signature

Highest legal standing, equivalent to handwritten signature. Requires identity verification.

QESB QES + Blockchain

Qualified signature with blockchain anchoring for maximum security and compliance.

Document Management

Core endpoints for uploading, listing, downloading, and managing documents.

Upload Document

POST

POST /api/upload

Upload a PDF document for signing. Returns the document UUID for subsequent operations.

List Documents

GET

GET /api/list

Retrieve a list of all documents for the authenticated user.

Document Status

GET

GET /api/status?uuid={document_uuid}

Get the current status of a document (pending, signed, declined).

Download Document

GET

GET /api/downloaddocument?uuid={document_uuid}

Download the signed PDF document.

Download Invoice

GET

GET /api/downloadinvoice?uuid={document_uuid}

Download the invoice for a document transaction.

Delete Document

DELETE

DELETE /api/deletedocument?uuid={document_uuid}

Permanently delete a document from your account.

Send Reminder

GET

GET /api/reminder?uuid={document_uuid}

Send a reminder email to pending signers.

Sign Document

GET

GET /api/sign_document?uuid={document_uuid}

Initiate the signing process for a document.

Signed Status

GET

GET /api/signed_status?uuid={document_uuid}

Check the signed status and get details about who has signed.

Invite for Sign

POST

POST /api/invite-for-sign

Send a document for signature to one or more recipients. Supports signature level selection, document types, and webhook callbacks.

Request Body

Parameter	Type	Required	Description
uuid	string	Required	Document UUID
email	string	Required	Recipient email address
name	string	Required	Recipient name
x	number	Required	X coordinate for signature placement
y	number	Required	Y coordinate for signature placement
page	integer	Required	Page number (1-indexed)
signature_level	string	Optional	One of: aes, aesb, qes, qesb
type	string	Optional	One of: signature, pod
callback_url	string	Optional	Webhook URL for status notifications

Example Request

{
  "uuid": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "email": "signer@example.com",
  "name": "John Doe",
  "x": 100,
  "y": 500,
  "page": 1,
  "signature_level": "aes",
  "type": "signature",
  "callback_url": "https://yourapp.com/webhook/signature-status"
}

Update Document Metadata

Update document properties after creation using these dedicated endpoints.

Update Signature Level

PUT

PUT /api/document/{uuid}/signature-level

{ "signature_level": "qes" }

Update Document Type

PUT

PUT /api/document/{uuid}/type

{ "type": "pod" }

Update Callback URL

PUT

PUT /api/document/{uuid}/callback-url

{ "callback_url": "https://yourapp.com/webhook" }

Webhook Callbacks

Receive real-time notifications when document status changes. Set a callback URL and we'll send a POST request with the event details.

Webhook Events

signed

Document has been signed by a recipient

declined

Document signing was declined

canceled

Document was canceled by the owner

Webhook Payload

When a document status changes, we send a POST request to your callback URL with the following headers and payload:


                                Content-Type: application/json

                                User-Agent: BlockSign-Webhook/1.0

                                X-BlockSign-Event: document.status_changed

{
  "event": "document.status_changed",
  "document": {
    "uuid": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "name": "Contract.pdf",
    "status": "signed",
    "signature_level": "aes",
    "type": "signature"
  },
  "timestamp": "2026-01-13T14:30:00+00:00",
  "signer": {
    "email": "signer@example.com",
    "name": "John Doe"
  },
  "all_signed": true
}

For canceled events, the signer and all_signed fields are not included.

Error Handling

The API uses standard HTTP status codes to indicate success or failure.

Status Code	Meaning
200	Success
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
403	Forbidden - You don't have access to this resource
404	Not Found - Resource doesn't exist
500	Server Error - Something went wrong on our end

Error Response Format

{
  "error": true,
  "message": "Document not found",
  "code": 404
}

Need Help?

Our team is here to help you integrate BlockSign into your applications.

Contact Support