Skip to main content
Version: Isle Royale (2.5.0)

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 with JSON.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.

warning

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
Immutability After Acceptance

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:

  1. PDF Agreements - Generated when acceptances are created
  2. 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​

FeatureCustom DataEmail Address
Searchable in dashboardNoYes (if set)
Included in PDFYesYes
StructureAny objectSingle string
PurposeAdditional contextPrimary contact/search
RequiredNoRecommended

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
});

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.