Skip to main content
Version: Isle Royale (2.5.0)

Get Packet Details

Retrieve packet and document information to render your acceptance interface.

Endpoint​

GET /api/v1/client/{clientId}/packet/{packetId}

Request​

Path Parameters​

ParameterTypeRequiredDescription
clientIdstringYesYour unique client identifier
packetIdstringYesThe ID of the packet to retrieve

Query Parameters​

ParameterTypeRequiredDescription
dynamicDataobjectYesDynamic data values for token replacement in documents
tip

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​

HeaderValueRequired
acceptapplication/jsonYes

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​

FieldTypeDescription
idstringUnique identifier for the packet
displayNamestringDisplay name of the packet
displayMethodstringSuggested display method: group, individual, or scroll
organizationIdstringID of the organization that owns this packet
customCssstringCustom CSS styles for the packet
shouldOpenModalbooleanWhether the packet should open in a modal
documentsarrayArray of document objects in the packet
createdstringISO 8601 timestamp when packet was created
modifiedstringISO 8601 timestamp when packet was last modified
deletedstring | nullISO 8601 timestamp when packet was deleted, or null if active

Document Object​

FieldTypeDescription
idstringUnique identifier for the document
displayNamestringDisplay name for the document
latestVersionobjectThe most recent published version
latestDraftobject | nullThe current draft version, or null if no draft exists
createdstringISO 8601 timestamp when document was created
modifiedstringISO 8601 timestamp when document was last modified
deletedstring | nullISO 8601 timestamp when document was deleted, or null if active

Version Object​

FieldTypeDescription
idstringUnique identifier for the version
versionNumberstringVersion number in MAJOR.MINOR format
contentsstringHTML content of the document
documentIdstringID 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 dangerouslySetInnerHTML carefully in React
  • Implement Content Security Policy (CSP) headers

Display Method Guidance​

The displayMethod field suggests how to present documents:

  • group - Single checkbox for all documents
  • individual - Separate checkbox per document
  • scroll - 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​