Custom Data
Custom data allows you to attach additional information to acceptance records. While this information helps identify the signer and verify their identity if the acceptance is ever challenged, you can also include anything else in there, such as the plan that they are signing up for, the method they're using to pay, or anything that you might want to have attached to the agreement and on the PDF when generated.
Overview
While ToughClicks requires a signer identifier (and optionally an email address), you can provide any additional contextual information that may be useful for:
- Identifying the signer in your system
- Verifying the signer in the real world
- Adding context about the acceptance event
- Recording session or transaction information
Key characteristics:
- Custom data is included in the PDF agreement
- Custom data is not searchable via the ToughClicks dashboard
- Custom data must be a valid JavaScript object
- Custom data must be JSON-serializable
When to Use Custom Data
Consider adding custom data when you want to record:
- Demographic information - Age, gender, location, language
- Account details - Account type, subscription level, verification status
- Session information - Session ID, IP address, user agent
- Transaction context - Order ID, plan selected, pricing tier
- Verification data - Phone number, address, government ID type
- Application state - Version, environment, feature flags
This information strengthens the legal validity of the acceptance by providing additional context about who accepted the terms and under what circumstances.
Setting Custom Data
Use the setCustomData() method to attach custom data to the acceptance. Call this method any time before calling TC.accept().
Syntax:
TC.setCustomData(dataObject);
Parameters:
dataObject- Any valid JavaScript object that can be serialized withJSON.stringify()
When to call:
- After initializing ToughClicks
- After setting display options
- Before calling
accept()(manual acceptance mode) - Before the user completes all checkboxes (automatic acceptance mode)
Basic Example
const { ToughClicks } = window.ToughClicks;
const tc = new ToughClicks(clientToken, packetId);
tc.setDisplayOptions({
containerId: 'tc-container',
displayMethod: 'Individual',
signerId: user.id
});
// Set custom data
tc.setCustomData({
customerId: user.customerId,
accountType: 'premium',
referralSource: 'google-ads'
});
Comprehensive Example
const { ToughClicks } = window.ToughClicks;
const tc = new ToughClicks(clientToken, packetId);
tc.setDisplayOptions({
containerId: 'tc-container',
displayMethod: 'Individual',
signerId: currentUser.uuid
});
tc.setSignerEmailAddress(currentUser.email);
// Set comprehensive custom data
tc.setCustomData({
profile: {
age: 28,
gender: 'female',
language: 'en-US'
},
location: {
country: 'US',
state: 'CA',
city: 'Los Angeles',
timezone: 'America/Los_Angeles'
},
account: {
customerId: 'CUST-98765',
type: 'premium',
subscriptionTier: 'pro',
verified: true
},
session: {
id: 'sess_abc123xyz',
ipAddress: '192.168.1.1',
userAgent: navigator.userAgent,
platform: 'web'
},
transaction: {
orderId: 'order_12345',
planSelected: 'annual-pro',
amount: 99.99,
currency: 'USD'
}
});
Nested Objects
Custom data can be deeply nested:
tc.setCustomData({
user: {
profile: {
personal: {
age: 30,
location: {
country: 'US',
state: 'NY',
city: 'New York'
}
},
preferences: {
language: 'en',
notifications: true
}
},
account: {
tier: 'premium',
features: ['feature1', 'feature2']
}
},
metadata: {
source: 'mobile-app',
version: '2.1.0'
}
});
Dynamic Custom Data
Update custom data based on user actions or form inputs:
const { ToughClicks } = window.ToughClicks;
const tc = new ToughClicks(clientToken, packetId);
// Initialize with basic data
let customData = {
timestamp: new Date().toISOString(),
source: 'registration-form'
};
// Update as user fills out form
document.getElementById('age').addEventListener('change', (e) => {
customData.age = parseInt(e.target.value);
tc.setCustomData(customData);
});
document.getElementById('country').addEventListener('change', (e) => {
customData.country = e.target.value;
tc.setCustomData(customData);
});
// Add final data before acceptance
document.getElementById('submit').addEventListener('click', async () => {
customData.customerId = getUserCustomerId();
customData.completeProfile = validateProfile();
tc.setCustomData(customData);
const success = await tc.accept();
// ...
});
Common Use Cases
E-commerce Checkout
tc.setCustomData({
order: {
id: 'ORD-12345',
total: 149.99,
currency: 'USD',
items: [
{ sku: 'PROD-001', quantity: 2, price: 49.99 },
{ sku: 'PROD-002', quantity: 1, price: 50.01 }
]
},
customer: {
accountAge: '2-5-years',
lifetimeValue: 1250.00,
previousOrders: 8
},
checkout: {
paymentMethod: 'credit-card',
shippingMethod: 'standard',
appliedCoupons: ['SAVE10']
}
});
SaaS Registration
tc.setCustomData({
subscription: {
plan: 'professional-annual',
billingCycle: 'annual',
monthlyRate: 49.99,
seats: 5
},
company: {
name: 'Acme Inc.',
size: '50-100',
industry: 'Technology'
},
trial: {
hadTrial: true,
trialStartDate: '2024-01-01',
trialEndDate: '2024-01-14',
trialConversion: true
}
});
Healthcare/HIPAA
tc.setCustomData({
patient: {
mrn: 'MRN-123456', // Medical Record Number
dob: '1990-05-15',
consentType: 'treatment-authorization'
},
provider: {
npi: '1234567890', // National Provider Identifier
facility: 'Main Street Clinic',
department: 'Cardiology'
},
visit: {
visitId: 'VISIT-789',
date: '2024-03-15',
reason: 'annual-checkup'
}
});
Financial Services
tc.setCustomData({
application: {
type: 'checking-account',
applicationId: 'APP-2024-03-15-001',
branch: 'Downtown Branch',
officer: 'John Smith'
},
applicant: {
employmentStatus: 'employed',
annualIncome: '75000-100000',
creditScore: 'good',
existingCustomer: true
},
verification: {
idType: 'drivers-license',
idState: 'CA',
addressVerified: true,
incomeVerified: true
}
});
Requirements and Limitations
Must be JSON-Serializable
The object must be successfully convertible to a string using JSON.stringify():
// Valid - all primitives and simple objects
tc.setCustomData({
string: 'value',
number: 42,
boolean: true,
null: null,
array: [1, 2, 3],
object: { nested: 'value' }
});
// Invalid - contains function
tc.setCustomData({
name: 'John',
callback: function() { } // Functions cannot be serialized
});
// Invalid - contains circular reference
const obj = {};
obj.circular = obj;
tc.setCustomData(obj); // Error: circular reference
// Invalid - contains undefined (will be omitted)
tc.setCustomData({
name: 'John',
age: undefined // Will be omitted from serialization
});
Sensitive Information
ToughClicks is built on a robust, secure platform designed to protect customer data and ensure compliance with industry standards. We follow security best practices across our infrastructure, application, and operations — including encryption in transit and at rest, principle-of-least-privilege access controls, continuous monitoring, and regular security reviews — to maintain the integrity and confidentiality of your data.
Despite all of these protections, we still recommend you consider what information you are sharing with us.
Custom data is included in plain-text in the PDF agreement.
Data Size
Custom data has a 1 KB size limit (1,024 bytes of serialized JSON, measured in UTF-8 bytes). It may also have at most 10 levels of nesting and 100 keys in total, with keys of at most 100 characters. setCustomData() returns false (and logs why in debug mode) when the data breaks a limit, and the API rejects such data with a 400. HTML tags are stripped from string values. See Limits for customData and dynamicData.
Updating Custom Data
You can call setCustomData() multiple times before acceptance. Each call replaces the previous data:
// Set initial data
tc.setCustomData({ step: 1, name: 'John' });
// This replaces the previous data entirely
tc.setCustomData({ step: 2, email: 'john@example.com' });
// Now only { step: 2, email: 'john@example.com' } is stored
// The 'name' field is lost
To update incrementally, maintain the data object yourself:
let customData = { step: 1, name: 'John' };
tc.setCustomData(customData);
// Update incrementally
customData.step = 2;
customData.email = 'john@example.com';
tc.setCustomData(customData);
// Now { step: 2, name: 'John', email: 'john@example.com' } is stored
Custom data is immutable once the acceptance is created. You can only update custom data before calling TC.accept(). After acceptance, the custom data is permanently stored with the acceptance record and cannot be changed.
Retrieving Custom Data
Custom data is included in:
- PDF Agreements - Generated when acceptances are created
- REST API responses - When retrieving acceptance records via the API
Custom data is not displayed in the ToughClicks Management Portal interface, but it is included in downloaded PDFs.
Custom Data vs Email Address
| Feature | Custom Data | Email Address |
|---|---|---|
| Searchable in dashboard | No | Yes (if set) |
| Included in PDF | Yes | Yes |
| Structure | Any object | Single string |
| Purpose | Additional context | Primary contact/search |
| Required | No | Recommended |
Use both together for best results:
// Primary identifier
tc.setDisplayOptions({
signerId: user.uuid
});
// Searchable email
tc.setSignerEmailAddress(user.email);
// Additional context
tc.setCustomData({
profile: { age: 30, location: 'US' },
account: { type: 'premium' }
});
Best Practices
1. Include Identifying Information
The more information you include, the easier it is to verify the signer in the agreement PDF. Please consider the trade-offs when sharing sensitive information.
tc.setCustomData({
userId: user.id,
username: user.username,
fullName: user.fullName,
phoneNumber: user.phone,
location: user.location
});
2. Link to Your System
Include identifiers that link the acceptance to your internal systems:
tc.setCustomData({
customerId: user.internalId,
accountNumber: user.accountNumber,
registrationSource: 'web-app'
});
3. Record Session Information
Session data helps verify the acceptance context:
tc.setCustomData({
session: {
id: sessionId,
ipAddress: getClientIP(),
userAgent: navigator.userAgent,
referrer: document.referrer,
screenResolution: `${screen.width}x${screen.height}`
}
});
4. Organize Data Hierarchically
Use nested objects to organize related information:
tc.setCustomData({
user: { /* user info */ },
account: { /* account info */ },
session: { /* session info */ },
transaction: { /* transaction info */ }
});
5. Sanitize User Input
ToughClicks sanitizes custom data input to protect against malicious content. However, you should also sanitize user-provided data before sending it:
function sanitize(str) {
// Remove potentially harmful characters
return str.replace(/[<>]/g, '');
}
tc.setCustomData({
userProvidedName: sanitize(userInput.name),
userProvidedCompany: sanitize(userInput.company)
});
This defense-in-depth approach ensures data security at multiple layers.
Related Documentation
- Signer Identifiers - Required identifier and email address
- Manual Acceptance - Control when custom data is submitted
- Display Options - Configure the acceptance flow