API Overview

The DocuTrust API is a RESTful JSON API for creating templates, managing submissions, and integrating document signing into your applications.

Base URL

All API requests are made to your DocuTrust instance URL:

https://your-app.com/api

Replace your-app.com with your actual DocuTrust deployment domain.

Authentication

Authenticate every request by including your API token in the X-Auth-Token header:

curl -X GET https://your-app.com/api/templates \
  -H "X-Auth-Token: YOUR_API_TOKEN"

API tokens are created in Settings > API within the DocuTrust admin panel. Each token can be scoped to specific permissions. See the Authentication guide for details on creating and managing tokens.

Never expose your API token in client-side code, public repositories, or browser requests. API tokens should only be used in server-to-server communication.

Content Types

Scenario	Content-Type
JSON requests (most endpoints)	`application/json`
File uploads	`multipart/form-data`
Responses	`application/json`

All request bodies must be valid JSON unless the endpoint accepts file uploads, in which case multipart/form-data is used.

Rate Limits

API requests are rate-limited to 120 requests per minute per API token.

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed per window (120).
`X-RateLimit-Remaining`	Number of requests remaining in the current window.
`X-RateLimit-Reset`	Unix timestamp when the rate limit window resets.

When the limit is exceeded, the API returns 429 Too Many Requests:

{
  "error": "Rate limit exceeded. Retry after 23 seconds."
}

The Retry-After header indicates the number of seconds to wait before retrying.

Pagination

List endpoints use cursor-based pagination for consistent results even when data is being created or deleted between pages.

Request Parameters

Parameter	Type	Default	Description
`after`	string	—	Return records after this cursor. Obtained from the `pagination.next` field of a previous response.
`before`	string	—	Return records before this cursor. Obtained from the `pagination.prev` field of a previous response.
`limit`	integer	10	Number of records per page. Minimum: 1. Maximum: 100.

Response Format

{
  "data": [
    {
      "id": 1,
      "name": "Employment Agreement"
    },
    {
      "id": 2,
      "name": "Non-Disclosure Agreement"
    }
  ],
  "pagination": {
    "next": "eyJpZCI6Mn0",
    "prev": null
  }
}

Field	Type	Description
`data`	array	The list of records for the current page.
`pagination.next`	string or null	Cursor to fetch the next page. Null if there are no more records.
`pagination.prev`	string or null	Cursor to fetch the previous page. Null if this is the first page.

Pass the next cursor as the after parameter to fetch the next page:

curl -X GET "https://your-app.com/api/templates?after=eyJpZCI6Mn0&limit=10" \
  -H "X-Auth-Token: YOUR_API_TOKEN"

Error Handling

All errors return a JSON object with an error field containing a human-readable message:

{
  "error": "Template not found"
}

HTTP Status Codes

Status Code	Meaning	When It Occurs
`200 OK`	Success	The request completed successfully.
`201 Created`	Resource created	A new resource was created (e.g., template, submission).
`204 No Content`	Success, no body	The request completed successfully with no response body (e.g., DELETE).
`400 Bad Request`	Invalid request	The request body is malformed or missing required fields.
`401 Unauthorized`	Authentication failed	The API token is missing, invalid, or expired.
`403 Forbidden`	Insufficient permissions	The API token does not have the required scope for this endpoint.
`404 Not Found`	Resource not found	The requested resource does not exist or is not accessible to this token.
`409 Conflict`	Conflict detected	The request conflicts with the current state (e.g., concurrent update detected).
`422 Unprocessable Entity`	Validation failed	The request body is valid JSON but contains invalid field values.
`429 Too Many Requests`	Rate limit exceeded	Too many requests in the current time window.
`500 Internal Server Error`	Server error	An unexpected error occurred on the server. Contact support if this persists.

Validation Errors

For 422 responses, the error message describes which field failed validation:

{
  "error": "Submitter email is invalid"
}

Versioning

The DocuTrust API is currently at version 1. There is no version prefix in the URL — all endpoints are accessible directly under /api/.

https://your-app.com/api/templates
https://your-app.com/api/submissions
https://your-app.com/api/submitters

Breaking Changes Policy

Breaking changes will be announced at least 90 days in advance via email and the changelog.
Non-breaking additions (new fields in responses, new optional parameters, new endpoints) are made without a version bump.
When a new API version is introduced, the previous version will remain available for a deprecation period of at least 12 months.

Request IDs

Every API response includes an X-Request-Id header containing a unique identifier for the request. Include this ID when contacting support about a specific request:

X-Request-Id: req_a1b2c3d4e5f6

Webhooks

DocuTrust can send real-time notifications to your server when events occur (e.g., a submission is completed, a submitter opens a document). Webhook payloads are signed with HMAC-SHA256 for verification. See the Webhooks guide for configuration details.

Overview

Partner API

Templates

Thumbnails

Submissions

Submitters

Users

Access Tokens

Webhooks

Settings

Custom Domains

Teams

Audit Events

MFA

BAA

Security Events

Subscriptions

Plans

Payments

Verification

KBA

AI

Embed

Health

API Overview

API Overview

Base URL

Authentication

Content Types

Rate Limits

Request Parameters

Response Format

Error Handling

HTTP Status Codes

Validation Errors

Versioning

Breaking Changes Policy

Request IDs

Webhooks

​API Overview

​Base URL

​Authentication

​Content Types

​Rate Limits

​Pagination

​Request Parameters

​Response Format

​Error Handling

​HTTP Status Codes

​Validation Errors

​Versioning

​Breaking Changes Policy

​Request IDs

​Webhooks

API Overview

Base URL

Authentication

Content Types

Rate Limits

Pagination

Request Parameters

Response Format

Error Handling

HTTP Status Codes

Validation Errors

Versioning

Breaking Changes Policy

Request IDs

Webhooks