Integrate DocuRecorded's electronic signature capabilities into your applications.
The DocuRecorded API allows you to integrate our electronic signature capabilities into your applications. With our API, you can create and manage documents, send them for signature, and track their status programmatically.
Our API is organized around REST. It accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
All API requests should be made to the following base URL:
https://api.docurecorded.com/v1
The current version of the API is v1. We may release new versions in the future to add features or make changes to existing endpoints.
The API is rate limited to 100 requests per minute per API key. If you exceed this limit, you'll receive a 429 Too Many Requests response.
The DocuRecorded API uses API keys for authentication. You can obtain an API key from your account dashboard.
All API requests must include your API key in the Authorization header:
Authorization: Bearer YOUR_API_KEY
Your API key carries many privileges, so be sure to keep it secure. Do not share your API key in publicly accessible areas such as GitHub, client-side code, etc.
Note
If you believe your API key has been compromised, you can regenerate it from your account dashboard.
The DocuRecorded API uses conventional HTTP response codes to indicate the success or failure of an API request.
In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g., a required parameter was missing), and codes in the 5xx range indicate an error with our servers.
Code | Description |
---|---|
200 - OK | Everything worked as expected. |
201 - Created | A new resource was successfully created. |
400 - Bad Request | The request was unacceptable, often due to missing a required parameter. |
401 - Unauthorized | No valid API key provided. |
403 - Forbidden | The API key doesn't have permissions to perform the request. |
404 - Not Found | The requested resource doesn't exist. |
429 - Too Many Requests | Too many requests hit the API too quickly. |
500, 502, 503, 504 - Server Errors | Something went wrong on our end. |
When an error occurs, the API will return a JSON response with an error object:
{ "error": { "code": "invalid_request", "message": "The request was unacceptable, often due to missing a required parameter.", "param": "document_id", "type": "validation_error" } }
The Documents API allows you to create, retrieve, update, and delete documents.
Creates a new document.
Parameter | Type | Required | Description |
---|---|---|---|
name | string | Yes | The name of the document. |
file | file | Yes | The document file (PDF, DOCX, etc.). |
signers | array | No | An array of signers for the document. |
expires_at | string | No | The expiration date for the document (ISO 8601 format). |
curl -X POST https://api.docurecorded.com/v1/documents \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "name=Contract" \ -F "[email protected]" \ -F "signers[0][name]=John Doe" \ -F "signers[0][phone]=+15551234567" \ -F "signers[1][name]=Jane Smith" \ -F "signers[1][phone]=+15557654321" \ -F "expires_at=2023-12-31T23:59:59Z"
{ "id": "doc_123456789", "name": "Contract", "status": "draft", "created_at": "2023-06-01T12:00:00Z", "updated_at": "2023-06-01T12:00:00Z", "expires_at": "2023-12-31T23:59:59Z", "signers": [ { "id": "signer_123", "name": "John Doe", "phone": "+15551234567", "status": "pending" }, { "id": "signer_456", "name": "Jane Smith", "phone": "+15557654321", "status": "pending" } ], "file_url": "https://api.docurecorded.com/v1/documents/doc_123456789/file" }
Retrieves a document by ID.
Parameter | Type | Required | Description |
---|---|---|---|
document_id | string | Yes | The ID of the document to retrieve. |
curl -X GET https://api.docurecorded.com/v1/documents/doc_123456789 \ -H "Authorization: Bearer YOUR_API_KEY"
{ "id": "doc_123456789", "name": "Contract", "status": "draft", "created_at": "2023-06-01T12:00:00Z", "updated_at": "2023-06-01T12:00:00Z", "expires_at": "2023-12-31T23:59:59Z", "signers": [ { "id": "signer_123", "name": "John Doe", "phone": "+15551234567", "status": "pending" }, { "id": "signer_456", "name": "Jane Smith", "phone": "+15557654321", "status": "pending" } ], "file_url": "https://api.docurecorded.com/v1/documents/doc_123456789/file" }
Lists all documents.
Parameter | Type | Required | Description |
---|---|---|---|
limit | integer | No | The maximum number of documents to return (default: 10, max: 100). |
offset | integer | No | The number of documents to skip (default: 0). |
status | string | No | Filter documents by status (draft, sent, completed, expired). |
curl -X GET "https://api.docurecorded.com/v1/documents?limit=5&status=sent" \ -H "Authorization: Bearer YOUR_API_KEY"
{ "data": [ { "id": "doc_123456789", "name": "Contract", "status": "sent", "created_at": "2023-06-01T12:00:00Z", "updated_at": "2023-06-01T12:30:00Z", "expires_at": "2023-12-31T23:59:59Z" }, { "id": "doc_987654321", "name": "Agreement", "status": "sent", "created_at": "2023-06-02T10:00:00Z", "updated_at": "2023-06-02T10:15:00Z", "expires_at": "2023-12-31T23:59:59Z" } ], "meta": { "total": 2, "limit": 5, "offset": 0 } }
The Templates API allows you to create, retrieve, update, and delete document templates.
Creates a new template.
Parameter | Type | Required | Description |
---|---|---|---|
name | string | Yes | The name of the template. |
file | file | Yes | The template file (PDF, DOCX, etc.). |
fields | array | No | An array of fields for the template. |
curl -X POST https://api.docurecorded.com/v1/templates \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "name=Contract Template" \ -F "file=@contract_template.pdf" \ -F "fields[0][name]=signature" \ -F "fields[0][type]=signature" \ -F "fields[0][x]=100" \ -F "fields[0][y]=200" \ -F "fields[0][page]=1" \ -F "fields[1][name]=date" \ -F "fields[1][type]=date" \ -F "fields[1][x]=300" \ -F "fields[1][y]=200" \ -F "fields[1][page]=1"
{ "id": "template_123456789", "name": "Contract Template", "created_at": "2023-06-01T12:00:00Z", "updated_at": "2023-06-01T12:00:00Z", "fields": [ { "id": "field_123", "name": "signature", "type": "signature", "x": 100, "y": 200, "page": 1 }, { "id": "field_456", "name": "date", "type": "date", "x": 300, "y": 200, "page": 1 } ], "file_url": "https://api.docurecorded.com/v1/templates/template_123456789/file" }
Retrieves a template by ID.
Parameter | Type | Required | Description |
---|---|---|---|
template_id | string | Yes | The ID of the template to retrieve. |
curl -X GET https://api.docurecorded.com/v1/templates/template_123456789 \ -H "Authorization: Bearer YOUR_API_KEY"
{ "id": "template_123456789", "name": "Contract Template", "created_at": "2023-06-01T12:00:00Z", "updated_at": "2023-06-01T12:00:00Z", "fields": [ { "id": "field_123", "name": "signature", "type": "signature", "x": 100, "y": 200, "page": 1 }, { "id": "field_456", "name": "date", "type": "date", "x": 300, "y": 200, "page": 1 } ], "file_url": "https://api.docurecorded.com/v1/templates/template_123456789/file" }
The Signatures API allows you to retrieve and manage signatures.
Lists all signatures for a document.
Parameter | Type | Required | Description |
---|---|---|---|
document_id | string | Yes | The ID of the document. |
curl -X GET https://api.docurecorded.com/v1/documents/doc_123456789/signatures \ -H "Authorization: Bearer YOUR_API_KEY"
{ "data": [ { "id": "signature_123", "signer_id": "signer_123", "signer_name": "John Doe", "signer_phone": "+15551234567", "status": "completed", "signed_at": "2023-06-01T14:00:00Z", "ip_address": "192.168.1.1" }, { "id": "signature_456", "signer_id": "signer_456", "signer_name": "Jane Smith", "signer_phone": "+15557654321", "status": "pending", "signed_at": null, "ip_address": null } ] }
The Users API allows you to manage users in your account.
Lists all users in your account.
curl -X GET https://api.docurecorded.com/v1/users \ -H "Authorization: Bearer YOUR_API_KEY"
{ "data": [ { "id": "user_123", "name": "John Doe", "phone": "+15551234567", "role": "admin", "created_at": "2023-01-01T00:00:00Z" }, { "id": "user_456", "name": "Jane Smith", "phone": "+15557654321", "role": "user", "created_at": "2023-02-01T00:00:00Z" } ] }
Creates a new user.
Parameter | Type | Required | Description |
---|---|---|---|
name | string | Yes | The name of the user. |
phone | string | Yes | The phone number of the user. |
role | string | No | The role of the user (admin, user). Default: user. |
curl -X POST https://api.docurecorded.com/v1/users \ -H "Authorization: Bearer YOUR_API_KEY" \ -d "name=John Doe" \ -d "phone=+15551234567" \ -d "role=user"
{ "id": "user_789", "name": "John Doe", "phone": "+15551234567", "role": "user", "created_at": "2023-06-01T12:00:00Z" }
Webhooks allow you to receive real-time notifications about events in your DocuRecorded account.
Creates a new webhook endpoint.
Parameter | Type | Required | Description |
---|---|---|---|
url | string | Yes | The URL of your webhook endpoint. |
events | array | Yes | An array of event types to subscribe to. |
curl -X POST https://api.docurecorded.com/v1/webhooks \ -H "Authorization: Bearer YOUR_API_KEY" \ -d "url=https://example.com/webhook" \ -d "events[]=document.signed" \ -d "events[]=document.viewed"
{ "id": "webhook_123", "url": "https://example.com/webhook", "events": ["document.signed", "document.viewed"], "created_at": "2023-06-01T12:00:00Z" }
Events are notifications about activities in your DocuRecorded account. You can subscribe to these events using webhooks.
Event | Description |
---|---|
document.created | Triggered when a new document is created. |
document.sent | Triggered when a document is sent for signature. |
document.viewed | Triggered when a signer views a document. |
document.signed | Triggered when a document is signed. |
document.completed | Triggered when all signers have signed a document. |