The ClearPolicy API exposes three endpoints for managing people — the contacts in your organization who receive attestation requests. All people endpoints are scoped to the organization your access token belongs to.
List people
GET https://api.clearpolicy.app/v1/people
Query parameters
Filter by the exact ULID of a person. When provided, returns a non-paginated collection containing only that person (or an empty array if not found).
Filter people whose name contains this value (case-insensitive partial match).
Filter people whose email contains this value (case-insensitive partial match).
Filter people whose phone number contains this value (partial match).
When set to true or 1, returns only archived people. When omitted or false, returns only active people.
Number of results per page. Must be between 1 and 100.
Example request
curl "https://api.clearpolicy.app/v1/people?per_page=10&page=1" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Example response
{
"data": [
{
"id": "01kg82xqfx6fvr046d15hnfmjv",
"organization_id": "01jz91kq3m0gar5btepwxvncde",
"name": "Jane Smith",
"email": "jane.smith@example.com",
"phone": "+12025550147",
"source": "oauth",
"source_id": null,
"archived_at": null,
"created_at": "2024-01-01T00:00:00.000000Z",
"updated_at": "2024-01-01T00:00:00.000000Z"
}
],
"links": {
"first": "https://api.clearpolicy.app/v1/people?page=1",
"last": "https://api.clearpolicy.app/v1/people?page=5",
"prev": null,
"next": "https://api.clearpolicy.app/v1/people?page=2"
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 5,
"per_page": 10,
"to": 10,
"total": 47
}
}
Create a person
POST https://api.clearpolicy.app/v1/people
201 Created status.
Body parameters
The full name of the person.
The email address of the person. Must be unique within your organization.
The phone number of the person. Must be in international format (e.g. +12025550147).
Example request
curl https://api.clearpolicy.app/v1/people \
-X POST \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Jane Smith",
"email": "jane.smith@example.com",
"phone": "+12025550147"
}'
Example response
{
"id": "01kg82xqfx6fvr046d15hnfmjv",
"organization_id": "01jz91kq3m0gar5btepwxvncde",
"name": "Jane Smith",
"email": "jane.smith@example.com",
"phone": "+12025550147",
"source": "oauth",
"source_id": null,
"archived_at": null,
"created_at": "2024-06-15T10:30:00.000000Z",
"updated_at": "2024-06-15T10:30:00.000000Z"
}
Get a person
GET https://api.clearpolicy.app/v1/people/{id}
404 is returned.
Path parameters
The ULID of the person to retrieve.
Example request
curl https://api.clearpolicy.app/v1/people/01kg82xqfx6fvr046d15hnfmjv \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Example response
{
"id": "01kg82xqfx6fvr046d15hnfmjv",
"organization_id": "01jz91kq3m0gar5btepwxvncde",
"name": "Jane Smith",
"email": "jane.smith@example.com",
"phone": "+12025550147",
"source": "oauth",
"source_id": null,
"archived_at": null,
"created_at": "2024-06-15T10:30:00.000000Z",
"updated_at": "2024-06-15T10:30:00.000000Z"
}
Person object
The ULID of the organization the person belongs to.
The full name of the person.
The email address of the person.
The phone number in international format, or null if not set.
How the person was created. For people created via the API, this is "oauth".
An optional external identifier from the originating system, or null.
ISO 8601 timestamp of when the person was archived, or null if active.
ISO 8601 timestamp of when the person was created.
ISO 8601 timestamp of the last update.
