API reference

The API is available on the Team plan and above. Below that, every call answers 403 with the code plan_required.

1. In wrkflow, open Settings, API and webhooks and create a key. Pick only the scopes it needs, and an expiry if you can.
2. Copy the key when it is shown. It is shown once, and wrkflow keeps only a hash of it.
3. Send it as a bearer token with every request.

curl https://new.wrkflow.si/api/v1/me \
  -H "Authorization: Bearer wrk_YOUR_KEY"

{
  "organization": { "id": "…", "name": "Northwind Traders", "slug": "northwind", "plan": "team" },
  "key": { "id": "…", "name": "Reporting", "prefix": "wrk_a1b2", "scopes": ["surveys:read", "responses:read"], "expires_at": null }
}

GET /me works with any valid key, so it is the call to test a connection with.

A key looks like wrk_ followed by 32 letters and digits. It belongs to one organization and only ever sees that organization. A key that is revoked or past its expiry stops working at once.

• Rate limit. 600 requests a minute for each key. Beyond that the API answers 429 with the code rate_limited and a Retry-After header in seconds; wait that long and retry.
• IP allowlist. If the organization limits access to certain addresses, the same list applies to API keys (403, ip_not_allowed).
• No caching. Every response carries Cache-Control: no-store.
• Audit log. Reading a survey’s responses or a file is recorded in the organization’s audit log with the key’s name: the first read of each survey by a key each day (UTC), so a sync that polls every minute writes one entry a day.

Errors share one shape: { "error": { "code": "not_found", "message": "No survey with that id." } }. Match on the code; the message is for people.

Lists that can be long (surveys, responses, contacts) page with an opaque cursor. Read next_cursor from a page and send it back; it is null on the last page. Responses and contacts read oldest first, so a sync can keep the last cursor and continue from it later; surveys read newest first.

let cursor = null;
do {
  const url = new URL("https://new.wrkflow.si/api/v1/surveys/SURVEY_ID/responses");
  url.searchParams.set("limit", "500");
  if (cursor) url.searchParams.set("cursor", cursor);
  const res = await fetch(url, { headers: { Authorization: "Bearer wrk_YOUR_KEY" } });
  const page = await res.json();
  for (const response of page.data) handle(response);
  cursor = page.next_cursor;
} while (cursor);

An API key has no person behind it, so it is held to the strictest reading rules. These cannot be switched off from the key.

• Sensitive questions. Answers to a question marked sensitive are never returned. The answer reads { "withheld": "sensitive" } in every response.
• Personal data in written answers (email addresses, phone numbers and similar) is masked.
• Anonymous surveys. Nothing is released until the survey has 5 responses. After that there are no attributes, hidden fields or language, and uploaded files lose their names. Identity is never included in any survey.

The same rules apply to exports, shared reports, the Google Sheets feed and webhooks.

Two events exist. A delivery carries the same item whether you receive it as a webhook, through a hook subscription or by polling.

curl -X POST https://new.wrkflow.si/api/v1/hooks \
  -H "Authorization: Bearer wrk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "event": "response.created", "target_url": "https://example.com/hooks/wrkflow", "survey_id": "SURVEY_ID" }'

{
  "id": "…",
  "event": "response.created",
  "target_url": "https://example.com/hooks/wrkflow",
  "survey_id": "SURVEY_ID",
  "active": true,
  "created_at": "2026-10-06T09:00:00+00:00"
}

Under Settings, API and webhooks you can add a webhook for the events you choose. Each delivery is a POST of JSON with three headers, and a body that wraps the item in data.

POST /hooks/wrkflow HTTP/1.1
Content-Type: application/json
User-Agent: wrkflow-webhooks/1.0
X-Wrkflow-Event: response.created
X-Wrkflow-Delivery: 5d0c…
X-Wrkflow-Attempt: 1
X-Wrkflow-Signature: t=1791277200,v1=9f2c…

{
  "id": "5d0c…",
  "event": "response.created",
  "created_at": "2026-10-06T09:14:04.020+00:00",
  "organization_id": "…",
  "data": {
    "id": "01a10e00-0000-7000-8000-0000000000a1",
    "survey": { "id": "01a10e00-0000-7000-8000-0000000000b1", "title": "Onboarding check-in (day 30)" },
    "response": {
      "id": "01a10e00-0000-7000-8000-0000000000a1",
      "submitted_at": "2026-10-06T09:14:03.120Z",
      "answers": { "enps": { "value": 9 } },
      "attributes": { "department": "Engineering" },
      "source": "invitation",
      "language": "sl",
      "version_id": "01a10e00-0000-7000-8000-0000000000c1",
      "anonymous": false
    }
  }
}

A survey.published delivery has this in data:

{
  "id": "01a10e00-0000-7000-8000-0000000000b1:1",
  "survey": { "id": "01a10e00-0000-7000-8000-0000000000b1", "title": "Onboarding check-in (day 30)", "public_id": "k3v9q2", "url": "https://new.wrkflow.si/s/k3v9q2" },
  "version": 1,
  "published_at": "2026-10-06T08:00:00.000Z"
}

X-Wrkflow-Signature holds a timestamp and an HMAC-SHA256 of <timestamp>.<raw body> made with the webhook’s signing secret. Check it against the raw bytes you received, before parsing, and reject anything older than a few minutes:

import { createHmac, timingSafeEqual } from "node:crypto";

// header: X-Wrkflow-Signature: t=<unix seconds>,v1=<hex>
export function verify(rawBody: string, header: string, secret: string) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = Buffer.from(createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex"));
  const given = Buffer.from(parts.v1 ?? "");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  return fresh && given.length === expected.length && timingSafeEqual(given, expected);
}

• Answer with a 2xx within ten seconds. Anything else (another status, a timeout, no answer) is tried again after 1 minute, 5 and 30 minutes, 2, 5 and 10 hours and 10 hours again: eight attempts over about a day. Then the delivery is marked failed, and an admin can send it again from the webhook’s log in Settings for 30 days.
• Every attempt of a delivery has the same X-Wrkflow-Delivery id and body, and says which attempt it is in X-Wrkflow-Attempt; it is signed again each time. Use the delivery id to ignore one you have already handled.
• Answer 410 Gone to stop: that delivery is not retried, and a subscription made through /hooks (Zapier, Make) is removed.
• Each delivery’s status, HTTP code, attempts and next try are in the webhook’s log under Settings, API and webhooks. Pausing a webhook drops the deliveries waiting for a retry.
• Deliveries for an anonymous survey are held until it has 5 responses and are sent only for days before today (UTC), in no particular order, so timing gives nothing away that an export would not.
• A submission never waits for a webhook and never fails because of one.

These hooks and triggers are what a Zapier or Make integration is built on. wrkflow does not publish an app in either marketplace; the help center explains how to build your own.