Create Acceptance Records
Record user acceptance of document packets using the ToughClicks REST API.
Endpoint
POST /api/v1/client/{clientId}/accept
Request
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
clientId | string | Yes | Your unique client identifier |
Headers
| Header | Value | Required |
|---|---|---|
accept | application/json | Yes |
content-type | application/json | Yes |
Request Body
{
"displayMethod": "group",
"signerIdentifier": "string",
"signerEmailAddress": "string",
"packetId": "string",
"applicationContext": {},
"customData": {},
"dynamicData": {}
}
Body Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
displayMethod | string | Yes | How the terms were displayed: group, individual, scroll, or buttonAssent |
packetId | string | Yes | The ID of the packet being accepted |
applicationContext | object | Yes | Context about the acceptance environment |
signerIdentifier | string | No | Unique identifier for the user (email, user ID, wallet address, etc.) |
signerEmailAddress | string | No | Email address of the signer |
customData | object | No | Custom data to help identify the signer (max 1 KB, immutable after acceptance). See Limits |
dynamicData | object | No | Dynamic values if using tokens in agreements (max 60 KB). See Limits |
assentEvidence | object | No | Evidence of how assent was manifested. Required in practice for buttonAssent, ignored for the checkbox methods |
Display Method Values
group- All documents displayed with a single checkboxindividual- Each document has its own checkboxscroll- User was required to scroll through the termsbuttonAssent- A notice was displayed with no checkbox, and the user agreed by clicking the integrator's own submit button
Assent Evidence
For the buttonAssent display method there is no checkbox, so the acceptance record rests on what notice was shown and whether it was seen. Send assentEvidence alongside applicationContext. The JavaScript SDK builds and sends this object for you; the shape is documented here for direct API integrations.
{
"assentEvidence": {
"method": "buttonAssent",
"noticeText": "By clicking Complete Booking you agree to our Booking & Cancellation Agreement.",
"assentActionLabel": "Complete Booking",
"presentedAt": "2026-08-27T14:02:11.402Z",
"firstPresentedAt": "2026-08-27T14:01:47.115Z",
"acceptedAt": "2026-08-27T14:02:39.881Z",
"renderCount": 2,
"visibility": {
"everVisible": true,
"visibleAtAccept": true,
"visibleMs": 52840,
"peakRatio": 1.0,
"observerSupported": true
},
"geometry": {
"notice": { "x": 412, "y": 968, "width": 464, "height": 38 },
"action": { "x": 412, "y": 1022, "width": 200, "height": 44 },
"fontSizePx": 14,
"viewport": { "width": 1280, "height": 800 }
},
"documents": [
{
"documentId": "0f0e88f8-...",
"presented": true,
"presentedAt": "2026-08-27T14:01:47.115Z",
"openedAt": null
}
]
}
}
| Field | Type | Description |
|---|---|---|
method | string | The display method in force |
noticeText | string | The notice exactly as rendered on the page. Read it from the DOM, not from your template: with dynamic contracts the two can differ, and what the visitor saw is the evidence |
assentActionLabel | string | The submit button label as named in the notice |
presentedAt | string | ISO 8601. When the notice was most recently rendered |
firstPresentedAt | string | ISO 8601. When the notice was first rendered in this session |
acceptedAt | string | ISO 8601. When acceptance was submitted |
renderCount | number | How many times the notice rendered before acceptance |
visibility | object | Whether the notice was on screen, and for how long. Set observerSupported to false if you could not measure it |
geometry | object | Element boxes and font size evidencing conspicuousness and proximity. Individual fields may be null |
documents | array | Per-document presentation record, including openedAt if the visitor opened a document |
This is a fixed key set. Undeclared fields are discarded, so send exactly these keys.
These values are printed on the acceptance certificate PDF under Assent Evidence. A buttonAssent agreement submitted without them produces a materially weaker certificate.
Application Context
The applicationContext object is required and can include any relevant information about the acceptance environment:
{
"deviceType": "mobile",
"screenSize": "375x667",
"referrer": "https://example.com/signup",
"pageTitle": "Sign Up - Example App",
"url": "https://example.com/accept-terms",
"timezone": "America/New_York",
"browserVersion": "Chrome 120.0.0",
"operatingSystem": "iOS",
"operatingSystemVersion": "17.2.1"
}
Custom Data
Custom data allows you to attach additional information to acceptance records. This information helps identify the signer and verify their identity if the acceptance is ever challenged.
Store any additional metadata with the acceptance (up to 1 KB):
{
"customerId": "cust_12345",
"subscriptionTier": "premium",
"referralSource": "email-campaign",
"accountType": "business"
}
- Custom data has a 1 KB size limit (1,024 bytes of serialized JSON)
- Custom data is immutable after acceptance is created
Dynamic Data
If your agreements use dynamic tokens, provide the values here:
{
"userName": "John Doe",
"accountType": "Premium",
"expirationDate": "2025-12-31"
}
Learn more about dynamic tokens in the Dynamic Contracts guide.
Limits for customData and dynamicData
The API checks both objects before recording anything. A request that breaks a rule gets a 400 Bad Request whose message names the rule and the limit, and no acceptance is recorded.
| Rule | customData | dynamicData |
|---|---|---|
| Type | JSON object (not an array, string or number) | JSON object or null |
| Size of the serialized JSON (UTF-8 bytes) | 1 KB (1,024 bytes) | 60 KB (61,440 bytes) |
| Nesting | at most 10 levels of objects/arrays (the root object is level 1) | same |
| Keys | at most 100 in total, counting the keys of nested objects | same |
| Key names | at most 100 characters; may not start with $ or .; may not be __proto__, constructor or prototype | same |
| Values | strings, numbers, booleans, null, objects and arrays | same |
Sizes are measured in UTF-8 bytes of the object re-serialized as compact JSON (no whitespace) after HTML tags are stripped, so a non-ASCII character such as é counts as 2 bytes.
HTML is stripped. Both objects are treated as plain text: HTML tags are removed from every string value (at any depth, including inside arrays) before the acceptance is stored, so "<b>Ada</b> & Co" is stored as "Ada & Co". Numbers, booleans and null are stored unchanged. Put formatting in the document template, not in the data.
{
"statusCode": 400,
"message": [
"customData is too large: 1,342 bytes; the maximum is 1,024 bytes (1 KB), measured as UTF-8 bytes of the serialized JSON"
],
"error": "Bad Request"
}
The JavaScript library applies the same limits in setCustomData() and setDynamicData(), so it reports the problem before sending the request.
Response
Success Response
Status Code: 200 OK
{
"entities": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"created": "2025-10-04T12:34:56Z",
"modified": "2025-10-04T12:34:56Z",
"deleted": null,
"ipAddress": "192.168.1.1",
"userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
"displayMethod": "group",
"user": "user@example.com",
"signerIdentifier": "user@example.com",
"signerEmailAddress": "user@example.com",
"applicationContext": {
"deviceType": "desktop",
"browserVersion": "Chrome 120.0.0"
},
"customData": {
"orderId": "12345"
},
"versionId": "v1.0",
"version": {
"id": "v1.0",
"versionNumber": "1.0",
"contents": "<h1>Terms of Service</h1>..."
},
"packetId": "3646a13b-cbd1-482c-9947-460cb74a71f2",
"pdfUrl": "https://cdn.toughclicks.com/acceptances/550e8400-e29b-41d4-a716-446655440000.pdf"
}
],
"totalEntities": 1
}
Response Fields
| Field | Type | Description |
|---|---|---|
entities | array | Array of acceptance record objects |
totalEntities | number | Total number of acceptance records created |
Acceptance Entity Object
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier for the acceptance record |
created | string | ISO 8601 timestamp when record was created |
modified | string | ISO 8601 timestamp when record was last modified |
deleted | string | null | ISO 8601 timestamp when record was deleted, or null if active |
ipAddress | string | IP address of the user at time of acceptance |
userAgent | string | User agent string of the browser/client |
displayMethod | string | How the terms were displayed |
user | string | (Deprecated) Legacy user identifier field |
signerIdentifier | string | Unique identifier for the user |
signerEmailAddress | string | Email address of the signer |
applicationContext | object | Context data provided in the request |
customData | object | Custom data provided in the request |
versionId | string | ID of the document version that was accepted |
version | object | Full version object of the accepted document |
packetId | string | ID of the packet that was accepted |
pdfUrl | string | URL to download a PDF certificate of the acceptance |
Error Response
Status Code: 400 Bad Request
{
"statusCode": 400,
"message": ["applicationContext must be an object"],
"error": "Bad Request"
}
customData or dynamicData over a limit (see Limits):
{
"statusCode": 400,
"message": ["dynamicData is nested too deeply: the maximum is 10 levels of objects/arrays"],
"error": "Bad Request"
}
A request body larger than 1 MB is rejected with 413 Payload Too Large.
Status Code: 404 Not Found
{
"statusCode": 404,
"message": "Packet 3646a13b-cbd1-482c-9947-460cb74a71f2 not found",
"error": "Not Found"
}
See Error Handling for the error body format.
Examples
Basic Acceptance
curl --request POST \
--url https://api.toughclicks.com/api/v1/client/477951a5-069b-401f-ab7f-32db486d5741/accept \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '{
"displayMethod": "group",
"signerIdentifier": "user@example.com",
"packetId": "3646a13b-cbd1-482c-9947-460cb74a71f2",
"applicationContext": {
"source": "web-app"
}
}'
With Email and Context
curl --request POST \
--url https://api.toughclicks.com/api/v1/client/477951a5-069b-401f-ab7f-32db486d5741/accept \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '{
"displayMethod": "individual",
"signerIdentifier": "uuid-12345",
"signerEmailAddress": "user@example.com",
"packetId": "3646a13b-cbd1-482c-9947-460cb74a71f2",
"applicationContext": {
"deviceType": "desktop",
"browserVersion": "Chrome 120.0.0",
"operatingSystem": "macOS",
"referrer": "https://example.com/signup"
}
}'
With Custom and Dynamic Data
curl --request POST \
--url https://api.toughclicks.com/api/v1/client/477951a5-069b-401f-ab7f-32db486d5741/accept \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '{
"displayMethod": "scroll",
"signerIdentifier": "user@example.com",
"packetId": "3646a13b-cbd1-482c-9947-460cb74a71f2",
"applicationContext": {
"platform": "web"
},
"customData": {
"orderId": "12345",
"subscriptionTier": "premium"
},
"dynamicData": {
"userName": "John Doe",
"accountType": "Premium"
}
}'
JavaScript Example
async function createAcceptance(clientId, packetId, userEmail) {
const response = await fetch(
`https://api.toughclicks.com/api/v1/client/${clientId}/accept`,
{
method: 'POST',
headers: {
'accept': 'application/json',
'content-type': 'application/json'
},
body: JSON.stringify({
displayMethod: 'group',
signerIdentifier: userEmail,
signerEmailAddress: userEmail,
packetId: packetId,
applicationContext: {
deviceType: navigator.platform,
browserVersion: navigator.userAgent,
url: window.location.href,
referrer: document.referrer
}
})
}
);
const data = await response.json();
if (response.ok) {
console.log('Acceptance created:', data.entities[0].id);
console.log('PDF URL:', data.entities[0].pdfUrl);
return data;
} else {
console.error('Error:', data.message);
throw new Error(data.message);
}
}
// Usage
const result = await createAcceptance(
'477951a5-069b-401f-ab7f-32db486d5741',
'3646a13b-cbd1-482c-9947-460cb74a71f2',
'user@example.com'
);
console.log(`Created ${result.totalEntities} acceptance record(s)`);
Python Example
import requests
import json
def create_acceptance(client_id, packet_id, user_email):
url = f"https://api.toughclicks.com/api/v1/client/{client_id}/accept"
payload = {
"displayMethod": "group",
"signerIdentifier": user_email,
"signerEmailAddress": user_email,
"packetId": packet_id,
"applicationContext": {
"deviceType": "server",
"platform": "Python API"
}
}
headers = {
"accept": "application/json",
"content-type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
if response.status_code == 200:
data = response.json()
acceptance_id = data['entities'][0]['id']
pdf_url = data['entities'][0]['pdfUrl']
print(f"Acceptance created: {acceptance_id}")
print(f"PDF URL: {pdf_url}")
return data
else:
print(f"Error: {response.json()['message']}")
raise Exception(response.json()['message'])
# Usage
result = create_acceptance(
'477951a5-069b-401f-ab7f-32db486d5741',
'3646a13b-cbd1-482c-9947-460cb74a71f2',
'user@example.com'
)
print(f"Total entities created: {result['totalEntities']}")
Best Practices
Always Provide applicationContext
The applicationContext parameter is required. At minimum, provide a simple object:
{
applicationContext: {
source: "web-app"
}
}
For better compliance tracking, include comprehensive context:
{
applicationContext: {
deviceType: navigator.platform,
browserVersion: navigator.userAgent,
url: window.location.href,
referrer: document.referrer,
screenSize: `${window.screen.width}x${window.screen.height}`,
timezone: Intl.DateTimeFormat().resolvedOptions().timeZone
}
}
Use Meaningful Signer Identifiers
Choose identifiers that will be useful for searching and managing agreements:
- Email addresses - Best for user-facing applications
- User IDs - Good for internal systems
- UUIDs - Use with
signerEmailAddressfor searchability
Store Relevant Custom Data
Use customData to link acceptances to your business logic:
- Order IDs
- Subscription tiers
- Campaign identifiers
- User segments
Save the PDF URL
The response includes a pdfUrl field that provides a downloadable PDF certificate of the acceptance. Store this URL if you need to provide users with proof of acceptance later:
const result = await createAcceptance(clientId, packetId, email);
const pdfUrl = result.entities[0].pdfUrl;
// Store pdfUrl in your database for later retrieval
await db.users.update(userId, { lastAcceptancePdfUrl: pdfUrl });
Handle Errors Gracefully
Always check the response status and handle errors appropriately:
try {
const acceptance = await createAcceptance(clientId, packetId, email);
// Proceed with user flow
} catch (error) {
// Show error message to user
// Log error for debugging
// Don't proceed until acceptance is recorded
}
Common Issues
Invalid applicationContext
Always include applicationContext, and make it a JSON object, even if it has just one property. A string or other non-object value is rejected:
Error:
{
"statusCode": 400,
"message": ["applicationContext must be an object"],
"error": "Bad Request"
}
Fix:
{
applicationContext: { source: "web" } // Minimum required
}
customData or dynamicData Rejected
A 400 whose message starts with customData or dynamicData means the object broke one of the limits, for example customData is too large: 1,342 bytes; the maximum is 1,024 bytes (1 KB), .... Keep customData to identifiers (order ID, plan, account number) rather than whole records, and send only the values your templates use in dynamicData.
Invalid Packet ID
Verify the packet ID exists for your client and is published.
Multiple Acceptance Records
The API creates one acceptance record per document in the packet. The totalEntities field indicates how many records were created. This is normal behavior.
Understanding the Response
The response returns an entities array because packets can contain multiple documents, and the API creates one acceptance record per document. Check totalEntities to see how many records were created.
Next Steps
- Get Packet Details - Retrieve packet information before creating acceptances
- Verify Acceptance - Check if user has accepted latest version
- Dynamic Contracts - Learn about using dynamic tokens
- Managing Packets - Configure packets in the dashboard