Skip to main content
An attestation request sends a document to a contact (person) and asks them to either acknowledge or sign it. Use this endpoint to programmatically issue requests from your own systems. The document must have a published revision, and both the person and document must belong to your organization.

​
Endpoint

POST https://api.clearpolicy.app/v1/attestation-requests

​
Authentication

Required. Pass your OAuth bearer token in the Authorization header.

​
Body parameters

​
person_id
string
required
The ULID of the person to send the request to. The person must belong to your organization.
​
document_id
string
required
The ULID of the document to send. The document must have a published revision.
​
requested_attestation_type
string
Override the document’s default attestation type for this request. Accepted values: "acknowledgment" or "signature". If omitted, the document’s default_attestation_type is used.

​
Example request

curl https://api.clearpolicy.app/v1/attestation-requests \
  -X POST \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "person_id": "01kg82xqfx6fvr046d15hnfmjv",
    "document_id": "01jz91kq3m0gar5btepwxvncde",
    "requested_attestation_type": "signature"
  }'

​
Response fields

A successful request returns 201 Created with the attestation request object.
​
id
string
required
The ULID of the attestation request.
​
organization_id
string
required
The ULID of the organization the request belongs to.
​
document_id
string
required
The ULID of the document being attested.
​
document_revision_id
string
required
The ULID of the specific published revision that was sent.
​
person_id
string
required
The ULID of the person the request was sent to.
​
recipient_name
string
required
The name of the recipient at the time the request was created.
​
recipient_email
string
required
The email address of the recipient at the time the request was created.
​
requested_attestation_type
string
required
The attestation type for this request. Either "acknowledgment" or "signature".
​
sent_at
string
ISO 8601 timestamp of when the request was sent, or null if not yet sent.
​
last_reminded_at
string
ISO 8601 timestamp of the most recent reminder, or null if no reminder has been sent.
​
viewed_at
string
ISO 8601 timestamp of when the recipient first viewed the request, or null.
​
attested_at
string
ISO 8601 timestamp of when the recipient completed the attestation, or null if pending.
​
canceled_at
string
ISO 8601 timestamp of when the request was canceled, or null.
​
expires_at
string
ISO 8601 timestamp of when the request is scheduled to expire, or null if it does not expire.
​
expired_at
string
ISO 8601 timestamp of when the request actually expired, or null if still active.
​
requested_by_user_id
string
The ULID of the user whose OAuth client issued this request.
​
source
string
required
How the request was created. For requests created via the API, this is "oauth".
​
status
string
required
The current status of the request. Possible values: "sent", "viewed", "attested", "canceled", "expired".
​
created_at
string
required
ISO 8601 timestamp of when the request was created.
​
updated_at
string
required
ISO 8601 timestamp of the last update.

​
Example response

{
  "id": "01kg82xqfx6fvr046d15hnfmjv",
  "organization_id": "01jz91kq3m0gar5btepwxvncde",
  "document_id": "01jz91kq3m0gar5btepwxvncde",
  "document_revision_id": "01jz91kq3m0gar5bteqryz1234",
  "person_id": "01kg82xqfx6fvr046d15hnfmjv",
  "recipient_name": "Jane Smith",
  "recipient_email": "jane.smith@example.com",
  "requested_attestation_type": "signature",
  "sent_at": "2024-06-15T10:30:00.000000Z",
  "last_reminded_at": null,
  "viewed_at": null,
  "attested_at": null,
  "canceled_at": null,
  "expires_at": "2025-06-15T10:30:00.000000Z",
  "expired_at": null,
  "requested_by_user_id": "01jz91kq3m0gar5btepw000001",
  "source": "oauth",
  "status": "sent",
  "created_at": "2024-06-15T10:30:00.000000Z",
  "updated_at": "2024-06-15T10:30:00.000000Z"
}

​
Error responses

StatusCause
400 Bad RequestThe document exists but has no published revision.
404 Not FoundThe person_id or document_id was not found in your organization.
422 Unprocessable EntityValidation failed — check that both IDs are valid ULIDs and requested_attestation_type is a supported value.
Last modified on April 12, 2026