> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clearpolicy.app/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API overview

> Use the ClearPolicy REST API for people, groups, documents, and signature requests. Review access, pagination, errors, and rate limits.

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

```text theme={null}
https://api.clearpolicy.app/api/v1
```

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

## Authentication

[Create an API token](/api/authentication) 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](/guides/manage-groups#automatic-request-emails).

## 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.

```json theme={null}
{
  "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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.