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 switch automations on and off, 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

Creating a contact requires a name, phone number or email address. Empty requests are rejected, even if they include a source or status. The bulk import deliberately does not start automations. Importing four thousand old leads should not message four thousand people. When you do want an import enrolled in an automation, turn that automation on afterwards with New and recent matches, using a window that covers the import.

​
Automations

Because POST /triggers matches on name, running the same request twice updates rather than duplicates. That makes it safe to keep your automations 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 automation”. 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.

​
Adding contacts by asking

Paste a list, forward a spreadsheet, or describe someone you just got off the phone with, and the assistant can put them in — up to 100 at a time. Four rules govern it:
  • Nothing gets sent. New contacts arrive as data. No workflow runs and no message goes out, however the contact is staged. Putting a batch through a workflow is a separate decision: enable the workflow in backfill mode.
  • Running the same list twice is safe. Contacts are matched on phone number, then on email address, so someone already on file is updated instead of duplicated. A contact with neither is refused and named back to you — there would be no way to recognise them next time.
  • The stage applies to new contacts only. Someone already on file keeps the stage they have — the assistant will tell you which ones it left alone, and you can ask it to move them.
  • Standalone workspaces only. If your contacts sync from HubSpot, they are created in HubSpot and arrive here on the next sync.

​
Removing contacts by asking

Someone asks to be forgotten, or a batch of test entries needs to go. Tell the assistant who, and it removes the contact together with everything held on them: messages, calls, notes, tasks, files, deals and activity. Anything queued for that person is dropped. Four rules govern it:
  • You see it before it goes. The assistant first shows the names and what goes with each one, and only deletes once you say yes. It works from exact contacts, never from a description, so “everyone called Ali” is a search you look at first.
  • It cannot be undone. Undo refuses it. The activity feed keeps a record of who was removed and by whom; the contact’s own history is gone.
  • Copies elsewhere stay. Call recordings and transcripts sit with the voice platform, and the person’s own phone and email provider keep their side of the conversation. Nudge removes what Nudge holds.
  • Standalone workspaces only, admins only. If your contacts sync from HubSpot, delete them in HubSpot; removing the copy here would only last until the next sync.
Ask it to undo and it deletes what it created, as long as nothing has happened to those contacts since — one that has picked up a message, a note or a deal is kept, and the assistant says which.

​
Bringing your history in

An assistant can also record what has already happened: calls you had, emails from a thread, WhatsApp exchanges, notes, follow-up tasks and deals. This is how a workspace that has been running somewhere else arrives with its past intact rather than starting empty — and it is how you log a call the moment you put the phone down. Nothing is sent. These are records of things that already occurred, written in a finished state that the sending machinery cannot see, so there is no way for a logged message to go out to anybody. Two consequences worth knowing:
  • A logged reply behaves like a real one. It puts the conversation in your Inbox and marks the contact as having replied — which also pauses any chase automation for that contact, exactly as a genuine reply would. That is usually what you want; it is worth knowing before you import a year of history into a workspace with live automations.
  • Messages that went out as one campaign can say so. Tell the assistant they were a campaign and they are grouped on the Bulk Action tab as a single send, with per-recipient results, instead of scattered across timelines.
Deals follow the pipeline you already have: one open deal per contact, so recording a deal on someone who already has one updates it rather than putting a second on the board, and a stage the board has no column for is reported back rather than silently dropped.