The Safeclose API is a JSON REST API. Every endpoint sits under the /v1/ path prefix, requires a Bearer token for authentication, and returns JSON for both successful responses and errors. This page covers the conventions you need to understand before making your first request.
Base URL
Your API base URL is the URL of your Safeclose API service. All examples in this reference use a placeholder:
https://your-api.example.com
{ "service": "safeclose-api" }:
curl https://your-api.example.com/health
{
"ok": true,
"service": "safeclose-api",
"ts": "2026-04-27T00:00:00.000Z"
}
If you receive an HTML response instead of JSON, your base URL likely points at the Safeclose web app instead of the API service. Make sure you are using the correct API host URL — the health endpoint at /health should return { "service": "safeclose-api" }.
Versioning
All API endpoints are prefixed with /v1/. The current version is v1. Include the version prefix in every request path:
https://your-api.example.com/v1/signing/session
Authentication
Every /v1/ endpoint requires a Bearer token in the Authorization header. The token is a Clerk JWT session token obtained from an authenticated Safeclose session.
Authorization: Bearer <your-session-token>
Content type
Send Content-Type: application/json for any request that includes a body. The API returns application/json for all responses, including errors.
Content-Type: application/json
Error format
When a request fails, the API returns a JSON object with a single error field describing what went wrong:
{
"error": "Missing Authorization Bearer token."
}
error string for a human-readable explanation.
HTTP status codes
| Code | Name | When you’ll see it |
|---|
200 | OK | Successful read or action |
201 | Created | Resource successfully created |
204 | No Content | Successful deletion; response body is empty |
400 | Bad Request | Invalid request body or missing required parameters |
401 | Unauthorized | Authorization header is missing, malformed, or the token is expired |
403 | Forbidden | Token is valid but your role does not have permission to access this resource |
404 | Not Found | Resource does not exist or is not visible to your account |
409 | Conflict | Resource is already in the target state (for example, cancelling a signing that is already cancelled) |
503 | Service Unavailable | A required service dependency is not available (for example, the comments feature requires the real-time service to be enabled) |
Rate limiting
Rate limiting is managed at the infrastructure level. Contact your organization administrator for details.
Available API resources
| Group | Base path | Description |
|---|
| Signing — session | /v1/signing/ | Retrieve your signing session, RBAC capabilities, and role assignments |
| Signing — signer queue | /v1/signing/signer/ | Access assigned signing packages, documents, and co-signers; record e-signatures |
| Signing — manager signings | /v1/signing/manager/ | Create and manage signing packages, view locations, companies, and organizations |
| Signing — templates and flows | /v1/signing/manager/ | List and update signing templates and flows |
| Documents | /v1/documents/ | Create, list, update, and delete chattel documents; manage comments and RCM outreach |
| Workspace | /v1/workspace/ | Query organization memberships and workspace settings |
Health endpoints
Two unauthenticated endpoints are available for infrastructure probes:
| Endpoint | Description |
|---|
GET /health | Returns { "ok": true, "service": "safeclose-api", "ts": "<iso-timestamp>" }. Always returns 200 when the process is running. |
GET /ready | Returns { "ready": true } when the database connection is reachable, or 503 { "ready": false } if it is not. |
The health endpoints do not require an Authorization header. Use /health for liveness probes and /ready for readiness probes.
