ClearPolicy REST API overview

The ClearPolicy REST API communicates over HTTPS and returns JSON. Learn the base URL, versioning, pagination format, ID format, and error responses.

The ClearPolicy REST API gives you programmatic access to your organization’s people, groups, documents, and attestation requests. All endpoints communicate over HTTPS and return JSON.

Base URL

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

The API path prefix (/api/v1) is included in every request URL. The current and only version is v1.

Authentication

All endpoints require a valid API bearer token. Pass the token in the Authorization header:

Authorization: Bearer YOUR_ACCESS_TOKEN

See Authentication for instructions on creating a token.

Your organization must have an active subscription or be within its trial period. If your trial has expired or your subscription is inactive, all API requests return a 402 Payment Required response.

Access by role

API access follows your ClearPolicy role. Organization owners and administrators can create API tokens and use the people, groups, documents, and attestation request endpoints. Tokens tied to Group Managers can use GET /me to confirm the token and organization, but other REST API endpoints return 403 Forbidden.

Response format

All responses are JSON. Successful responses return the requested resource or collection directly in the response body.

IDs

All resource IDs are ULIDs — lexicographically sortable string identifiers. They are represented as lowercase strings, for example:

01kg82xqfx6fvr046d15hnfmjv

Pagination

List endpoints return paginated results. The response includes a data array alongside links and meta objects:

{
  "data": [...],
  "links": {
    "first": "https://api.clearpolicy.app/api/v1/people?page=1",
    "last": "https://api.clearpolicy.app/api/v1/people?page=5",
    "prev": null,
    "next": "https://api.clearpolicy.app/api/v1/people?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,
    "per_page": 25,
    "to": 25,
    "total": 120
  }
}

Use the page and per_page query parameters to navigate results. per_page accepts values between 1 and 100, and defaults to 25.

Errors

Errors return JSON with an error field describing the problem:

{
  "error": "Person not found."
}

Common HTTP status codes:

Status	Meaning
200 OK	Request succeeded.
201 Created	Resource created successfully.
400 Bad Request	The request was invalid (e.g. document not published).
401 Unauthorized	Missing or invalid access token.
402 Payment Required	Your organization’s trial has expired or subscription is inactive. Visit your billing page to subscribe.
403 Forbidden	Token lacks required permissions.
404 Not Found	The requested resource does not exist in your organization.
422 Unprocessable Entity	Validation failed — check request parameters.
429 Too Many Requests	Rate limit exceeded — wait and retry.

Rate limiting

Each API token is limited to 60 requests per minute. Limits apply per token, not per organization, so multiple tokens each have their own allowance.

If you exceed the limit, the API returns 429 Too Many Requests. Responses include Retry-After and X-RateLimit-* headers so you can tell when to retry. Use exponential backoff when retrying.