NextNote API

Pipe external leads straight into your CRM, works with GHL, Zapier, Make, or any system that can fire an HTTP POST.

You need a NextNote account to use this API. Customers mint keys from Settings → Lead intake keys inside the dashboard. This page is the reference doc for your team or integrator.

What you can do today

Your API key authorizes one endpoint right now: POST /api/public/lead-intake. Each call drops a new prospect into a folder you pick. If you’ve enabled Auto-bridge in settings, qualifying leads also trigger an outbound bridge call to connect you with the lead live the moment they opt in.

• Create or dedupe a prospect by phone or email
• Route leads to a specific folder per-key or per-call
• Fire a live auto-bridge call (when enabled in Settings)
• Auto-build an AI receptionist for the lead’s business (when enabled)
• Tag leads with campaign / consent metadata for compliance

Authentication

Mint a key from Settings → Lead intake keys. The full secret shows once at mint time, copy it then. NextNote only stores a bcrypt hash, so a lost key can’t be recovered (only revoked and replaced).

Send your key with the request in one of three ways. Pick whichever your integration platform makes easiest:

Authorization header

Authorization: Bearer nn_live_...

Standard REST

X-NextNote-Key

X-NextNote-Key: nn_live_...

Plays nice with restrictive proxies

?key=… on the URL

?key=nn_live_...

Easiest for GHL workflows

POST /api/public/lead-intake

POSThttps://nextnote.to/api/public/lead-intake

Request body (JSON)

Field	Type	Required	Notes
name	string	optional	Lead full name. Falls back to "Unknown lead" if missing. Aliases: full_name, contact_name.
phone	string	one of phone/email	E.164 or US 10/11 digit, auto-normalized. Aliases: phone_number, contact_phone.
email	string	one of phone/email	Lowercased server-side. Aliases: contact_email. At least one of phone or email is required.
website	string	optional	Lead's website. Aliases: contact_website. Used by the auto-build to derive a business name.
business_name	string	optional	Used by the auto-build receptionist flow. Aliases: businessName, company, company_name.
niche	string	optional	Industry hint used by the auto-build receptionist. Aliases: industry, vertical.
services	string	optional	Services the lead's business offers. Used by the auto-build to populate the receptionist's knowledge base.
folder_name	string	optional	Routes this specific lead to a folder by name. Overrides the key's default folder. Created on first use.
source	string	optional	Where the lead came from. Defaults to "external_intake". Aliases: consent_source.
campaign	string	optional	Campaign tag stored on the prospect. Alias: consent_campaign.
consent_recorded_at	ISO timestamp	optional	When the lead opted in. Defaults to now if omitted.

Folder routing priority

folder_name on the request body (per-call override)
Default folder you picked when you minted the key
Auto-created “Lead Intake” fallback folder

Examples

bash

curl -X POST 'https://nextnote.to/api/public/lead-intake?key=nn_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Jane Cooper",
    "phone": "+15555550182",
    "email": "jane@example.com",
    "source": "Meta Ads",
    "campaign": "Aug Funnel. Roofing",
    "folder_name": "Meta Ads. Aug"
  }'

Success response

json

{
  "ok": true,
  "prospectId": "p_8f3...",
  "created": true,        // false when an existing prospect was updated instead
  "deduped": false,       // present only when we matched an existing phone/email
  "phoneCaptured": true,
  "bridgeFired": false,   // true when Auto-bridge dialed the lead
  "autoBuildQueued": true // true when an AI receptionist build was queued
}

Error responses

Code	Type	Notes
401	Unauthorized	Key missing, malformed, or revoked.
400	Bad request	Both phone AND email empty, or invalid email format.
429	Rate limited	300 requests / minute / key. Includes retryAfterSec in the body.
500	Server error	Database or routing failure. Safe to retry. POSTs are idempotent on phone/email.

What it costs

Lead intake calls draw from your NextNote credit balance. Charges are best-effort, if your balance is low we will still process the lead and log a shortfall (we never silently drop a lead because of low credits).

2 credits ($0.02) per successful POST /api/public/lead-intake call. Webhook retries from the same prospect id are idempotent, you’re never charged twice for the same lead.
50 credits ($0.50) per auto-built AI receptionist. Only deducted when the auto-build chain actually creates a receptionist for the new lead’s business, disabled? Not charged.
Bridge calls bill the standard per-minute voice rate, same as any other inbound or outbound call on the platform.

Behaviors to know

Dedupe by phone first, then email

If a prospect already exists under your account with the same phone (or, failing that, email), we update them in place instead of creating a duplicate. The response sets deduped: true.

Phone is optional but unlocks Auto-bridge

Leads without a phone still land in your CRM so you can follow up by email. Phone + verified forwarding number + toggle on in Settings is what triggers the live bridge call.

Per-key rate limit: 300 / minute

Generous enough for bursty funnel traffic. Hits return 429 with retryAfterSec, back off and retry.

GET works for sanity checks

A GET with your key returns 200 if the key is valid. Use it to verify your URL is wired up before sending real leads.

Auto-build cap: 20 receptionists / 24 hours / account

A rolling-window guardrail so a misconfigured funnel can’t accidentally spawn thousands of AI agents overnight. Lead intake keeps working past the cap; only the auto-build step is skipped.

Lost a key? The full secret never leaves the database after mint. Revoke the old key from Settings and mint a fresh one, same folder routing, new secret.