{ "openapi": "3.1.0", "info": { "title": "ClearPolicy API", "description": "Access your organization's people, groups, documents, and document requests. API tokens are organization-scoped and require an active trial or subscription. Owners and administrators can use all listed endpoints; Group Manager tokens can use GET /me but receive 403 on the other endpoints.\n\nEach API token is limited to 60 requests per minute. Respect Retry-After on 429 responses and use the X-RateLimit-* headers to track the allowance.", "version": "1.0.0" }, "servers": [ { "url": "https://api.clearpolicy.app/api/v1" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/me": { "get": { "summary": "Get current user", "description": "Returns the authenticated user and their current organization.", "operationId": "getMe", "tags": [ "Me" ], "responses": { "200": { "description": "The authenticated user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/people": { "get": { "summary": "List people", "description": "Returns a paginated list of people in your organization. Supports filtering by name, email, phone, and archived status.", "operationId": "listPeople", "tags": [ "People" ], "parameters": [ { "name": "id", "in": "query", "description": "Filter by exact ULID. When provided, returns a non-paginated array containing only that person (or an empty array).", "schema": { "type": "string" } }, { "name": "name", "in": "query", "description": "Filter by name (case-insensitive partial match).", "schema": { "type": "string", "maxLength": 255 } }, { "name": "email", "in": "query", "description": "Filter by email (case-insensitive partial match).", "schema": { "type": "string", "maxLength": 255 } }, { "name": "phone", "in": "query", "description": "Filter by phone number (partial match).", "schema": { "type": "string", "maxLength": 50 } }, { "name": "archived", "in": "query", "description": "When `true` or `1`, returns only archived people. When omitted or `false`, returns only active people.", "schema": { "type": "string", "enum": [ "true", "false", "1", "0" ], "default": "false" } }, { "name": "per_page", "in": "query", "description": "Number of results per page (1\u2013100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "page", "in": "query", "description": "Page number to retrieve.", "schema": { "type": "integer", "minimum": 1, "default": 1 } } ], "responses": { "200": { "description": "A paginated list of people.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedPeople" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "summary": "Add a person", "description": "Adds a person to your organization. Provide last_name and email; first_name and phone are optional. This does not send a team invitation or a document request.", "operationId": "createPerson", "tags": [ "People" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePersonRequest" } } } }, "responses": { "201": { "description": "The created person.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Person" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/people/{id}": { "get": { "summary": "Get a person", "description": "Returns a single person by their ULID.", "operationId": "getPerson", "tags": [ "People" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The ULID of the person.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The requested person.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Person" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/documents": { "get": { "summary": "List documents", "description": "Returns a paginated list of documents in your organization. Supports filtering by name and archived status.", "operationId": "listDocuments", "tags": [ "Documents" ], "parameters": [ { "name": "name", "in": "query", "description": "Filter by document name (case-insensitive partial match).", "schema": { "type": "string", "maxLength": 255 } }, { "name": "archived", "in": "query", "description": "When `true` or `1`, returns only archived documents. When omitted or `false`, returns only active documents.", "schema": { "type": "string", "enum": [ "true", "false", "1", "0" ], "default": "false" } }, { "name": "per_page", "in": "query", "description": "Number of results per page (1\u2013100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "page", "in": "query", "description": "Page number to retrieve.", "schema": { "type": "integer", "minimum": 1, "default": 1 } } ], "responses": { "200": { "description": "A paginated list of documents.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedDocuments" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/groups": { "get": { "summary": "List groups", "description": "Returns a paginated list of groups in your organization, ordered by name ascending.", "operationId": "listGroups", "tags": [ "Groups" ], "parameters": [ { "name": "per_page", "in": "query", "description": "Number of results per page (1\u2013100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "page", "in": "query", "description": "Page number to retrieve.", "schema": { "type": "integer", "minimum": 1, "default": 1 } } ], "responses": { "200": { "description": "A paginated list of groups.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedGroups" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/groups/{group}/people": { "post": { "summary": "Add people to a group", "description": "Adds one or more active people to a group. People who are already members are accepted and returned without error. The response always uses status 200 and lists one membership object per requested person ID, in the same order as the request.\n\nAdding people may assign the group's documents to them. When the group has automatic request issuance enabled, ClearPolicy creates signature requests for newly assigned published documents and sends grouped notification emails asynchronously.", "operationId": "addGroupPeople", "tags": [ "Groups" ], "parameters": [ { "name": "group", "in": "path", "required": true, "description": "The ULID of the group.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddGroupPeopleRequest" } } } }, "responses": { "200": { "description": "Memberships for the requested people (including any who were already members).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupMembershipList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/groups/{group}/people/{person}": { "delete": { "summary": "Remove a person from a group", "description": "Removes one person from a group. The person must already be a member; otherwise the API returns 404. Document assignments created earlier via the group are not automatically removed.", "operationId": "removeGroupPerson", "tags": [ "Groups" ], "parameters": [ { "name": "group", "in": "path", "required": true, "description": "The ULID of the group.", "schema": { "type": "string" } }, { "name": "person", "in": "path", "required": true, "description": "The ULID of the person to remove.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "The person was removed from the group." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/attestation-requests": { "post": { "summary": "Send an attestation request", "description": "Sends a published document to a person for electronic signature (typed name). New requests are always signature; historical rows may still show acknowledgment as a read-only type. A document that does not require a signature cannot be sent. That request returns 422.", "operationId": "createAttestationRequest", "tags": [ "Attestation Requests" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAttestationRequestBody" } } } }, "responses": { "201": { "description": "The created attestation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttestationRequest" } } } }, "400": { "description": "The document has no published revision.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } } }, "components": { "schemas": { "Me": { "type": "object", "required": [ "id", "name", "email", "current_organization_name" ], "properties": { "id": { "type": "string", "description": "The ULID of the authenticated user." }, "name": { "type": "string", "description": "The full name of the user." }, "email": { "type": "string", "format": "email", "description": "The email address of the user." }, "current_organization_name": { "type": "string", "description": "The name of the organization the token belongs to." } } }, "Person": { "type": "object", "required": [ "id", "organization_id", "first_name", "last_name", "name", "email", "source", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "description": "The ULID of the person." }, "organization_id": { "type": "string", "description": "The ULID of the organization." }, "first_name": { "type": ["string", "null"], "description": "The person's first name, if provided." }, "last_name": { "type": "string", "description": "The person's last name." }, "name": { "type": "string", "description": "The full name assembled from first_name and last_name." }, "email": { "type": "string", "format": "email", "description": "The email address of the person." }, "phone": { "type": [ "string", "null" ], "description": "The phone number in international format, or null." }, "source": { "type": "string", "enum": [ "oauth", "web", "system", "planning_center" ], "description": "How the person was created." }, "source_id": { "type": [ "string", "null" ], "description": "An external identifier from the originating system, or null." }, "archived_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the person was archived, or null if active." }, "created_at": { "type": "string", "format": "date-time", "description": "When the person was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "When the person was last updated." } } }, "CreatePersonRequest": { "type": "object", "required": [ "last_name", "email" ], "properties": { "first_name": { "type": ["string", "null"], "maxLength": 255, "description": "The person's first name. Optional." }, "last_name": { "type": "string", "maxLength": 255, "description": "The person's last name. Required." }, "email": { "type": "string", "format": "email", "maxLength": 255, "description": "The email address. Must be unique within your organization." }, "phone": { "type": ["string", "null"], "description": "Phone number in international format (e.g. +12025550147)." } } }, "Document": { "type": "object", "required": [ "id", "organization_id", "name", "default_attestation_type", "requires_signature", "has_published_revision", "attestation_counts", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "description": "The ULID of the document." }, "organization_id": { "type": "string", "description": "The ULID of the organization." }, "name": { "type": "string", "description": "The name of the document." }, "default_attestation_type": { "type": "string", "enum": [ "acknowledgment", "signature" ], "description": "Document default attestation type. New documents and writes always use signature. acknowledgment may appear on historical documents only." }, "requires_signature": { "type": "boolean", "description": "Whether people must sign this document. Returned on list and read. The API cannot set this field yet. When false, people in a group that includes the published document can read it in the signing portal. They are not asked to sign. Sending an attestation request for that document returns 422." }, "renewal_interval_days": { "type": [ "integer", "null" ], "description": "Number of days before attestations must be renewed, or null." }, "auto_renew": { "type": "boolean", "description": "Whether attestation requests are automatically re-issued on renewal." }, "archived_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the document was archived, or null if active." }, "has_published_revision": { "type": "boolean", "description": "Whether the document has at least one published revision." }, "last_updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the latest revision was published, or null." }, "attestation_counts": { "$ref": "#/components/schemas/AttestationCounts" }, "created_at": { "type": "string", "format": "date-time", "description": "When the document was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "When the document was last updated." } } }, "AttestationCounts": { "type": "object", "required": [ "attested_latest", "pending_attested", "attested_outdated", "unrequested", "renewal_due", "total" ], "properties": { "attested_latest": { "type": "integer", "description": "People who have attested to the latest revision." }, "pending_attested": { "type": "integer", "description": "People with a pending attestation request." }, "attested_outdated": { "type": "integer", "description": "People who attested to an older revision." }, "unrequested": { "type": "integer", "description": "People who have not been sent an attestation request." }, "renewal_due": { "type": "integer", "description": "People whose attestation renewal is due." }, "total": { "type": "integer", "description": "Total number of people assigned to this document." } } }, "AttestationRequest": { "type": "object", "required": [ "id", "organization_id", "document_id", "document_revision_id", "person_id", "recipient_name", "recipient_email", "requested_attestation_type", "source", "status", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "description": "The ULID of the attestation request." }, "organization_id": { "type": "string", "description": "The ULID of the organization." }, "document_id": { "type": "string", "description": "The ULID of the document being attested." }, "document_revision_id": { "type": "string", "description": "The ULID of the published revision that was sent." }, "person_id": { "type": "string", "description": "The ULID of the person the request was sent to." }, "recipient_name": { "type": "string", "description": "The name of the recipient when the request was created." }, "recipient_email": { "type": "string", "format": "email", "description": "The email of the recipient when the request was created." }, "requested_attestation_type": { "type": "string", "enum": [ "acknowledgment", "signature" ], "description": "Attestation type frozen on this request. New requests are always signature. acknowledgment is historical (read-only)." }, "recipient_message": { "type": [ "string", "null" ], "description": "The message included with the request that appears in emails and on the attestation page, or null if none was provided." }, "sent_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the request was sent, or null." }, "last_reminded_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the most recent reminder was sent, or null." }, "viewed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the recipient first viewed the request, or null." }, "attested_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the recipient completed the attestation, or null." }, "canceled_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the request was canceled, or null." }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the request is scheduled to expire, or null." }, "expired_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the request expired, or null." }, "requested_by_user_id": { "type": [ "string", "null" ], "description": "The ULID of the user whose API token issued this request." }, "source": { "type": "string", "enum": [ "oauth", "web", "system", "planning_center" ], "description": "How the request was created." }, "status": { "type": "string", "enum": [ "created", "sent", "viewed", "attested", "canceled", "expired", "bounced", "failed", "complained" ], "description": "The current status of the request. Delivery problem statuses (bounced, failed, complained) apply to pending requests whose latest email could not be delivered." }, "created_at": { "type": "string", "format": "date-time", "description": "When the request was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "When the request was last updated." } } }, "CreateAttestationRequestBody": { "type": "object", "required": [ "person_id", "document_id" ], "properties": { "person_id": { "type": "string", "description": "The ULID of the person to send the request to." }, "document_id": { "type": "string", "description": "The ULID of the document to send. Must have a published revision." }, "requested_attestation_type": { "type": "string", "enum": [ "signature" ], "deprecated": true, "description": "Deprecated. Ignored if sent. New requests always use signature (typed-name electronic signature). acknowledgment is not accepted for writes." }, "recipient_message": { "type": "string", "maxLength": 5000, "description": "An optional message to include with the request. This message appears in the emails sent for document requests and on the attestation page." } } }, "PaginatedPeople": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Person" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "PaginatedDocuments": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Document" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "PaginationLinks": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } } }, "PaginationMeta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "from": { "type": [ "integer", "null" ] }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "to": { "type": [ "integer", "null" ] }, "total": { "type": "integer" } } }, "Error": { "type": "object", "properties": { "error": { "type": "string", "description": "A human-readable error message." } } }, "Group": { "type": "object", "required": [ "id", "organization_id", "name", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "description": "The ULID of the group." }, "organization_id": { "type": "string", "description": "The ULID of the organization." }, "name": { "type": "string", "description": "The name of the group." }, "created_at": { "type": "string", "format": "date-time", "description": "When the group was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "When the group was last updated." } } }, "PaginatedGroups": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Group" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "AddGroupPeopleRequest": { "type": "object", "required": [ "person_ids" ], "properties": { "person_ids": { "type": "array", "minItems": 1, "maxItems": 100, "description": "Distinct ULIDs of active (non-archived) people in your organization to add to the group.", "items": { "type": "string" } } } }, "GroupMembership": { "type": "object", "required": [ "group_id", "person_id" ], "properties": { "group_id": { "type": "string", "description": "The ULID of the group." }, "person_id": { "type": "string", "description": "The ULID of the person." } } }, "GroupMembershipList": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GroupMembership" }, "description": "One membership per requested person_id, in request order." } } } }, "responses": { "Unauthorized": { "description": "Missing or invalid access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "PaymentRequired": { "description": "Trial expired or subscription inactive.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "payment_url": { "type": "string", "format": "uri" } } } } } }, "Forbidden": { "description": "The token or team member does not have permission for this action. Group Manager tokens can use GET /me but cannot use the other REST endpoints.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "NotFound": { "description": "The requested resource was not found in your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ValidationError": { "description": "Validation failed, or the action is unavailable for the selected resource. Validation responses use message and errors; action errors can use error instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "An action-specific error, such as requesting a signature on a document with signatures off." }, "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } } } } }, "TooManyRequests": { "description": "Rate limit exceeded. Each API token is limited to 60 requests per minute.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 42 } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed per minute for this token.", "schema": { "type": "integer", "example": 60 } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "Unix timestamp when the rate limit resets.", "schema": { "type": "integer", "example": 1719532800 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } } } } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Bearer token created in ClearPolicy API settings with the `api:use` scope." } } } }