API & Webhooks

With API & Webhooks your own systems (ERP, data warehouse, website backend, automation tools) can work with your NextCRM workspace:

• the REST API reads and changes leads, contacts, tasks and notes, and reads funnels, form submissions, campaigns and team members;
• webhooks notify your server the moment something happens, for example a new lead or a stage change.

Note: Only Workspace Admins can open Settings > API & Webhooks. API access is included in the Business, Agency and Enterprise plans. On other plans existing keys and endpoints stay visible, but new ones cannot be created and API calls are refused.

Where to get each value

Everything comes from NextCRM itself; no third-party account is needed.

Value	Where to get it
API key	Settings > API & Webhooks > Create API key. The full key is shown only once; copy it to your integration (for example n8n, Zapier, Make or your own code) as a Bearer token.
Signing secret	Shown once when you add a webhook endpoint, and again after Rotate secret. Store it on the server that receives the webhooks.
Webhook URL	Comes from your own system or automation tool, for example the production URL of an n8n Webhook node. It must use https.

Setup order: create an API key with the scopes you need > make a first call > add a webhook endpoint with its events > verify the signature on your server > send a test event.

Create an API key

1. Click your profile card at the bottom of the sidebar, choose Settings and open the card API & Webhooks (open API & Webhooks) and stay on the API keys tab.
2. Click Create API key.
3. Enter a Name that tells you where the key is used, for example "ERP sync".
4. Under Permissions, choose Read and/or Write per area. Choose only what the integration really needs.
5. Optionally set an expiry under Expires (30, 90 or 365 days, or a date).
6. Click Create key and copy the key right away with Copy.

Warning: The key is shown only once. NextCRM stores only a fingerprint (hash) of it, so nobody - not even support - can show it to you again. If it is lost, revoke it and create a new one.

The list shows each key with its prefix (for example ncrm_live_1a2b3c4d), permissions, who created it, when it was last used and when it expires. Revoke stops a key immediately.

What a key is allowed to do

A key acts for your workspace with the rights of a Workspace Admin, limited to the permissions you chose:

Permission	Allows
Leads (read / write)	List and read leads; create, update, move to a stage, assign, move to the Trash and restore
Contacts (read / write)	List, read, create, update and delete contacts
Tasks (read / write)	List and read tasks; create, update, complete and archive them
Funnels and stages (read)	Read funnels with their stages
Form submissions (read)	Read forms and their submissions
Campaigns (read)	Read campaigns and their results
Notes and activities (read / write)	Read a lead's notes and timeline; add notes and log calls
Team members (read)	Read names, emails and roles of team members (to assign leads and tasks)
Webhooks (read / write)	Read, register and delete webhook endpoints

The same rules apply as in the app: plan limits (a new lead over your active lead limit lands in Lead Inbox), the Trash (leads in the Trash must be restored before they can be changed; deleting through the API always moves to the Trash), and data never crosses into another workspace. Things only people may do - managing team, roles, billing or API keys, and deleting permanently - are not possible with a key. A key also stops working when the person who created it is no longer a Workspace Admin.

Every change made with a key appears in the lead timeline as API key <name>.

Make your first call

Send the key in the Authorization header. The base URL is https://…/api/v1.

curl https://…/api/v1/leads?limit=10 \
  -H "Authorization: Bearer ncrm_live_..."

Creating a lead:

curl -X POST https://…/api/v1/leads \
  -H "Authorization: Bearer ncrm_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f9c2a10-order-4711" \
  -d '{"first_name":"Ada","last_name":"Lovelace","email":"ada@example.com","value":12000}'

The full reference with every endpoint, field and a curl example is on the API docs tab, publicly at https://…/api/v1/docs, and as an OpenAPI 3.1 file at https://…/api/v1/openapi.json.

Rules every integration should follow

• Responses look like { "data": ..., "meta": { ... } }; errors like { "error": { "code", "message", "details" } } with a field list for validation errors. Dates are ISO 8601 in UTC.
• Pagination: lists return meta.next_cursor; pass it as cursor to get the next page (limit up to 100).
• Idempotency: send an Idempotency-Key header with POST requests. A retry with the same key returns the first result instead of creating a duplicate (for 24 hours).
• Rate limits: 120 requests per minute per key and 600 per workspace. Above that the API answers 429 with a Retry-After header - wait that many seconds.
• Maintenance: during a NextCRM update the API answers 503 MAINTENANCE with Retry-After. Webhooks are held back and delivered afterwards.
• Server only: call the API from your server. Browsers cannot call it (no CORS), and an API key must never be put into a website or app.

Webhooks

1. Open the Webhooks tab and click Add endpoint.
2. Enter the Endpoint URL of your server. It must start with https:// and be reachable from the internet; internal, private and cloud metadata addresses are refused.
3. Choose the Events you want and click Save endpoint.
4. Copy the signing secret (shown once) and store it on your server.
5. Click Send test event to check that your server answers.

Available events: lead.created, lead.updated, lead.stage_changed, lead.assigned, lead.trashed, lead.restored, task.created, task.completed, form.submitted, contact.created, contact.updated, campaign.sent, call.logged, nps.responded, customer.renewal_updated, customer.at_risk, booking.created, booking.rescheduled, booking.canceled, quote.sent, quote.accepted, quote.declined and automation.webhook.

Quote events carry amounts as integers in the currency's smallest unit (for example cents): subtotal_minor is the sum of the lines after line discounts, discount_minor the discount on the whole quote, tax_minor the tax and total_minor the amount to pay. Each item's total_minor is its amount after the line discount, before the quote discount and tax.

Leads created by a file import send one lead.created per imported lead after the import has finished, with "context": { "source": "import", "import_batch_id": "..." } next to data.

Each delivery is a POST with the event as JSON (id, type, created_at, actor, data) and these headers: X-NextCRM-Event, X-NextCRM-Delivery, X-NextCRM-Timestamp and X-NextCRM-Signature.

Verify the signature

X-NextCRM-Signature looks like t=1760860800,v1=5f2b.... Compute HMAC-SHA256 of <t>.<raw request body> with your signing secret and compare it with v1. Reject requests whose timestamp is older than 5 minutes.

import crypto from "node:crypto";

function verify(rawBody, header, secret) {
  const t = Number(/(?:^|,)t=(\d+)/.exec(header)?.[1]);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return header.split(",").some((part) => part === `v1=${expected}`);
}

Retries, delivery log and rotation

• Answer with any 2xx status within 10 seconds. Otherwise NextCRM retries with growing pauses (1, 2, 4, ... minutes) up to 8 attempts.
• Delivery log shows every delivery with its status, attempts and the response code. Send again queues a delivery once more.
• After many failures in a row an endpoint is disabled automatically and all Workspace Admins get a notification. Fix the endpoint, then click Enable.
• Rotate secret creates a new signing secret. The old one keeps signing for 24 hours so you can switch without losing events.

Lora and the API

Lora can explain the API, open this page and list your webhook endpoints. She never creates, shows or revokes API keys and never sees a signing secret - you do that yourself on this page.

Troubleshooting

Answer	Meaning
401 INVALID_API_KEY, API_KEY_REVOKED, API_KEY_EXPIRED	The key is wrong, revoked or expired. Create a new one.
403 INSUFFICIENT_SCOPE	The key lacks the permission for this call. Create a key with the needed permission.
403 API_KEY_OWNER_NOT_ADMIN	The person who created the key is no longer a Workspace Admin. A current admin must create a new key.
402 FEATURE_NOT_IN_PLAN	The plan does not include API access.
409 LEAD_IN_TRASH	Restore the lead first (POST /leads/{id}/restore).
422 VALIDATION_FAILED	See error.details for the field and the reason.
429 RATE_LIMITED	Wait the Retry-After seconds, then continue.