Nudge API

Version 2026-10-22 · from Starter · for Zapier, Make and your own integrations

With the Nudge API you fetch leads and Nudges, and Nudge sends you a message as soon as something happens: a new lead, a meeting, a reply to a follow-up email or a won deal. That is how you connect Nudge to your CRM, your accounting or your own system. Using Zapier or Make? Then you do not need any of this: the Nudge app handles it.

The API, the Zapier and Make apps and your own webhook are included from Starter and up. Prefer no API? Every organisation on Starter or higher also has its own webhook under Settings → Integrations, with the same messages.

1. Create a key

In Nudge, go to Settings → Integrations → API keys and create a key. You see it once; store it safely and never paste it into a chat or email. Only the owner or an admin can create and revoke keys.

Send the key with every request:

Authorization: Bearer nk_live_…

Base URL: https://app.nudgedigital.nl/api/v1. Limit per minute for your whole organisation: Starter 60, Growth 120, Scale 300, Agency 600 (and at most 120 per key). Above that you get 429.

2. Security

  • A key only gives access to the data of your own organisation. We do not store the key itself, only a hashed fingerprint.
  • If you remove someone from your team, or they are no longer an admin, the keys they created are revoked immediately. Zapier and Make connections on those keys stop too.
  • Each key shows when it was used and for which endpoint, with the start of a hashed IP address. So you notice right away if something odd happens.
  • Webhooks only go to public https addresses. The address is checked again on every delivery, including at the moment of connecting.
  • If you go back to Free, the API, webhooks and integrations stop until you choose a plan again.

3. Endpoints

  • GET /me: which organisation the key belongs to. Useful as a connection test.
  • GET /leads?limit=25&since=2026-10-01T00:00:00Z&widget_id=…: leads, newest first, at most 100 per call. Leads over your plan's monthly limit come without contact details ("locked": true), just like in your Lead Vault.
  • GET /widgets: your Nudges, with id, name and status.
  • GET /hooks, POST /hooks, DELETE /hooks/{id}: webhook subscriptions, see below.

A lead looks like this:

{
  "id": "6d1c…",
  "name": "Sanne de Vries",
  "email": "sanne@example.com",
  "phone": "+31612345678",
  "company": "Example B.V.",
  "score": 82,
  "tier": "hot",
  "status": "new",
  "dealValue": null,
  "widgetId": "a41f…",
  "widgetName": "Growth scan",
  "sourceUrl": "https://example.com/pricing?utm_source=google",
  "answers": [{ "questionId": "q1", "label": "Biggest challenge?", "value": "Not enough time" }],
  "locked": false,
  "leadCreatedAt": "2026-10-22T09:14:03.000Z"
}

4. Webhook subscriptions

Let Nudge send a message as soon as something happens. Create a subscription with:

POST /api/v1/hooks
{ "url": "https://your-system.com/nudge", "event": "lead.new" }

→ 201 { "ok": true, "id": "…", "event": "lead.new", "secret": "nwh_…" }

Events: lead.new, lead.status_changed (with deal value when won), lead.replied, meeting.scheduled and meeting.cancelled. For a new lead the lead id is in id, for the other events in leadId. At most 25 subscriptions per organisation.

Every message is JSON with event, eventId and createdAt, signed with the subscription's secret:

X-Nudge-Signature: t=1761124443,v1=5f2b…
// v1 = HMAC-SHA256(secret, `${t}.${body}`) in hex. Reject messages older than 5 minutes.

Reply with a 2xx code. If that fails, Nudge retries after about 1, 5 and 30 minutes. Reply with 410 Gone and Nudge deletes the subscription.

5. Errors

  • 400: invalid input; the message says what is wrong.
  • 401: no key, an unknown key or a revoked key.
  • 403: your plan has no API access (Free).
  • 404: not found, or not part of your organisation.
  • 409: limit reached (keys or subscriptions).
  • 429: too many requests; wait a minute.

Every error is JSON: { "ok": false, "error": "…" }. Every response has the header Nudge-Api-Version.

6. Privacy

Through the API you fetch personal data of leads. You are responsible for it, including in the system you send it to. Zapier, Make or your own system are not Nudge sub-processors but integrations you choose yourself; see the data processing agreement and the sub-processors.

Questions, or building an integration for your clients? Email info@nudgedigital.nl.

7. Nudge in your AI assistant (MCP)

Just ask Claude, ChatGPT or Cursor: "Which hot leads came in this week?" or "Where do visitors drop out of my scan?". Add this address as a connector (MCP):

https://app.nudgedigital.nl/api/mcp
  • You sign in with your Nudge account and choose which account the assistant may see. No key to copy.
  • View: Nudges, numbers per question, leads and their answers.
  • Build: ask "Build a scan for my site" and the assistant sets up a draft Nudge. Visitors only see it once you review it in the builder and publish it. The assistant cannot delete, send or change anything that is already live.
  • Does the app not support signing in, like Claude Code? Send an API key instead: Authorization: Bearer nk_live_….
  • Disconnect any time under Settings → Integrations. From the Starter plan, for owners and admins.

What does your Nudge look like?

Paste your website, or tell us what you do. You'll see it within a few seconds.