Search Clickwrap Events

Endpoint

POST /v2/server/clickwrap/{slug}/events/search

Authentication

This endpoint requires an OAuth access token. Send it as a bearer token:

Authorization: Bearer your_access_token

Required scope: clickwrap:read

Clickwrap is the one /v2 surface with no acting user. The subject of a clickwrap event is user_identifier, an opaque string you supply for your own end user, which is never resolved against Chamelio’s users. These endpoints are authorized by organization and scope alone, so client_credentials tokens work here without restriction.

Path Parameters

Parameter	Type	Required	Description
`slug`	string	Yes	Unique identifier for the clickwrap

Request Body

Every field is optional. An empty body ({}) returns the newest 50 events for the clickwrap.

Field	Type	Required	Description
`user_identifier`	string or null	No	Case-insensitive partial match against `user_identifier`. `%` matches any sequence of characters; `_` matches one character. Check returned values when you need a literal match
`event_types`	array of strings or null	No	Return only these event types: `accepted`, `viewed`, `checked`, `scrolled_to_bottom`
`version_ids`	array of integers or null	No	Return only events recorded against these versions. Use the `clickwrap_version_id` values from Get Clickwrap History
`metadata_key`	string or null	No	Top-level key in the event’s `metadata`. Must be sent together with `metadata_value`
`metadata_value`	string or null	No	Case-insensitive partial match against the value at `metadata_key`, with `%` and `_` wildcards as above. Check returned values when you need a literal match. Must be sent together with `metadata_key`
`from_date`	string or null	No	ISO 8601 timestamp. Return events recorded at or after this time
`to_date`	string or null	No	ISO 8601 timestamp. Return events recorded at or before this time. Cannot be earlier than `from_date`
`sort_order`	string	No	Sort by event time: `desc` (newest first, default) or `asc`
`offset`	integer	No	Number of events to skip. Minimum `0`, default `0`
`page_size`	integer	No	Number of events to return. Between `1` and `200`, default `50`

Request Example

curl -X POST "https://platform.chamelio.ai/v2/server/clickwrap/privacy-policy/events/search" \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "user_identifier": "user@example.com",
    "event_types": ["accepted"],
    "page_size": 20
  }'

import requests

slug = "privacy-policy"

url = f"https://platform.chamelio.ai/v2/server/clickwrap/{slug}/events/search"
headers = {
    "Authorization": "Bearer your_access_token",
    "Content-Type": "application/json"
}
body = {
    "user_identifier": "user@example.com",
    "event_types": ["accepted"],
    "page_size": 20
}

response = requests.post(url, headers=headers, json=body)
print(response.json())

const slug = "privacy-policy";

const response = await fetch(
  `https://platform.chamelio.ai/v2/server/clickwrap/${slug}/events/search`,
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your_access_token',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      user_identifier: 'user@example.com',
      event_types: ['accepted'],
      page_size: 20
    })
  }
);

const data = await response.json();
console.log(data);

Response

Success Response

Status Code: 200 OK

{
  "events": [
    {
      "clickwrap_event_id": 1834,
      "clickwrap_id": 7,
      "clickwrap_title": "Privacy Policy",
      "clickwrap_slug": "privacy-policy",
      "event_type": "accepted",
      "user_identifier": "user@example.com",
      "ip_address": "203.0.113.42",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ...",
      "metadata": {
        "session_id": "sess_abc123",
        "product": "checkout",
        "certificate_attachment_id": 5521,
        "template_variables": {"company_name": "Acme Inc"}
      },
      "version_number": 3,
      "created_at": "2026-10-20T14:32:08Z",
      "sor_document_processing_id": 90412,
      "sor_exported_at": "2026-10-20T14:32:41Z",
      "sor_export_error": null
    },
    {
      "clickwrap_event_id": 1102,
      "clickwrap_id": 7,
      "clickwrap_title": "Privacy Policy",
      "clickwrap_slug": "privacy-policy",
      "event_type": "accepted",
      "user_identifier": "user@example.com",
      "ip_address": "203.0.113.42",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ...",
      "metadata": {
        "session_id": "sess_9f8e7d",
        "product": "checkout"
      },
      "version_number": 2,
      "created_at": "2026-03-04T10:15:22Z",
      "sor_document_processing_id": null,
      "sor_exported_at": null,
      "sor_export_error": null
    }
  ],
  "total": 2
}

Response Fields

Field	Type	Description
`events`	array	The matching events for this page, sorted by `created_at` in `sort_order`
`total`	integer	Total matching events across all pages, except that an empty or out-of-range page returns `0` even if earlier pages contain matches

Event Object Fields

Field	Type	Description
`clickwrap_event_id`	integer	Unique identifier of the event
`clickwrap_id`	integer	Internal identifier of the clickwrap
`clickwrap_title`	string	Title of the clickwrap
`clickwrap_slug`	string	Slug of the clickwrap
`event_type`	string	`accepted`, `viewed`, `checked`, or `scrolled_to_bottom`
`user_identifier`	string	The end-user identifier sent when the event was captured
`ip_address`	string or null	End user’s IP address, if it was sent at capture
`user_agent`	string or null	End user’s user agent, if it was sent at capture
`metadata`	object or null	Stored custom metadata plus `template_variables` when a nonempty `variables` object was sent at capture. On `accepted` events Chamelio adds `certificate_attachment_id` once the acceptance PDF has been generated
`version_number`	integer or null	Sequential number of the version the event was recorded against
`created_at`	string	ISO 8601 timestamp when the event was recorded
`sor_document_processing_id`	integer or null	Knowledge Center processing ID of the exported acceptance PDF. Null until exported, and always null when export to the Knowledge Center is off for the clickwrap
`sor_exported_at`	string or null	ISO 8601 timestamp when the acceptance PDF was exported to the Knowledge Center
`sor_export_error`	string or null	Error message if storing or exporting the acceptance PDF failed

Error Responses

401 Unauthorized

Returned when the access token is missing, unknown, revoked, or expired, or when an X-API-Key was sent instead of a bearer token. See OAuth error responses.

{
  "detail": "Invalid access token"
}

403 Forbidden

Returned when the token does not carry the required scope.

{
  "detail": "Insufficient scope; this endpoint requires: clickwrap:read"
}

404 Not Found

Returned when no clickwrap exists for the given slug.

{
  "detail": "Not found"
}

422 Unprocessable Entity

Returned when the request body fails validation: for example, only one of metadata_key and metadata_value is sent, from_date is later than to_date, page_size is outside 1-200, or an event_types entry is not a known event type.

{
  "detail": [
    {
      "loc": ["body"],
      "msg": "Value error, metadata_key and metadata_value must be provided together",
      "type": "value_error"
    }
  ]
}

429 Too Many Requests

Returned when your organization exceeds its per-minute request limit.

{
  "detail": "Rate limit exceeded"
}

500 Internal Server Error

Returned when the request fails due to a server error.

{
  "detail": "Failed to search clickwrap events"
}

Notes

The search covers every version of the clickwrap, including archived ones, so it returns a user’s full history. Unlike the other clickwrap endpoints, it also works for a clickwrap that has no published version yet.

user_identifier and metadata_value are partial matches: user@example.com also matches other-user@example.com. % matches any sequence of characters and _ matches one character; for example, user_1 also matches userA1. When you need a literal user or metadata value, check that value on each returned event.

For personalized agreements, metadata.template_variables contains the values supplied through the v2 capture request. The acceptance PDF uses those values with the recorded version’s template. PDF generation is asynchronous, so certificate_attachment_id may be absent when you first retrieve the event.

To page through results, increase offset by page_size until you have read total events. A page past the last result comes back with an empty events array and total set to 0.

The result is organization-global. Every token issued for the same organization gets the same answer - the token’s user is used only to authenticate and scope-check the request.

Use Cases

This endpoint is useful for:

Compliance evidence - Pull every acceptance a user has recorded, with the version, IP address, user agent, and metadata of each
Reconciliation - Find events by your own metadata (e.g. an order or session ID) to match them to records in your system
Funnel reporting - Count viewed versus accepted events over a date range

Overview

API Key Access

OAuth App Access

MCP (beta)

Webhooks

Endpoint

Authentication

Path Parameters

Request Body

Request Example

Response

Success Response

Response Fields

Event Object Fields

Error Responses

401 Unauthorized

403 Forbidden

404 Not Found

422 Unprocessable Entity

429 Too Many Requests

500 Internal Server Error

Notes

Use Cases

Overview

API Key Access

OAuth App Access

MCP (beta)

Webhooks

​Endpoint

​Authentication

​Path Parameters

​Request Body

​Request Example

​Response

​Success Response

​Response Fields

​Event Object Fields

​Error Responses

​401 Unauthorized

​403 Forbidden

​404 Not Found

​422 Unprocessable Entity

​429 Too Many Requests

​500 Internal Server Error

​Notes

​Use Cases

Endpoint

Authentication

Path Parameters

Request Body

Request Example

Response

Success Response

Response Fields

Event Object Fields

Error Responses

401 Unauthorized

403 Forbidden

404 Not Found

422 Unprocessable Entity

429 Too Many Requests

500 Internal Server Error

Notes

Use Cases