Verify User Acceptance
Check if a user has accepted the latest versions of all documents in a packet.
Endpoint
GET /api/v1/client/{clientId}/packet/{packetId}/verify/{signerIdentifier}
Request
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
clientId | string | Yes | Your unique client identifier |
packetId | string | Yes | The ID of the packet to verify |
signerIdentifier | string | Yes | The unique identifier of the user (same as used in acceptance) |
Headers
| Header | Value | Required |
|---|---|---|
accept | application/json | Yes |
Response
Success Response
Status Code: 200 OK
{
"id": "3646a13b-cbd1-482c-9947-460cb74a71f2",
"signerIdentifier": "user@example.com",
"latestVersion": "v1.0",
"latestAgreement": "acc-789",
"created": "2025-01-01T00:00:00Z",
"modified": "2025-03-01T15:45:00Z",
"deleted": null
}
Response Fields
| Field | Type | Description |
|---|---|---|
id | string | The packet ID that was verified |
signerIdentifier | string | The user identifier that was verified |
latestVersion | string | ID of the latest published version |
latestAgreement | string | ID of the most recent acceptance by this user |
created | string | ISO 8601 timestamp when the first acceptance was created |
modified | string | ISO 8601 timestamp when the most recent acceptance was modified |
deleted | string | null | ISO 8601 timestamp when the acceptance was deleted, or null if active |
No Acceptance Response
If the user has never accepted the packet:
{
"id": "3646a13b-cbd1-482c-9947-460cb74a71f2",
"signerIdentifier": "new-user@example.com",
"latestVersion": "v1.0",
"latestAgreement": null,
"created": null,
"modified": null,
"deleted": null
}
Error Response
Status Code: 404 Not Found
{
"statusCode": 404,
"message": "Packet not found",
"error": "Not Found"
}
Examples
Basic Request
curl --request GET \
--url https://api.toughclicks.com/api/v1/client/477951a5-069b-401f-ab7f-32db486d5741/packet/3646a13b-cbd1-482c-9947-460cb74a71f2/verify/user@example.com \
--header 'accept: application/json'
With URL Encoding
If the signer identifier contains special characters, URL encode it:
curl --request GET \
--url https://api.toughclicks.com/api/v1/client/477951a5-069b-401f-ab7f-32db486d5741/packet/3646a13b-cbd1-482c-9947-460cb74a71f2/verify/user%2Btest%40example.com \
--header 'accept: application/json'
JavaScript Example
async function verifyUserAcceptance(clientId, packetId, userId) {
const encodedUserId = encodeURIComponent(userId);
const response = await fetch(
`https://api.toughclicks.com/api/v1/client/${clientId}/packet/${packetId}/verify/${encodedUserId}`,
{
method: 'GET',
headers: {
'accept': 'application/json'
}
}
);
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
const verification = await response.json();
return verification;
}
// Usage
const verification = await verifyUserAcceptance(
'477951a5-069b-401f-ab7f-32db486d5741',
'3646a13b-cbd1-482c-9947-460cb74a71f2',
'user@example.com'
);
if (verification.latestAgreement === null) {
console.log('User has not accepted the terms yet');
// Redirect to acceptance flow
} else if (verification.latestAgreement !== verification.latestVersion) {
console.log('User may need to accept updated terms');
// Check if re-acceptance is required
} else {
console.log('User has accepted the latest version');
// Allow user to proceed
}
Check If User Has Accepted
async function hasUserAccepted(clientId, packetId, userId) {
try {
const verification = await verifyUserAcceptance(clientId, packetId, userId);
return verification.latestAgreement !== null;
} catch (error) {
console.error('Error verifying acceptance:', error);
return false;
}
}
// Usage
const hasAccepted = await hasUserAccepted(
'477951a5-069b-401f-ab7f-32db486d5741',
'3646a13b-cbd1-482c-9947-460cb74a71f2',
'user@example.com'
);
if (!hasAccepted) {
// Redirect to acceptance page
window.location.href = '/accept-terms';
}
Python Example
import requests
from urllib.parse import quote
def verify_user_acceptance(client_id, packet_id, user_id):
encoded_user_id = quote(user_id, safe='')
url = f"https://api.toughclicks.com/api/v1/client/{client_id}/packet/{packet_id}/verify/{encoded_user_id}"
headers = {
"accept": "application/json"
}
response = requests.get(url, headers=headers)
if response.status_code == 200:
verification = response.json()
if verification['latestAgreement'] is None:
print(f"User {user_id} has not accepted terms")
elif verification['latestAgreement'] != verification['latestVersion']:
print(f"User {user_id} may need to accept updated terms")
print(f" Latest version: {verification['latestVersion']}")
print(f" Accepted: {verification['latestAgreement']}")
else:
print(f"User {user_id} has accepted the latest version")
return verification
else:
print(f"Error: {response.status_code}")
raise Exception(response.json()['message'])
# Usage
verification = verify_user_acceptance(
'477951a5-069b-401f-ab7f-32db486d5741',
'3646a13b-cbd1-482c-9947-460cb74a71f2',
'user@example.com'
)
Session Check Middleware
// Express.js middleware example
async function checkTermsAcceptance(req, res, next) {
const userId = req.user.email; // or req.user.id
const clientId = process.env.TOUGHCLICKS_CLIENT_ID;
const packetId = process.env.TOUGHCLICKS_PACKET_ID;
try {
const verification = await verifyUserAcceptance(clientId, packetId, userId);
if (verification.latestAgreement === null) {
// User has never accepted terms
return res.redirect('/accept-terms');
}
// User has accepted (check version comparison in your business logic)
next();
} catch (error) {
console.error('Error verifying acceptance:', error);
next(error);
}
}
// Use in routes
app.get('/dashboard', checkTermsAcceptance, (req, res) => {
res.render('dashboard');
});
React Hook Example
import { useState, useEffect } from 'react';
function useTermsAcceptance(clientId, packetId, userId) {
const [verification, setVerification] = useState(null);
const [loading, setLoading] = useState(true);
const [error, setError] = useState(null);
useEffect(() => {
async function checkAcceptance() {
if (!userId) {
setLoading(false);
return;
}
try {
const result = await verifyUserAcceptance(clientId, packetId, userId);
setVerification(result);
} catch (err) {
setError(err.message);
} finally {
setLoading(false);
}
}
checkAcceptance();
}, [clientId, packetId, userId]);
return {
verification,
loading,
error,
hasAccepted: verification?.latestAgreement !== null
};
}
// Usage in component
function ProtectedRoute({ children }) {
const { verification, loading, hasAccepted } = useTermsAcceptance(
'client-id',
'packet-id',
user?.email
);
if (loading) return <div>Checking acceptance...</div>;
if (!hasAccepted) {
return <Navigate to="/accept-terms" />;
}
return children;
}
Use Cases
1. Session Verification
Check acceptance at the start of each user session to ensure they've accepted the terms.
2. Before Critical Actions
Verify acceptance before allowing users to perform important actions (purchases, data changes, etc.).
3. Periodic Checks
Periodically verify acceptance for long-running sessions or applications.
4. Acceptance Reporting
Generate reports on which users have accepted terms and which haven't.
5. Version Comparison
Compare latestVersion with latestAgreement to determine if there have been updates since the user last accepted.
Best Practices
Cache Verification Results
Cache the verification result for the duration of a user session:
// Cache in session storage
sessionStorage.setItem(
`tc_verification_${userId}`,
JSON.stringify({
verified: verification,
timestamp: Date.now()
})
);
// Check cache first
const cached = sessionStorage.getItem(`tc_verification_${userId}`);
if (cached) {
const { verified, timestamp } = JSON.parse(cached);
const age = Date.now() - timestamp;
// Use cache if less than 1 hour old
if (age < 3600000) {
return verified;
}
}
Handle URL Encoding
Always URL encode the signer identifier:
const encodedId = encodeURIComponent(signerIdentifier);
This is especially important for email addresses and special characters.
Check for Null Values
Always check if latestAgreement is null before comparing with latestVersion:
if (verification.latestAgreement === null) {
// User has never accepted
redirectToAcceptancePage();
} else if (verification.latestAgreement !== verification.latestVersion) {
// User may need to re-accept
checkIfReacceptanceRequired();
} else {
// User is up to date
proceed();
}
Handle Version Changes
The API returns version IDs as strings. You may need to fetch full version details to determine if the user needs to re-accept based on your versioning policy:
async function needsReacceptance(verification) {
if (verification.latestAgreement === null) return true;
if (verification.latestAgreement === verification.latestVersion) return false;
// Fetch packet details to compare version numbers
const packet = await getPacket(clientId, packetId);
// Implement your version comparison logic here
// For example, check if major version changed
return false; // Placeholder
}
Common Issues
User Never Accepted
If latestAgreement is null, the user has never accepted this packet. Redirect to acceptance flow.
Incorrect Signer Identifier
Ensure you're using the same identifier format as when creating acceptances:
- If you used email during acceptance, use email for verification
- If you used UUID, use the same UUID
Version ID Comparison
latestVersion and latestAgreement are version IDs (strings), not full version objects. You may need to fetch the packet details to get full version information for comparison.
404 Errors
If you receive a 404 error:
- Verify the client ID and packet ID are correct
- Ensure the packet is published
- Check that the packet hasn't been deleted
Next Steps
- Get Packet Details - Retrieve current version information
- Create Acceptance - Record user re-acceptance
- Managing Versions - Learn about version management
- Core Concepts - Understand versioning strategy