REST API overview

The ClearPolicy REST API returns JSON over HTTPS. It supports listing and adding people, listing documents and groups, changing group membership, and sending document requests.

Base URL

https://api.clearpolicy.app/api/v1

Include /api/v1 in every request. The supported version is v1.

Authentication

Create an API token and send it in the Authorization header. Include Accept: application/json, and Content-Type: application/json when sending JSON. All REST endpoints require an active trial or subscription for the token’s organization. Without it, requests return 402 Payment Required.

Access by role

Owners and administrators can use the REST endpoints. A token tied to a Group Manager can confirm its identity and organization through GET /me; other REST endpoints return 403 Forbidden. Tokens are organization-scoped. Use IDs from the same organization as the token.

Supported endpoints

Method and path	Purpose
`GET /me`	Confirm the authenticated account and organization.
`GET /people`	List or search people.
`POST /people`	Add a person.
`GET /people/{id}`	Read a person.
`GET /documents`	List documents.
`GET /groups`	List groups.
`POST /groups/{group}/people`	Add people to a group.
`DELETE /groups/{group}/people/{person}`	Remove a person’s group membership.
`POST /attestation-requests`	Send a document request.

Use the endpoint pages in API Reference for request and response fields.

Sending a document request

Provide a person_id and document_id from the connected organization. The document must be published and require a signature. New requests collect typed-name signatures; historical responses can still contain acknowledgment values. Sending a document with requires_signature: false returns 422. Change the setting in the app if a signature is needed. The REST API does not change that setting. Adding group membership can also send requests when automatic group emails are enabled. See group behavior.

Response format

Single-resource responses contain that resource’s fields. Paginated lists have data, links, and meta. Check the endpoint reference for non-paginated variants, such as filtering people by an exact ID.

IDs

Resource IDs are lowercase ULID strings, such as 01kg82xqfx6fvr046d15hnfmjv. Treat them as strings, not numbers.

Pagination

Use page and per_page. Page size defaults to 25, with a maximum of 100. Paginated responses provide the current page in meta.current_page and the next-page URL in links.next. Continue until links.next is null. For people and documents, archived=true selects only archived records; omitting it selects active records. It does not combine active and archived results.

Errors

Status	Meaning and recovery
`400 Bad Request`	The action cannot be completed, such as sending an unpublished document. Correct the document or request.
`401 Unauthorized`	Token missing, invalid, expired, or revoked.
`402 Payment Required`	Update the organization’s billing access.
`403 Forbidden`	Check role and token permissions.
`404 Not Found`	The resource is unavailable in the token’s organization.
`422 Unprocessable Entity`	Invalid fields or an unsupported action, such as requesting a signature on a document with signatures off.
`429 Too Many Requests`	Wait for `Retry-After`, then retry.

Some action errors use an error field. Validation errors can use message and field-specific errors. Handle the HTTP status and the returned body rather than assuming every error has the same shape.

{
  "message": "The email field is required.",
  "errors": {
    "email": ["The email field is required."]
  }
}

Rate limiting

Each API token is limited to 60 requests per minute. Inspect X-RateLimit-* headers and respect Retry-After on a 429 response. Use backoff when retrying.

Overview

Me

People

Documents

Groups

Attestation requests

Base URL

Authentication

Access by role

Supported endpoints

Sending a document request

Response format

IDs

Errors

Rate limiting

​Base URL

​Authentication

​Access by role

​Supported endpoints

​Sending a document request

​Response format

​IDs

​Pagination

​Errors

​Rate limiting

Base URL

Authentication

Access by role

Supported endpoints

Sending a document request

Response format

IDs

Pagination

Errors

Rate limiting