Get Packet Details
Retrieve packet and document information to render your acceptance interface.
Endpoint
GET /api/v1/client/{clientId}/packet/{packetId}
Request
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
clientId | string | Yes | Your unique client identifier |
packetId | string | Yes | The ID of the packet to retrieve |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
dynamicData | object | Yes | Dynamic data values for token replacement in documents |
The API rejects URLs longer than about 8 KB with 414 URI Too Long. If your dynamic data may not fit in the query string, send it in the request body with Render Packet instead.
dynamicData must be a URL-encoded JSON object (or null) and follows the same limits as in request bodies. A value that isn't valid JSON, or breaks a limit, returns 400 Bad Request with a message saying why. (Before release 2.5.0, invalid JSON was silently ignored and the documents were returned unrendered.) HTML tags are stripped from its string values.
Headers
| Header | Value | Required |
|---|---|---|
accept | application/json | Yes |
Response
Success Response
Status Code: 200 OK
{
"id": "3646a13b-cbd1-482c-9947-460cb74a71f2",
"displayName": "User Registration Packet",
"displayMethod": "group",
"organizationId": "org-456",
"customCss": ".custom-style { color: blue; }",
"shouldOpenModal": true,
"documents": [
{
"id": "doc-123",
"displayName": "Terms of Service",
"latestVersion": {
"id": "v1.0",
"versionNumber": "1.0",
"contents": "<h1>Terms of Service</h1><p>Welcome to our service...</p>",
"documentId": "doc-123"
},
"latestDraft": null,
"created": "2025-01-01T00:00:00Z",
"modified": "2025-01-15T10:00:00Z",
"deleted": null
},
{
"id": "doc-456",
"displayName": "Privacy Policy",
"latestVersion": {
"id": "v2.1",
"versionNumber": "2.1",
"contents": "<h1>Privacy Policy</h1><p>Your privacy matters...</p>",
"documentId": "doc-456"
},
"latestDraft": null,
"created": "2025-01-01T00:00:00Z",
"modified": "2025-02-20T14:30:00Z",
"deleted": null
}
],
"created": "2025-01-01T00:00:00Z",
"modified": "2025-02-20T14:30:00Z",
"deleted": null
}
Response Fields
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier for the packet |
displayName | string | Display name of the packet |
displayMethod | string | Suggested display method: group, individual, or scroll |
organizationId | string | ID of the organization that owns this packet |
customCss | string | Custom CSS styles for the packet |
shouldOpenModal | boolean | Whether the packet should open in a modal |
documents | array | Array of document objects in the packet |
created | string | ISO 8601 timestamp when packet was created |
modified | string | ISO 8601 timestamp when packet was last modified |
deleted | string | null | ISO 8601 timestamp when packet was deleted, or null if active |
Document Object
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier for the document |
displayName | string | Display name for the document |
latestVersion | object | The most recent published version |
latestDraft | object | null | The current draft version, or null if no draft exists |
created | string | ISO 8601 timestamp when document was created |
modified | string | ISO 8601 timestamp when document was last modified |
deleted | string | null | ISO 8601 timestamp when document was deleted, or null if active |
Version Object
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier for the version |
versionNumber | string | Version number in MAJOR.MINOR format |
contents | string | HTML content of the document |
documentId | string | ID of the parent document |
Error Response
Status Code: 400 Bad Request
{
"statusCode": 400,
"message": "dynamicData is not valid JSON. Send a URL-encoded JSON object, for example ?dynamicData=%7B%22name%22%3A%22Ada%22%7D",
"error": "Bad Request"
}
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?dynamicData={}' \
--header 'accept: application/json'
With Dynamic Data
curl --request GET \
--url 'https://api.toughclicks.com/api/v1/client/477951a5-069b-401f-ab7f-32db486d5741/packet/3646a13b-cbd1-482c-9947-460cb74a71f2?dynamicData=%7B%22userName%22%3A%22John%20Doe%22%7D' \
--header 'accept: application/json'
Staging Environment
curl --request GET \
--url 'https://api.stage.toughclicks.com/api/v1/client/477951a5-069b-401f-ab7f-32db486d5741/packet/3646a13b-cbd1-482c-9947-460cb74a71f2?dynamicData={}' \
--header 'accept: application/json'
JavaScript Example
async function getPacket(clientId, packetId, dynamicData = {}) {
const params = new URLSearchParams({
dynamicData: JSON.stringify(dynamicData)
});
const response = await fetch(
`https://api.toughclicks.com/api/v1/client/${clientId}/packet/${packetId}?${params}`,
{
method: 'GET',
headers: {
'accept': 'application/json'
}
}
);
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
const packet = await response.json();
return packet;
}
// Usage
const packet = await getPacket(
'477951a5-069b-401f-ab7f-32db486d5741',
'3646a13b-cbd1-482c-9947-460cb74a71f2'
);
console.log('Packet:', packet.displayName);
packet.documents.forEach(doc => {
console.log(`- ${doc.displayName} (v${doc.latestVersion.versionNumber})`);
});
Rendering Documents
async function renderAcceptanceUI(clientId, packetId) {
try {
// Get packet details
const packet = await getPacket(clientId, packetId);
// Create container
const container = document.getElementById('acceptance-container');
// Apply custom CSS if provided
if (packet.customCss) {
const style = document.createElement('style');
style.textContent = packet.customCss;
document.head.appendChild(style);
}
// Render each document
packet.documents.forEach(doc => {
const docElement = document.createElement('div');
docElement.className = 'document';
// Add title
const title = document.createElement('h2');
title.textContent = doc.displayName;
docElement.appendChild(title);
// Add content
const content = document.createElement('div');
content.className = 'document-content';
content.innerHTML = doc.latestVersion.contents;
docElement.appendChild(content);
// Add checkbox
const checkbox = document.createElement('input');
checkbox.type = 'checkbox';
checkbox.id = `accept-${doc.id}`;
checkbox.name = 'acceptance';
const label = document.createElement('label');
label.htmlFor = checkbox.id;
label.textContent = `I agree to the ${doc.displayName}`;
const checkboxContainer = document.createElement('div');
checkboxContainer.className = 'checkbox-container';
checkboxContainer.appendChild(checkbox);
checkboxContainer.appendChild(label);
docElement.appendChild(checkboxContainer);
container.appendChild(docElement);
});
} catch (error) {
console.error('Error rendering acceptance UI:', error);
}
}
// Usage
renderAcceptanceUI(
'477951a5-069b-401f-ab7f-32db486d5741',
'3646a13b-cbd1-482c-9947-460cb74a71f2'
);
Python Example
import requests
import json
from urllib.parse import urlencode
def get_packet(client_id, packet_id, dynamic_data=None):
if dynamic_data is None:
dynamic_data = {}
params = {
'dynamicData': json.dumps(dynamic_data)
}
url = f"https://api.toughclicks.com/api/v1/client/{client_id}/packet/{packet_id}?{urlencode(params)}"
headers = {
"accept": "application/json"
}
response = requests.get(url, headers=headers)
if response.status_code == 200:
packet = response.json()
print(f"Packet: {packet['displayName']}")
for doc in packet['documents']:
version = doc['latestVersion']['versionNumber']
print(f"- {doc['displayName']} (v{version})")
return packet
else:
print(f"Error: {response.status_code}")
raise Exception(response.json()['message'])
# Usage
packet = get_packet(
'477951a5-069b-401f-ab7f-32db486d5741',
'3646a13b-cbd1-482c-9947-460cb74a71f2'
)
React Component Example
import React, { useState, useEffect } from 'react';
function AcceptanceForm({ clientId, packetId, dynamicData = {} }) {
const [packet, setPacket] = useState(null);
const [loading, setLoading] = useState(true);
const [error, setError] = useState(null);
const [accepted, setAccepted] = useState({});
useEffect(() => {
async function fetchPacket() {
try {
const params = new URLSearchParams({
dynamicData: JSON.stringify(dynamicData)
});
const response = await fetch(
`https://api.toughclicks.com/api/v1/client/${clientId}/packet/${packetId}?${params}`,
{
headers: { 'accept': 'application/json' }
}
);
if (!response.ok) {
throw new Error('Failed to fetch packet');
}
const data = await response.json();
setPacket(data);
// Initialize acceptance state
const initialAccepted = {};
data.documents.forEach(doc => {
initialAccepted[doc.id] = false;
});
setAccepted(initialAccepted);
} catch (err) {
setError(err.message);
} finally {
setLoading(false);
}
}
fetchPacket();
}, [clientId, packetId, dynamicData]);
const handleCheckboxChange = (documentId) => {
setAccepted(prev => ({
...prev,
[documentId]: !prev[documentId]
}));
};
const allAccepted = packet?.documents.every(
doc => accepted[doc.id]
);
if (loading) return <div>Loading...</div>;
if (error) return <div>Error: {error}</div>;
if (!packet) return null;
return (
<div className="acceptance-form">
<h1>{packet.displayName}</h1>
{packet.customCss && (
<style>{packet.customCss}</style>
)}
{packet.documents.map(doc => (
<div key={doc.id} className="document">
<h2>{doc.displayName}</h2>
<div
className="content"
dangerouslySetInnerHTML={{ __html: doc.latestVersion.contents }}
/>
<label>
<input
type="checkbox"
checked={accepted[doc.id]}
onChange={() => handleCheckboxChange(doc.id)}
/>
I agree to the {doc.displayName}
</label>
</div>
))}
<button disabled={!allAccepted}>
Continue
</button>
</div>
);
}
export default AcceptanceForm;
Use Cases
1. Render Acceptance Interface
Fetch packet details to display documents to users for acceptance.
2. Check Latest Versions
Compare current versions with previously accepted versions to determine if re-acceptance is needed.
3. Preview Content
Display document content in your application's preview or help sections.
4. Cache Document Data
Store packet information locally to reduce API calls, but always verify against the API before critical operations.
Best Practices
Cache Responsibly
While you can cache packet data for performance, always:
- Set reasonable TTL (e.g., 1 hour)
- Refresh before critical acceptance operations
- Clear cache when users report outdated content
Handle Content Safely
Document content is HTML. Always:
- Sanitize if allowing user-generated content
- Use
dangerouslySetInnerHTMLcarefully in React - Implement Content Security Policy (CSP) headers
Display Method Guidance
The displayMethod field suggests how to present documents:
group- Single checkbox for all documentsindividual- Separate checkbox per documentscroll- Require scrolling through content
You can override this based on your UX needs.
Dynamic Data
The dynamicData query parameter is required. Pass an empty object {} if you don't need dynamic token replacement:
// No dynamic data needed
const packet = await getPacket(clientId, packetId, {});
// With dynamic data
const packet = await getPacket(clientId, packetId, {
userName: "John Doe",
accountType: "Premium"
});
Common Issues
404 Not Found
Possible causes:
- Invalid client ID or packet ID
- Packet not published
- Packet deleted or archived
Empty Documents Array
The packet exists but has no published documents. Check the ToughClicks dashboard to publish document versions.
Content Rendering Issues
If content doesn't render properly:
- Ensure proper HTML escaping
- Check for CSS conflicts
- Verify Content Security Policy allows inline styles
Missing dynamicData Parameter
The dynamicData query parameter is required. If you get a 400 error, ensure you're including it in your request, even if it's an empty object.
Next Steps
- Create Acceptance - Record user acceptances after displaying documents
- Verify Acceptance - Check if user has accepted latest versions
- Dynamic Contracts - Use dynamic tokens in documents
- Managing Documents - Create and version documents