> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usertick.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Developers

> Changes to the SDK, the REST API, webhooks and the MCP server.

**October 2026**

## Identify your users

* **`Usertick.identify(userId, traits, { hash })`** is now sent with each response: the user id, the traits and an anonymous id for this browser. Nothing is sent before Submit. The site's **Send user identity with responses** and the survey's **Anonymous responses** turn it off. [Identify your users](https://docs.usertick.com/installation/identify.md).
* **`Usertick.logout()`** forgets the id, the traits and the token, and starts a new anonymous id. `identify(null)` now clears the traits too.
* **Identity verification.** Your server computes a user hash, the HMAC-SHA256 of the user ID with your organization's `utid_` secret, once per user; it never expires. Verification has three modes (Off, Monitor and Enforced), the keys rotate with 24 hours of overlap, and the results say why a hash failed. The guide and Settings have server examples in Node.js, Python, PHP, Ruby, Go, Java and .NET, and Settings checks a user ID and its hash. Changing the mode or deleting a key asks for two-factor authentication, like creating a key. [Verify your users](https://docs.usertick.com/installation/verify-users.md).
* **Link surveys** read the user from `uid` and `uh` in the link, then remove both from the address bar. A reload of the same tab keeps them, and a link with a hash can be emailed or printed, because the hash never expires. [Link surveys](https://docs.usertick.com/installation/identify.md#link-surveys).
* **Console warnings** name a hash passed as the bare third argument of `identify()`, a hash that isn't 64 hex characters and an options object that still carries `token`.
* **The site switch holds on the server.** With **Send user identity with responses** off, Usertick drops an identity that reaches it from that site anyway.
* **REST API and webhooks.** The Response resource has `respondent`, and `contact` is the linked contact in webhook deliveries too. `GET /responses` takes `userId`, and `POST /responses/erase` takes `{ "userId" }` next to `{ "email" }`. [The Response resource](https://docs.usertick.com/developers/api/response-object.md), [Erase personal data](https://docs.usertick.com/developers/api/erasure.md).
* **Integrations** name the person by your user id or the email, never the anonymous id. [How a tool knows who answered](https://docs.usertick.com/integrations/overview.md#how-a-tool-knows-who-answered).

## REST API v1

The REST API now covers responses, surveys, metrics, erasure and webhooks. It replaces the earlier endpoints.

* **Base URL** `https://app.usertick.com/api/public/v1`. Replies are plain JSON. Lists are `{ data, nextCursor }` with a `limit` of 1 to 100. [Pagination](https://docs.usertick.com/developers/api/pagination.md).
* **Responses**: list with the inbox's filters, including `updatedSince` for syncing, read one, change status, type, urgency and assignees, and read, add, edit and delete notes. Files download through short-lived links. [Overview](https://docs.usertick.com/developers/api/overview.md).
* **Surveys and more**: list surveys, read one with its questions, pause and resume it, and list sites, members and the analysis tree.
* **Metrics**: counts, NPS, CSAT, CES and average scores, time series and breakdowns. [Metrics](https://docs.usertick.com/developers/api/metrics.md).
* **Erasure**: erase one response, or everything one person sent, as a job you can follow. [Erase personal data](https://docs.usertick.com/developers/api/erasure.md).
* **One Response resource** for API answers and webhook deliveries. [The Response resource](https://docs.usertick.com/developers/api/response-object.md).
* **Conventions**: every error has a stable `code`, plus an `errors` list for invalid fields. Every reply has `X-Request-Id` and rate limit headers for the key and the organization. Every POST takes an `Idempotency-Key`. Changes within v1 are additive, and anything that will go away is announced six months ahead. [Errors](https://docs.usertick.com/developers/api/errors.md), [Idempotency](https://docs.usertick.com/developers/api/idempotency.md), [Versioning](https://docs.usertick.com/developers/api/versioning.md).
* **API reference**: every endpoint has its own page, with **Try it** on each one. [The API reference](https://docs.usertick.com/developers/api/overview.md#the-api-reference).
* **OAuth for approved apps**, like Zapier: authorization code with PKCE, rotating refresh tokens and revocation. [OAuth for apps](https://docs.usertick.com/developers/api/oauth.md).
* **Removed**: `GET /auth/test` (use `GET /me`), `GET /zapier/responses` (use `GET /responses/recent`), the earlier response list (use the new `GET /responses`), and the public `GET /openapi.json` (the [API reference](https://docs.usertick.com/developers/api/overview.md#the-api-reference) documents every endpoint).

## API keys belong to the organization

A key keeps working when the person who made it leaves. Changes it makes show in the activity log as made through the key. Keys can expire and rotate with 24 hours of overlap, and **Edit access** changes what a live key can do from its next request. Each key shows a usage chart and its latest calls, and **Show all** opens its request log of the last 7 days with a **Status** filter. New scopes: `surveys:read`, `surveys:write`, `responses:delete`, `analytics:read` and `webhooks:read`. [Authentication](https://docs.usertick.com/developers/api/authentication.md).

## Webhooks

* Deliveries are signed the Standard Webhooks way: `webhook-id`, `webhook-timestamp` and `webhook-signature`, with `whsec_` secrets. The `X-Usertick-Signature` and `X-Usertick-Delivery` headers are gone. [Verify signatures](https://docs.usertick.com/developers/webhooks/verify.md).
* A response delivery is `{ id, type, createdAt, data }`, with the Response resource in `data`. [Events](https://docs.usertick.com/developers/webhooks/events.md).
* The delivery log keeps request and response bodies for 30 days, and **Send again** resends a delivery with the same `webhook-id`. Account notifications are now retried like responses. [Delivery and retries](https://docs.usertick.com/developers/webhooks/delivery.md).
* Notifications about one person, such as mentions, are no longer sent to webhooks.
* Four AI events: `response.status_changed`, `response.classification_corrected`, `response.urgent` and `theme.spiking`, for subscriptions and for endpoints in Settings. Filters now take `themes` next to types and urgencies, and `GET /responses/recent` lists status changes and urgent responses. [AI events](https://docs.usertick.com/developers/webhooks/events.md#ai-events).
* **Events wait during a failure pause.** While failures keep a workflow, survey events or a subscription paused, Usertick keeps the events for up to 7 days, at most 1,000 for each, and sends them in the order they arrived after **Turn on**, **Resume** or a new subscribe. A workflow or endpoint turned off by hand, or a pause of the whole organization, keeps nothing. [Events that arrive during a pause](https://docs.usertick.com/developers/webhooks/delivery.md#events-that-arrive-during-a-pause).
* **Up to 100 webhooks** per organization under **Settings → Developers → Webhooks**. Adding one more fails with `WH-005-009`. Subscriptions keep their own limits. [Other limits](https://docs.usertick.com/developers/api/rate-limits.md#other-limits).
* **A workflow's Zapier step.** `POST /webhooks/subscribe` takes the event `workflow.step` with `workflowId` and `stepId`, and the subscription then receives the responses the workflow sends to that step, in the envelope of the event that started the run. `GET /workflows/zapier-steps` lists the steps, and the new codes are `APK-006-013`, `APK-006-014` and `WH-005-010`. [A workflow's Zapier step](https://docs.usertick.com/developers/webhooks/events.md#a-workflows-zapier-step).

## MCP

* **Sign in instead of a key.** Every assistant connects by URL and signs in to Usertick: Claude, ChatGPT, Claude Code, Cursor, VS Code and Gemini CLI on their own, Windsurf and other assistants through the `mcp-remote` bridge. Any member can connect one and chooses what it may do; it works with that member's own role. The MCP server no longer takes API keys, which stay for the REST API. [Connect an assistant](https://docs.usertick.com/developers/mcp.md#connect-an-assistant).
* **Disconnect from Security.** **Settings → Security** lists the assistants you connected, each with **Revoke access**. Members who manage integrations or developer settings see everyone's under **Settings → Developers → API keys**. [Disconnect an assistant](https://docs.usertick.com/developers/mcp.md#disconnect-an-assistant).
* **OAuth for assistants.** Authorization server metadata, Client ID Metadata Documents and client registration, required PKCE, tokens bound to the MCP server and `iss` in every authorization response. [AI assistants](https://docs.usertick.com/developers/api/oauth.md#ai-assistants).
* **A tool for every scope**, 23 in all: list surveys and sites, pause and resume surveys, list themes, update responses and their notes, list members, erase responses, read metrics, and list webhooks and their deliveries and send them again. Every tool says whether it only reads or removes data. [Tools](https://docs.usertick.com/developers/mcp.md#tools).
* `list_responses` takes every response filter and pages by cursor. `test_auth` shows what the connection may do and its rate limits. `subscribe_webhook` and `get_recent_responses` take the AI events and a `themes` filter, and `get_recent_responses` takes a `limit` of 1 to 100 (3 by default).
* **Clearer errors.** A failed tool call carries the API's error code with its message, or every invalid field with its message, and how long to wait when the API sends `Retry-After`, as it does with a `429`. [MCP server](https://docs.usertick.com/developers/mcp.md#tools).

**September 2026**

## identify, and events that carry properties

* **`Usertick.identify(userId, traits)`** tells the widget who the visitor is, for the new sign-in state and trait targeting. Every survey on the page is re-checked at once. (Since October 2026 a response also carries the id and traits; see the October entry.) `identify(null)` on logout. [Reference](https://docs.usertick.com/developers/sdk/reference.md#identify).
* **`Usertick.trigger(name, payload)`** payloads now matter: a custom event trigger can carry property rules, so `plan` is `pro` opens one survey and `plan` is `enterprise` another. Dotted keys reach nested values.
* **`Usertick.reset()`** also forgets the `identify` record and the per-visit counters.
* **Several surveys on a page** all arm their triggers; the first to fire wins. Surveys are re-evaluated on SPA navigation, after `identify`, and when the config refreshes.

**August 2026**

## Coming soon: mobile SDKs

Surveys inside native iOS, Android, React Native and Flutter apps are planned, built in the same editor with the same question types and triggered by screens and events in your app.

## MCP server

Usertick now supports the Model Context Protocol. The **hosted endpoint** at `mcp.usertick.com/mcp` connects any MCP client, such as Claude Code or Cursor, without an install. With the URL and your API key in the client's configuration, a request like "summarize this week's feedback" becomes a tool call against your data. [Setup guide](https://docs.usertick.com/developers/mcp.md).

## REST API reference, expanded

* A dedicated [errors page](https://docs.usertick.com/developers/api/errors.md) lists the envelope, every stable error code and which errors are safe to retry.
* A pagination guide with complete paging loops in JavaScript and Python. The paged list it covered was replaced in October 2026.
* The flat recent responses endpoint, `GET /zapier/responses`, is now fully documented. It was replaced by `GET /responses/recent` in October 2026.
* JavaScript and Python examples on the endpoint pages, next to the existing cURL.

**June 2026**

## Webhooks

Webhooks send signed HTTP deliveries to any system you run, with an HMAC-SHA256 signature on every payload, automatic retries with backoff, a log of every attempt and in-app alerts when an endpoint keeps failing. See the [webhook reference](https://docs.usertick.com/developers/webhooks/overview.md).

**Earlier**

The developer foundation:

* **The snippet**: one script tag, isolated from the page in a Shadow DOM, with response delivery that survives going offline. [Install it](https://docs.usertick.com/installation/website.md).
* **The JavaScript SDK**: the same runtime as an npm package, with the public API (`init`, `on`, `trigger`, `show`, `reset`, `destroy`) and framework guides. [SDK reference](https://docs.usertick.com/developers/sdk/overview.md).
* **The REST API**: scoped `utk_live_` keys from Settings → Developers, response listing with cursor paging, webhook subscriptions, and 120 requests per minute per key with `X-RateLimit-*` headers. [API reference](https://docs.usertick.com/developers/api/overview.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.