Safeclose API: conventions, errors, and resources

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

Replace this with your actual API host. You can confirm the correct URL by calling the health endpoint — it returns { "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>

See Authenticate requests for full details on obtaining and using tokens.

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

The HTTP status code indicates the category of failure. Parse the 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.

​Base URL

​Versioning

​Authentication

​Content type

​Error format

​HTTP status codes

​Rate limiting

​Available API resources

​Health endpoints

Base URL

Versioning

Authentication

Content type

Error format

HTTP status codes

Rate limiting

Available API resources

Health endpoints