API Documentation

Integrate DocuRecorded's electronic signature capabilities into your applications.

Getting Started

Resources

Webhooks

Introduction

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.

Base URL

All API requests should be made to the following base URL:

https://api.docurecorded.com/v1

API Versions

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.

Rate Limiting

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.

Authentication

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

API Key Security

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.

Error Handling

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.

HTTP Status Codes

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.

Error Response Format

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

Documents

The Documents API allows you to create, retrieve, update, and delete documents.

POST /documents

Creates a new document.

Request Parameters

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).

Example Request

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"

Response

{
  "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"
}
GET /documents/{document_id}

Retrieves a document by ID.

Path Parameters

Parameter Type Required Description
document_id string Yes The ID of the document to retrieve.

Example Request

curl -X GET https://api.docurecorded.com/v1/documents/doc_123456789 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "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"
}
GET /documents

Lists all documents.

Query Parameters

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).

Example Request

curl -X GET "https://api.docurecorded.com/v1/documents?limit=5&status=sent" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

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

Templates

The Templates API allows you to create, retrieve, update, and delete document templates.

POST /templates

Creates a new template.

Request Parameters

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.

Example Request

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"

Response

{
  "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"
}
GET /templates/{template_id}

Retrieves a template by ID.

Path Parameters

Parameter Type Required Description
template_id string Yes The ID of the template to retrieve.

Example Request

curl -X GET https://api.docurecorded.com/v1/templates/template_123456789 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

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

Signatures

The Signatures API allows you to retrieve and manage signatures.

GET /documents/{document_id}/signatures

Lists all signatures for a document.

Path Parameters

Parameter Type Required Description
document_id string Yes The ID of the document.

Example Request

curl -X GET https://api.docurecorded.com/v1/documents/doc_123456789/signatures \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

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

Users

The Users API allows you to manage users in your account.

GET /users

Lists all users in your account.

Example Request

curl -X GET https://api.docurecorded.com/v1/users \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "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"
    }
  ]
}
POST /users

Creates a new user.

Request Parameters

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.

Example Request

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"

Response

{
  "id": "user_789",
  "name": "John Doe",
  "phone": "+15551234567",
  "role": "user",
  "created_at": "2023-06-01T12:00:00Z"
}

Webhooks

Webhooks allow you to receive real-time notifications about events in your DocuRecorded account.

POST /webhooks

Creates a new webhook endpoint.

Request Parameters

Parameter Type Required Description
url string Yes The URL of your webhook endpoint.
events array Yes An array of event types to subscribe to.

Example Request

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"

Response

{
  "id": "webhook_123",
  "url": "https://example.com/webhook",
  "events": ["document.signed", "document.viewed"],
  "created_at": "2023-06-01T12:00:00Z"
}

Events

Events are notifications about activities in your DocuRecorded account. You can subscribe to these events using webhooks.

Available Events

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.