Skip to main content
Every Nudge workspace has a REST API. Anything an admin can do in the app, a key can do over HTTPS: read and write contacts, import a book of leads, create and toggle triggers, manage templates, send WhatsApp messages. What it deliberately cannot do is change your configuration, your schema, or the app itself. The common uses: pushing leads in from a website or another system, syncing contact data with a tool Nudge has no native integration for, and pointing an AI assistant at your workspace so you can ask it to do the boring parts.

​
Getting a key

Go to Settings → API and click New key. Name it after whatever will use it, for example “website” or “Claude”.
The full key is shown once, at creation. Copy it then. Afterwards the table shows only the last four characters, and there is no way to reveal it again. Lost a key? Revoke it and make a new one.
Revoking cuts access immediately. Keys are never deleted, so the record of what existed and when it was last used survives.

​
Making a request

The same screen shows your workspace’s base URL. Every key goes in an Authorization header:
A quick connectivity check:
Responses are JSON. Errors come back as {"error": "..."} with a 400, 401 or 404, and the message says what was actually wrong rather than “bad request”.

​
What you can call

​
Contacts

The bulk import deliberately does not fire triggers. Importing four thousand old leads should not message four thousand people. When you do want an import enrolled in a trigger, enable that trigger with Include current matches afterwards.

​
Triggers

Because POST /triggers matches on name, running the same request twice updates rather than duplicates. That makes it safe to keep your triggers in version control and replay them.

​
Templates and messages

GET, POST, PATCH and DELETE on /templates manage the library. POST /messages sends WhatsApp to one contact or up to 500:
Variables resolve per recipient, exactly like a template send.
API sends join the same paced queue as everything else. A script cannot make your reps’ numbers send faster than the safety settings allow, which is the point.

​
Things worth knowing

  • One key, full access. There are no per-key permissions yet. Treat a key like an admin password and give each integration its own, so you can revoke one without disturbing the others.
  • Creating contacts is standalone-mode only. If your workspace syncs with HubSpot, contacts come from HubSpot and creating them through the API is refused. Reading, updating and sending work in both modes. See Standalone vs HubSpot.
  • WhatsApp only, for now. Email sending through the API is not built yet.
  • Contact ids are stable. In HubSpot mode they are the HubSpot contact id; standalone they look like nudge: followed by a uuid.

​
Watching what happens

Settings → API lists the last 100 requests: when, which key, what was called, the status, and the error for anything that failed. It keeps 30 days. When an integration misbehaves, look here first. It usually tells you the answer without needing anyone to reproduce anything.

​
Using it with an AI assistant

You do not need a REST key for this. Settings → API opens with an AI connectors card: click Connect Claude or Connect ChatGPT, and you get a connector URL and a one-time key to paste into that app’s own connector settings. From then on you can work the CRM by asking — “import these leads”, “which contacts replied this week and got no follow-up”, “turn off the reactivation trigger”. A connector key is not the same thing as a REST key, and the difference matters:
  • A REST key says a program may do admin things. It belongs to the workspace.
  • A connector key says this person’s assistant acts as them. It belongs to whoever created it, every action it takes lands in the activity feed under their name, and reversible ones can be undone.
So give each person their own connector rather than sharing one, and revoke it the same way you revoke any key.