openapi: 3.0.3 info: title: 'ClearPolicy API Documentation' description: 'This documentation provides a reference to the API endpoints, including example requests and responses.' version: 1.0.0 servers: - url: 'https://api.clearpolicy.app' tags: - name: 'Attestation Requests' description: "\nAPIs for managing attestation requests." - name: Documents description: "\nAPIs for managing documents." - name: Endpoints description: '' - name: People description: "\nAPIs for managing people." components: securitySchemes: default: type: http scheme: bearer description: 'You can retrieve your token by visiting your dashboard and clicking Generate API token.' security: - default: [] paths: /api/v1/attestation-requests: post: summary: 'Create a new attestation request.' operationId: createANewAttestationRequest description: 'You must provide the `person_id` and `document_id` in the request body.' parameters: [] responses: 201: description: '' content: text/plain: schema: type: string example: "{\n \"id\": \"01kg82xqfx6fvr046d15hnfmjv\",\n \"organization_id\": \"01kg82xqfx6fvr046d15hnfmjv\",\n \"document_revision_id\": \"01kg82xqfx6fvr046d15hnfmjv\",\n \"person_id\": \"01kg82xqfx6fvr046d15hnfmjv\",\n \"sent_at\": \"2024-01-01T00:00:00.000000Z\",\n \"requested_attestation_type\": \"signature\",\n \"viewed_at\": null,\n \"attested_at\": null,\n \"canceled_at\": null,\n \"requested_by_user_id\": \"01kg82xqfx6fvr046d15hnfmjv\",\n \"batch_id\": null,\n \"created_at\": \"2024-01-01T00:00:00.000000Z\",\n \"updated_at\": \"2024-01-01T00:00:00.000000Z\",\n \"status\": \"sent\",\n }" tags: - 'Attestation Requests' requestBody: required: true content: application/json: schema: type: object properties: person_id: type: string description: 'The unique identifier of the person to send the attestation request to.' example: 01kg82xqfx6fvr046d15hnfmjv document_id: type: string description: 'The unique identifier of the document to be attested.' example: 01kg82xqfx6fvr046d15hnfmjv requested_attestation_type: type: string description: '' example: acknowledgment enum: - acknowledgment - signature nullable: true required: - person_id - document_id /api/v1/documents: get: summary: 'List all documents.' operationId: listAllDocuments description: 'You can filter documents by providing query parameters such as `name`.' parameters: - in: query name: name description: 'The name of the document.' example: 'Employee Handbook' required: false schema: type: string description: 'The name of the document.' example: 'Employee Handbook' nullable: true responses: 200: description: '' content: application/json: schema: type: array items: type: object properties: id: type: string example: 01kg82xqfx6fvr046d15hnfmjv organization_id: type: string example: 01kg82xqfx6fvr046d15hnfmjv name: type: string example: 'Employee Handbook' created_at: type: string example: '2024-01-01T00:00:00.000000Z' updated_at: type: string example: '2024-01-01T00:00:00.000000Z' has_published_revision: type: boolean example: true last_updated_at: type: string example: '2024-01-01T00:00:00.000000Z' example: - id: 01kg82xqfx6fvr046d15hnfmjv organization_id: 01kg82xqfx6fvr046d15hnfmjv name: 'Employee Handbook' created_at: '2024-01-01T00:00:00.000000Z' updated_at: '2024-01-01T00:00:00.000000Z' has_published_revision: true last_updated_at: '2024-01-01T00:00:00.000000Z' - id: 05ns89asd87fsdg045g45hnfskd organization_id: 01kg82xqfx6fvr046d15hnfmjv name: 'Code of Conduct' created_at: '2024-01-02T00:00:00.000000Z' updated_at: '2024-01-02T00:00:00.000000Z' has_published_revision: false last_updated_at: '2024-01-02T00:00:00.000000Z' tags: - Documents /api/v1/me: get: summary: 'Retrieve current user.' operationId: retrieveCurrentUser description: 'This endpoint returns the details of the currently authenticated user, including their name, email, and the name of the organization they belong to.' parameters: [] responses: 200: description: '' content: application/json: schema: type: object example: id: 01kg82xqfx6fvr046d15hnfmjv name: 'John Doe' email: john.doe@example.com current_organization_name: 'Example Organization' properties: id: type: string example: 01kg82xqfx6fvr046d15hnfmjv name: type: string example: 'John Doe' email: type: string example: john.doe@example.com current_organization_name: type: string example: 'Example Organization' tags: - Endpoints /api/v1/people: get: summary: 'List all people.' operationId: listAllPeople description: 'You can filter people by providing query parameters such as `id`, `name`, `email`, or `phone`.' parameters: - in: query name: id description: 'The unique identifier of the person.' example: 01kg82xqfx6fvr046d15hnfmjv required: false schema: type: string description: 'The unique identifier of the person.' example: 01kg82xqfx6fvr046d15hnfmjv nullable: true - in: query name: name description: 'The name of the person.' example: 'John Doe' required: false schema: type: string description: 'The name of the person.' example: 'John Doe' nullable: true - in: query name: email description: 'The email address of the person.' example: john.doe@example.com required: false schema: type: string description: 'The email address of the person.' example: john.doe@example.com nullable: true - in: query name: phone description: 'The phone number of the person. Must be in international format.' example: '+12345678901' required: false schema: type: string description: 'The phone number of the person. Must be in international format.' example: '+12345678901' nullable: true - in: query name: archived description: '' example: architecto required: false schema: type: string description: '' example: architecto nullable: true responses: 200: description: '' content: application/json: schema: type: array items: type: object properties: id: type: string example: 01kg82xqfx6fvr046d15hnfmjv name: type: string example: 'John Doe' email: type: string example: john.doe@example.com phone: type: string example: '+12345678901' example: - id: 01kg82xqfx6fvr046d15hnfmjv name: 'John Doe' email: john.doe@example.com phone: '+12345678901' - id: 05ns89asd87fsdg045g45hnfskd name: 'Jane Smith' email: jane.smith@example.com phone: '+12345678902' tags: - People post: summary: 'Create a new person.' operationId: createANewPerson description: 'You must provide the `name` and `email` of the person. The `phone` number is optional but must be in international format if provided.' parameters: [] responses: 201: description: '' content: application/json: schema: type: object example: id: 01kg82xqfx6fvr046d15hnfmjv name: 'John Doe' email: john.doe@example.com phone: '+12345678901' properties: id: type: string example: 01kg82xqfx6fvr046d15hnfmjv name: type: string example: 'John Doe' email: type: string example: john.doe@example.com phone: type: string example: '+12345678901' tags: - People requestBody: required: true content: application/json: schema: type: object properties: name: type: string description: 'The name of the person.' example: 'John Doe' email: type: string description: 'The email address of the person.' example: john.doe@example.com phone: type: string description: 'The phone number of the person. Must be in international format.' example: '+12345678901' nullable: true groups: type: array description: 'Must not be greater than 255 characters.' example: - 'n' items: type: string documents: type: array description: '' example: - architecto items: type: string required: - name - email '/api/v1/people/{id}': get: summary: 'Retrieve the specified person.' operationId: retrieveTheSpecifiedPerson description: "You can retrieve a person by its unique identifier (ID). The response will include the person's name, email, and phone number." parameters: [] responses: 200: description: '' content: application/json: schema: type: object example: id: 01kg82xqfx6fvr046d15hnfmjv name: 'John Doe' email: john.doe@example.com phone: '+12345678901' properties: id: type: string example: 01kg82xqfx6fvr046d15hnfmjv name: type: string example: 'John Doe' email: type: string example: john.doe@example.com phone: type: string example: '+12345678901' tags: - People parameters: - in: path name: id description: 'The ID of the person.' example: 01kkn48q1cvh6xerxhfxdy2zpe required: true schema: type: string