Capture Clickwrap Event

Endpoint

POST /v2/server/clickwrap/{slug}/capture

Authentication

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

Authorization: Bearer your_access_token

Required scope: clickwrap:write

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

Field	Type	Required	Description
`user_identifier`	string	Yes	Stable identifier for the end user (e.g. email or internal user ID)
`event_type`	string	Yes	Type of interaction: `accepted`, `viewed`, `checked`, `scrolled_to_bottom`
`metadata`	object or null	No	Arbitrary key-value pairs to attach to the event record
`ip_address`	string or null	No	End user’s IP address at the time of acceptance. Recommended for legal validity - the API caller’s IP is never substituted
`user_agent`	string or null	No	End user’s user agent string. Recommended for legal validity - the API caller’s user agent is never substituted

Request Example

curl -X POST "https://platform.chamelio.ai/v2/server/clickwrap/privacy-policy/capture" \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "user_identifier": "user@example.com",
    "event_type": "accepted",
    "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"}
  }'

import requests

slug = "privacy-policy"

url = f"https://platform.chamelio.ai/v2/server/clickwrap/{slug}/capture"
headers = {
    "Authorization": "Bearer your_access_token",
    "Content-Type": "application/json"
}
body = {
    "user_identifier": "user@example.com",
    "event_type": "accepted",
    "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"}
}

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}/capture`,
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your_access_token',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      user_identifier: 'user@example.com',
      event_type: 'accepted',
      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' }
    })
  }
);

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

Response

Success Response

Status Code: 200 OK

{
  "acknowledged": true
}

Response Fields

Field	Type	Description
`acknowledged`	boolean	Always `true` when the event was recorded successfully

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:write"
}

404 Not Found

Returned when no active clickwrap or active version exists for the given slug.

{
  "detail": "Not found"
}

422 Unprocessable Entity

Returned when an acceptance is recorded before its prerequisite events. An accepted event requires a prior viewed event, and a scroll_and_accept clickwrap additionally requires a prior scrolled_to_bottom event.

{
  "detail": "View event is required before acceptance"
}

{
  "detail": "Scroll to bottom event is required before acceptance"
}

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 capture clickwrap event"
}

Notes

Capture always targets the currently active version. You cannot capture an event against an older or draft version via this endpoint.

Because this is a server-to-server endpoint, the API caller’s IP address and user agent are never used as the end user’s origin data. Always pass the actual end user’s ip_address and user_agent in the request body for legally valid acceptance records.

Record the interaction events in order - viewed, then scrolled_to_bottom for a scroll_and_accept clickwrap, then accepted. Sending accepted first returns 422.

Use Cases

This endpoint is useful for:

Server-side consent capture - Record acceptance from a backend flow where the clickwrap was rendered in your own UI
Audit trails - Store ip_address, user_agent, and metadata (e.g. session ID, product context) for compliance records
Multi-step flows - Record intermediate events (viewed, scrolled_to_bottom) before the final accepted event

Overview

API Key Access

OAuth App Access

Webhooks

Endpoint

Authentication

Path Parameters

Request Body

Request Example

Response

Success Response

Response 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

​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

Error Responses

401 Unauthorized

403 Forbidden

404 Not Found

422 Unprocessable Entity

429 Too Many Requests

500 Internal Server Error

Notes

Use Cases