Skip to main content
Version: Isle Royale (2.5.0)

Create Acceptance Records

Record user acceptance of document packets using the ToughClicks REST API.

Endpoint​

POST /api/v1/client/{clientId}/accept

Request​

Path Parameters​

ParameterTypeRequiredDescription
clientIdstringYesYour unique client identifier

Headers​

HeaderValueRequired
acceptapplication/jsonYes
content-typeapplication/jsonYes

Request Body​

{
"displayMethod": "group",
"signerIdentifier": "string",
"signerEmailAddress": "string",
"packetId": "string",
"applicationContext": {},
"customData": {},
"dynamicData": {}
}

Body Parameters​

ParameterTypeRequiredDescription
displayMethodstringYesHow the terms were displayed: group, individual, scroll, or buttonAssent
packetIdstringYesThe ID of the packet being accepted
applicationContextobjectYesContext about the acceptance environment
signerIdentifierstringNoUnique identifier for the user (email, user ID, wallet address, etc.)
signerEmailAddressstringNoEmail address of the signer
customDataobjectNoCustom data to help identify the signer (max 1 KB, immutable after acceptance). See Limits
dynamicDataobjectNoDynamic values if using tokens in agreements (max 60 KB). See Limits
assentEvidenceobjectNoEvidence 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 checkbox
  • individual - Each document has its own checkbox
  • scroll - User was required to scroll through the terms
  • buttonAssent - 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
}
]
}
}
FieldTypeDescription
methodstringThe display method in force
noticeTextstringThe 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
assentActionLabelstringThe submit button label as named in the notice
presentedAtstringISO 8601. When the notice was most recently rendered
firstPresentedAtstringISO 8601. When the notice was first rendered in this session
acceptedAtstringISO 8601. When acceptance was submitted
renderCountnumberHow many times the notice rendered before acceptance
visibilityobjectWhether the notice was on screen, and for how long. Set observerSupported to false if you could not measure it
geometryobjectElement boxes and font size evidencing conspicuousness and proximity. Individual fields may be null
documentsarrayPer-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"
}
warning
  • 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"
}
info

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.

RulecustomDatadynamicData
TypeJSON 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)
Nestingat most 10 levels of objects/arrays (the root object is level 1)same
Keysat most 100 in total, counting the keys of nested objectssame
Key namesat most 100 characters; may not start with $ or .; may not be __proto__, constructor or prototypesame
Valuesstrings, numbers, booleans, null, objects and arrayssame

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​

FieldTypeDescription
entitiesarrayArray of acceptance record objects
totalEntitiesnumberTotal number of acceptance records created

Acceptance Entity Object​

FieldTypeDescription
idstringUnique identifier for the acceptance record
createdstringISO 8601 timestamp when record was created
modifiedstringISO 8601 timestamp when record was last modified
deletedstring | nullISO 8601 timestamp when record was deleted, or null if active
ipAddressstringIP address of the user at time of acceptance
userAgentstringUser agent string of the browser/client
displayMethodstringHow the terms were displayed
userstring(Deprecated) Legacy user identifier field
signerIdentifierstringUnique identifier for the user
signerEmailAddressstringEmail address of the signer
applicationContextobjectContext data provided in the request
customDataobjectCustom data provided in the request
versionIdstringID of the document version that was accepted
versionobjectFull version object of the accepted document
packetIdstringID of the packet that was accepted
pdfUrlstringURL 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 signerEmailAddress for 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​