Skip to main content
Version: Isle Royale (2.5.0)

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
warning

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, or scroll
  • 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 null if 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"
}
FieldTypeDescription
statusCodenumberThe HTTP status code
messagestring or string[]What went wrong. For request validation errors (400) this is an array with one entry per problem
errorstringThe 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​