Getting Started with the REST API
The ToughClicks REST API provides programmatic access to all ToughClicks features, allowing you to integrate document acceptance tracking directly into your application without using the JavaScript SDK.
Prerequisites
Before you begin, make sure you have:
- Client ID: Your unique client identifier from the ToughClicks Management Portal
- Packet ID: The ID of the document packet you want to use
For testing purposes, you can use these credentials:
- ClientId:
477951a5-069b-401f-ab7f-32db486d5741 - PacketId:
3646a13b-cbd1-482c-9947-460cb74a71f2
These test credentials are for demonstration only and may change at any time. Get your own credentials from the ToughClicks Management Portal.
Environments
ToughClicks provides two environments for integration:
Staging Environment
https://api.stage.toughclicks.com/api/v1/...
Use this for testing your integration without affecting production data.
Production Environment
https://api.toughclicks.com/api/v1/...
Use this for live production applications.
API Implementation Flow
Step 1: Retrieve Packet Details
Start by fetching the packet details to render your acceptance interface.
Endpoint: GET /api/v1/client/{clientId}/packet/{packetId}
Example Request:
curl --request GET \
--url 'https://api.toughclicks.com/api/v1/client/{clientId}/packet/{packetId}?dynamicData={}' \
--header 'accept: application/json'
This returns all the information needed to render the interface for the signer, including:
- Document display names
- HTML contents of the latest version
- Version numbers and metadata
- Custom CSS and display settings
See: Get Packet Details for full documentation.
Step 2: Create Acceptance Records
Once the signer has accepted the terms, create the acceptance records.
Endpoint: POST /api/v1/client/{clientId}/accept
Example Request:
curl --request POST \
--url https://api.toughclicks.com/api/v1/client/{clientId}/accept \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '{
"displayMethod": "group",
"signerIdentifier": "string",
"signerEmailAddress": "string",
"packetId": "{packetId}",
"applicationContext": {
"source": "web-app"
},
"customData": {},
"dynamicData": {}
}'
Required Fields:
- displayMethod - How the terms were displayed:
group,individual, orscroll - packetId - The ID of the packet being accepted
- applicationContext - JSON object with context about the acceptance (device type, screen size, referrer, page title, URL, timezone, browser version, OS, etc.)
Optional Fields:
- signerIdentifier - Any unique identifier for the user (email, user ID, crypto wallet, etc.)
- signerEmailAddress - Email address of the signer. Recommended if using a UUID for signerIdentifier.
- customData - Additional information to help identify the signer (max 1KB, immutable after acceptance)
- dynamicData - Required if using dynamic tokens in your agreements
Once this endpoint returns success, you can allow the user to proceed.
See: Create Acceptance for full documentation.
Step 3: Verify User Acceptance (Optional)
On subsequent sessions, you may want to verify if a user has accepted the most recent version of the terms.
Endpoint: GET /api/v1/client/{clientId}/packet/{packetId}/verify/{signerIdentifier}
Example Request:
curl --request GET \
--url https://api.toughclicks.com/api/v1/client/{clientId}/packet/{packetId}/verify/{signerIdentifier} \
--header 'accept: application/json'
The response includes:
- latestVersion - ID of the current version
- latestAgreement - ID of the latest version the user has agreed to (or
nullif never accepted) - Timestamp information about when the acceptance was created and modified
If the user needs to accept the latest terms, return to Step 1.
See: Verify Acceptance for full documentation.
Authentication
Currently, the ToughClicks REST API uses the Client ID in the URL path for authentication. No additional authentication headers are required.
Error Handling
The API uses standard HTTP status codes:
- 200 OK - Request succeeded
- 400 Bad Request - Invalid request parameters
- 401 Unauthorized - The Client ID has expired
- 403 Forbidden - The request's origin is not in the client's allowed domains
- 404 Not Found - Client ID, Packet ID, or resource not found
- 500 Internal Server Error - Server error
Every error response has the same JSON body:
{
"statusCode": 404,
"message": "Packet not found",
"error": "Not Found"
}
| Field | Type | Description |
|---|---|---|
statusCode | number | The HTTP status code |
message | string or string[] | What went wrong. For request validation errors (400) this is an array with one entry per problem |
error | string | The status text, e.g. Bad Request. May be absent on 500 responses |
A validation error looks like this:
{
"statusCode": 400,
"message": ["applicationContext must be an object"],
"error": "Bad Request"
}
Read message as either a string or an array of strings.
Rate Limiting
The ToughClicks API does not currently enforce rate limits, but we recommend implementing reasonable request throttling in your application to ensure optimal performance.
Next Steps
- Get Packet Details - Retrieve packet and document information
- Create Acceptance - Record user acceptances
- Verify Acceptance - Check user compliance
- Core Concepts - Understand key terminology
- Dynamic Contracts - Use tokens in your agreements