ClickWrap API Integration

Sample showing how to collect a ClickWrap consent, search consents, and retrieve an audit trail through the raw REST API (ClickWrap.Integrators.Api) — no browser, no widget, no JS import. Two equivalent ways to run it: an interactive Node.js CLI, and a Postman collection.

It targets the same agreement as the sibling clickwrap-web-integration-sample repo (test-agreement-01, demo environment), so the two samples can be compared side by side: one collects consent via the embeddable widget, this one via direct API calls.

Structure

config.json         integration parameters (API base URL, agreement group guid, environment, referer)
index.js            CLI entry point (menu)
src/api.js           the four API calls
src/commands/        one file per menu action
postman/             Postman collection, same four calls

How the integration works

1. Fetch the agreement. GET /api/Agreement/LastEnvironmentVersion?groupGuid=&environment= returns the current version of the agreement for that group/environment: its clauses (labels[].tag) and the form field names it expects (fieldCollection, e.g. name,surname,email). This sample calls it to build the consent request generically for whatever agreement agreementGroupGuid points to, which is what a demo CLI needs. A real integration with a fixed form usually already knows its clause tags and field names (from the backoffice's Code tab) and doesn't need this call to drive what it sends — knowing a clause or field was added doesn't supply the value for it, that still requires a code change to collect it from somewhere. Calling this endpoint mainly buys you certainty that you're notarizing the agreement version actually in effect, not protection against the agreement changing out from under you.
2. Submit the consent. POST /api/Consent records the consent: the same agreementGroupGuid, one entry per clause (tag + accepted), the user's IP, an externalID you choose to identify the user, the environment, and a fieldCollection object with a value for each field name from step 1.
3. Search consents. POST /api/Consent/List filters by external ID, user identifier, date range, etc. Its environment field is spelled enviroment (typo, matches EnviromentEnum's own misspelling) — unlike Create Consent's environment. Sending the wrong name doesn't error, it's just silently ignored, which looks like "no results" rather than a request bug.
4. Get the audit trail. GET /api/Consent/GetAuditTrail/{guid} returns the audit trail PDF for a given consent guid.

Every request needs an apiKey header (the organization's API key, issued by the ClickWrap backoffice). POST /api/Consent additionally requires a Referer header, which must match one of the trusted domains configured for the agreement.

Running the Node.js CLI

npm install
export CW_API_KEY="your-demo-organization-api-key"
npm start -- --environment=0

--environment selects the API's EnviromentEnum (0 = Staging, 1 = Production; the names also work: --environment=Staging). It defaults to 1/Production when omitted — right now all of our demo consents were created under Staging, so pass --environment=0 (or --environment=Staging) to find them; the default run against Production will find nothing.

It shows a menu with three actions:

• Crea consenso — fetches the agreement's clauses and field names, asks for an external ID, a user IP, a yes/no per clause, and a value per field, then submits the consent.
• Cerca consenso — asks for optional filters (external ID, user identifier, date range, paging) and prints the matching consents in a table.
• Recupera audit trail — asks for a consent guid and an output path, then saves the audit trail PDF there.

It reads config.json for apiBaseUrl/agreementGroupGuid/referer, so those only need to be set once.

Running the Postman collection

Import postman/ClickWrap-Api-Integration-Sample.postman_collection.json. It has the same four calls as collection variables (apiBaseUrl, agreementGroupGuid, environment, referer already set to the demo/test-agreement-01 defaults) plus an empty apiKey variable to fill in.

Run Create Consent first — its test script stores the response's guid and externalID into collection variables (consentGuid, lastExternalId), which Search Consents and Get Audit Trail pick up automatically. For the audit trail PDF, use Postman's "Save Response" → "Save to a file" (it's a binary body, not JSON).

Where to find apiKey and agreementGroupGuid for your own agreement

The ClickWrap backoffice's Code tab for an agreement shows the cwGuid used by the widget sample — that's the same value as agreementGroupGuid here. The organization apiKey is issued separately (Integrators API credentials), not shown on that tab.

Notes

• The consent starts in status Registered/Queued and is notarized asynchronously by the ClickWrap background worker — POST /api/Consent does not wait for notarization, it only confirms the consent was recorded.
• Every run creates a real consent record on the demo environment, associated with the externalID you pass — it is not a simulated call.
• screenshot is sent as an empty string in this sample. The API expects a base64-encoded image; a real integration should capture and send a real screenshot of what the user agreed to, if the agreement requires it (AllowScreenshot/Required fields on the agreement).