Skip to main content
Version: Isle Royale (2.5.0)

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​

ParameterTypeRequiredDescription
clientIdstringYesYour unique client identifier
packetIdstringYesThe ID of the packet to verify
signerIdentifierstringYesThe unique identifier of the user (same as used in acceptance)

Headers​

HeaderValueRequired
acceptapplication/jsonYes

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​

FieldTypeDescription
idstringThe packet ID that was verified
signerIdentifierstringThe user identifier that was verified
latestVersionstringID of the latest published version
latestAgreementstringID of the most recent acceptance by this user
createdstringISO 8601 timestamp when the first acceptance was created
modifiedstringISO 8601 timestamp when the most recent acceptance was modified
deletedstring | nullISO 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​