Browse the docs
Connect your CRM
Dialing
Managing the team
Developers
Docs / Developers
API overview
Authenticate with API keys, paginate, handle errors and rate limits in the NitroDialer REST API.
The NitroDialer API lets your own systems add leads to campaigns, pause and resume campaigns, read calls and coaching stats, and manage your do-not-call list. It's a JSON REST API over HTTPS.
Base URL
https://nitrodialer.com/api/v1The machine-readable OpenAPI 3.1 document describes every endpoint; import it into Postman, Insomnia or a code generator. The reference is generated from it.
Authentication
An admin creates API keys in Settings → API keys. A key looks like nd_live_ followed by 32 letters and digits, and is shown once — store it in your secrets manager. NitroDialer only keeps a hash of it.
Send it as a bearer token:
curl https://nitrodialer.com/api/v1/me \
-H "Authorization: Bearer nd_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"Each key has scopes:
| Scope | Allows |
|---|---|
read | Every GET endpoint |
write | Creating and changing things: adding leads, pausing campaigns, editing the do-not-call list |
Keys belong to the workspace, not to a person, so they keep working when the admin who created them leaves. Revoke a key in Settings → API keys; it stops working immediately. Keys stop working while a workspace is suspended.
Errors
Errors use standard HTTP status codes and the same body shape:
{ "error": { "code": "not_found", "message": "No campaign with that id." } }| Status | Code | When |
|---|---|---|
| 400 | invalid_json, invalid_cursor | The body isn't JSON, or the cursor doesn't belong to this list |
| 401 | unauthorized, key_revoked | Missing, malformed, unknown or revoked key |
| 403 | insufficient_scope, workspace_inactive | The key lacks the scope, or the workspace is suspended |
| 404 | not_found | No such object in your workspace |
| 409 | campaign_archived, lead_in_call | The object's state doesn't allow the change right now |
| 422 | invalid_request, invalid_phone | Validation failed; the message lists each problem |
| 429 | rate_limited | Too many requests |
| 500 | internal_error | Something went wrong on our side; safe to retry |
Pagination
List endpoints return newest items first, 25 per page by default:
{ "object": "list", "data": [ … ], "has_more": true, "next_cursor": "2b7e4f55-0d3c-4a11-8a2f-9c6d5e4b3a21" }Pass limit (1–100) and, for the next page, starting_after=<next_cursor>. When has_more is false you've reached the end.
Rate limits
Each key can make 120 requests per minute. Every response includes:
| Header | Meaning |
|---|---|
RateLimit-Limit | Requests allowed per minute |
RateLimit-Remaining | Requests left in the current minute |
RateLimit-Reset | Seconds until the window resets |
A 429 response also includes Retry-After. Limits are counted per server instance, so treat them as a guide and back off on 429 rather than relying on exact counts. To add many leads, send them in batches of up to 500 per request instead of one at a time.
Safe retries
- Adding leads is safe to retry when you send
crm_record_id: a lead with the same CRM record id in the same campaign is updated, not duplicated. - Removing a lead, pausing or activating a campaign and adding a do-not-call number can be repeated with the same result.
Timestamps and phone numbers
All timestamps are ISO 8601 in UTC, for example 2026-10-27T14:03:12.000Z. Phone numbers are returned in E.164 format (+15125550142). You can send them in any common format; numbers without a country code are read as North American.
Versioning
The version is in the path (/api/v1). Within v1 we only make additive changes — new endpoints, new optional parameters, new fields in responses — so ignore fields you don't recognise. Breaking changes would ship as /api/v2 with notice.
Webhooks
To be told when calls finish or leads arrive instead of polling, set up webhooks.