Browse the docs

Get started

Connect your CRM

Dialing

Managing the team

Developers

Docs / Developers

API reference

Every NitroDialer API endpoint with parameters, request and response examples.

Base URL https://nitrodialer.com/api/v1. Authenticate with Authorization: Bearer nd_live_…. Errors, pagination and rate limits are explained in the API overview. Download the OpenAPI 3.1 document to generate a client.

GET/me
GET/campaigns
GET/campaigns/{id}
PATCH/campaigns/{id}
GET/campaigns/{id}/leads
POST/campaigns/{id}/leads
GET/leads/{id}
DELETE/leads/{id}
GET/calls
GET/calls/{id}
GET/stats/agents
GET/dnc
POST/dnc
DELETE/dnc
GET/dispositions

Workspace

GET/api/v1/meread scope

Get the workspace for this API key

Use this to check that a key works and which CRM the workspace is connected to.

Example request

Shell

curl "https://nitrodialer.com/api/v1/me" \
  -H "Authorization: Bearer $NITRODIALER_API_KEY"

Response · 200

JSON

{
  "object": "workspace",
  "id": "6b1f…",
  "name": "Polaron Comfort",
  "crm_provider": "hubspot",
  "plan": "growth",
  "status": "active",
  "timezone": "America/New_York",
  "created_at": "2026-09-01T12:00:00.000Z",
  "api_key": {
    "id": "a1b2…",
    "scopes": [
      "read",
      "write"
    ]
  }
}

Responses

`200`	The workspace.
`401`	Missing, malformed, unknown or revoked API key.
`403`	The key lacks the required scope, or the workspace is suspended.
`429`	Rate limit exceeded (120 requests per minute per key).

Campaigns

GET/api/v1/campaignsread scope

List campaigns

Newest first. Archived campaigns are excluded unless you filter by status=archived.

Parameters

Name	In	Description
`limit`	query	Items per page, 1–100. Default 25.
`starting_after`	query	Cursor: the `next_cursor` from the previous page.
`status`	query	draft, active, paused or archived.

Example request

Shell

curl "https://nitrodialer.com/api/v1/campaigns" \
  -H "Authorization: Bearer $NITRODIALER_API_KEY"

Response · 200

JSON

{
  "object": "list",
  "data": [
    {
      "id": "8f0b5c2e-6c1a-4f43-9d7e-2b8c1f0a9e11",
      "object": "campaign",
      "name": "Heat pump rebate — web leads",
      "status": "active",
      "mode": "power",
      "call_type": "b2c",
      "assignment": "shared",
      "source": {
        "type": "crm_list",
        "provider": "hubspot",
        "object": "contacts",
        "list_name": "Rebate form — last 30 days"
      },
      "caller_id": "+14165550100",
      "last_synced_at": "2026-10-27T13:30:00.000Z",
      "created_at": "2026-10-20T15:02:11.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Responses

`200`	A page of campaigns.
`401`	Missing, malformed, unknown or revoked API key.
`403`	The key lacks the required scope, or the workspace is suspended.
`422`	The request failed validation.
`429`	Rate limit exceeded (120 requests per minute per key).

GET/api/v1/campaigns/{id}read scope

Get a campaign with queue counts

Parameters

Name	In	Description
`id` required	path	Campaign id (UUID).

Example request

Shell

curl "https://nitrodialer.com/api/v1/campaigns/ID" \
  -H "Authorization: Bearer $NITRODIALER_API_KEY"

Response · 200

JSON

{
  "id": "8f0b5c2e-6c1a-4f43-9d7e-2b8c1f0a9e11",
  "object": "campaign",
  "name": "Heat pump rebate — web leads",
  "status": "active",
  "mode": "power",
  "call_type": "b2c",
  "assignment": "shared",
  "source": {
    "type": "crm_list",
    "provider": "hubspot",
    "object": "contacts",
    "list_name": "Rebate form — last 30 days"
  },
  "caller_id": "+14165550100",
  "last_synced_at": "2026-10-27T13:30:00.000Z",
  "created_at": "2026-10-20T15:02:11.000Z",
  "queue": {
    "ready": 214,
    "in_call": 3,
    "callback": 18,
    "done": 96,
    "exhausted": 41,
    "dnc": 4,
    "removed": 2,
    "total": 378
  }
}

Responses

`200`	The campaign.
`401`	Missing, malformed, unknown or revoked API key.
`403`	The key lacks the required scope, or the workspace is suspended.
`404`	No such object in this workspace.
`429`	Rate limit exceeded (120 requests per minute per key).

PATCH/api/v1/campaigns/{id}write scope

Activate or pause a campaign

Pausing stops agents from receiving new leads from this campaign; calls in progress finish normally.

Parameters

Name	In	Description
`id` required	path	Campaign id (UUID).

Request body

JSON

{
  "status": "paused"
}

Example request

Shell

curl -X PATCH "https://nitrodialer.com/api/v1/campaigns/ID" \
  -H "Authorization: Bearer $NITRODIALER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"paused"}'

Response · 200

JSON

{
  "id": "8f0b5c2e-6c1a-4f43-9d7e-2b8c1f0a9e11",
  "object": "campaign",
  "name": "Heat pump rebate — web leads",
  "status": "paused",
  "mode": "power",
  "call_type": "b2c",
  "assignment": "shared",
  "source": {
    "type": "crm_list",
    "provider": "hubspot",
    "object": "contacts",
    "list_name": "Rebate form — last 30 days"
  },
  "caller_id": "+14165550100",
  "last_synced_at": "2026-10-27T13:30:00.000Z",
  "created_at": "2026-10-20T15:02:11.000Z",
  "queue": {
    "ready": 214,
    "in_call": 3,
    "callback": 18,
    "done": 96,
    "exhausted": 41,
    "dnc": 4,
    "removed": 2,
    "total": 378
  }
}

Responses

`200`	The updated campaign.
`401`	Missing, malformed, unknown or revoked API key.
`403`	The key lacks the required scope, or the workspace is suspended.
`404`	No such object in this workspace.
`422`	The request failed validation.
`429`	Rate limit exceeded (120 requests per minute per key).

Leads

GET/api/v1/campaigns/{id}/leadsread scope

List a campaign's leads

Parameters

Name	In	Description
`id` required	path	Campaign id (UUID).
`limit`	query	Items per page, 1–100. Default 25.
`starting_after`	query	Cursor: the `next_cursor` from the previous page.
`status`	query	Filter by queue status.

Example request

Shell

curl "https://nitrodialer.com/api/v1/campaigns/ID/leads" \
  -H "Authorization: Bearer $NITRODIALER_API_KEY"

Response · 200

JSON

{
  "object": "list",
  "data": [
    {
      "id": "2b7e4f55-0d3c-4a11-8a2f-9c6d5e4b3a21",
      "object": "lead",
      "campaign_id": "8f0b5c2e-6c1a-4f43-9d7e-2b8c1f0a9e11",
      "status": "ready",
      "priority": 100,
      "first_name": "Daniel",
      "last_name": "Okafor",
      "company": null,
      "email": "d.okafor@example.com",
      "phones": [
        {
          "e164": "+15125550142",
          "type": "mobile"
        }
      ],
      "city": "Austin",
      "region": "TX",
      "postal_code": "78701",
      "timezone": "America/Chicago",
      "crm_object": "contacts",
      "crm_record_id": "51234",
      "express_consent": true,
      "attempts": 0,
      "last_attempt_at": null,
      "next_eligible_at": "2026-10-27T14:00:00.000Z",
      "callback_at": null,
      "last_disposition": null,
      "created_at": "2026-10-27T14:00:00.000Z"
    }
  ],
  "has_more": true,
  "next_cursor": "2b7e4f55-0d3c-4a11-8a2f-9c6d5e4b3a21"
}

Responses

`200`	A page of leads.
`401`	Missing, malformed, unknown or revoked API key.
`403`	The key lacks the required scope, or the workspace is suspended.
`404`	No such object in this workspace.
`422`	The request failed validation.
`429`	Rate limit exceeded (120 requests per minute per key).

POST/api/v1/campaigns/{id}/leadswrite scope

Add leads to a campaign

Send one lead as the body, or up to 500 as `{ "leads": [...] }`. Leads with a `crm_record_id` already in the campaign are updated, not duplicated, so retries are safe. Each new lead fires a `lead.created` webhook. Returns 201 when at least one lead was inserted.

Parameters

Name	In	Description
`id` required	path	Campaign id (UUID).

Request body

JSON

{
  "first_name": "Daniel",
  "last_name": "Okafor",
  "mobile": "512-555-0142",
  "region": "TX",
  "crm_object": "contacts",
  "crm_record_id": "51234",
  "express_consent": true,
  "priority": 100
}

Example request

Shell

curl -X POST "https://nitrodialer.com/api/v1/campaigns/ID/leads" \
  -H "Authorization: Bearer $NITRODIALER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Daniel","last_name":"Okafor","mobile":"512-555-0142","region":"TX","crm_object":"contacts","crm_record_id":"51234","express_consent":true,"priority":100}'

Responses

`200`	Nothing new inserted (all updates or skips).
`201`	Leads inserted.
`401`	Missing, malformed, unknown or revoked API key.
`403`	The key lacks the required scope, or the workspace is suspended.
`404`	No such object in this workspace.
`409`	The campaign is archived.
`422`	The request failed validation.
`429`	Rate limit exceeded (120 requests per minute per key).

GET/api/v1/leads/{id}read scope

Get a lead

Parameters

Name	In	Description
`id` required	path	Lead id (UUID).

Example request

Shell

curl "https://nitrodialer.com/api/v1/leads/ID" \
  -H "Authorization: Bearer $NITRODIALER_API_KEY"

Response · 200

JSON

{
  "id": "2b7e4f55-0d3c-4a11-8a2f-9c6d5e4b3a21",
  "object": "lead",
  "campaign_id": "8f0b5c2e-6c1a-4f43-9d7e-2b8c1f0a9e11",
  "status": "ready",
  "priority": 100,
  "first_name": "Daniel",
  "last_name": "Okafor",
  "company": null,
  "email": "d.okafor@example.com",
  "phones": [
    {
      "e164": "+15125550142",
      "type": "mobile"
    }
  ],
  "city": "Austin",
  "region": "TX",
  "postal_code": "78701",
  "timezone": "America/Chicago",
  "crm_object": "contacts",
  "crm_record_id": "51234",
  "express_consent": true,
  "attempts": 0,
  "last_attempt_at": null,
  "next_eligible_at": "2026-10-27T14:00:00.000Z",
  "callback_at": null,
  "last_disposition": null,
  "created_at": "2026-10-27T14:00:00.000Z"
}

Responses

`200`	The lead.
`401`	Missing, malformed, unknown or revoked API key.
`403`	The key lacks the required scope, or the workspace is suspended.
`404`	No such object in this workspace.
`429`	Rate limit exceeded (120 requests per minute per key).

DELETE/api/v1/leads/{id}write scope

Remove a lead from its campaign

Sets the lead's status to `removed` so it is never dialed again. Call history is kept. Safe to repeat.

Parameters

Name	In	Description
`id` required	path	Lead id (UUID).

Example request

Shell

curl -X DELETE "https://nitrodialer.com/api/v1/leads/ID" \
  -H "Authorization: Bearer $NITRODIALER_API_KEY"

Response · 200

JSON

{
  "id": "2b7e4f55-0d3c-4a11-8a2f-9c6d5e4b3a21",
  "object": "lead",
  "deleted": true
}

Responses

`200`	Removed.
`401`	Missing, malformed, unknown or revoked API key.
`403`	The key lacks the required scope, or the workspace is suspended.
`404`	No such object in this workspace.
`409`	The lead is on a call right now.
`429`	Rate limit exceeded (120 requests per minute per key).

Calls

GET/api/v1/callsread scope

List calls

Newest first, by the time the call was placed.

Parameters

Name	In	Description
`limit`	query	Items per page, 1–100. Default 25.
`starting_after`	query	Cursor: the `next_cursor` from the previous page.
`campaign_id`	query	Only calls from this campaign.
`agent_id`	query	Only calls made by this agent.
`disposition`	query	Disposition key, e.g. appointment.
`since`	query	Placed at or after (ISO 8601).
`until`	query	Placed before (ISO 8601).

Example request

Shell

curl "https://nitrodialer.com/api/v1/calls" \
  -H "Authorization: Bearer $NITRODIALER_API_KEY"

Response · 200

JSON

{
  "object": "list",
  "data": [
    {
      "id": "c41d9a6e-7b2f-4e8a-9f10-3d2c1b0a9f88",
      "object": "call",
      "campaign": {
        "id": "8f0b5c2e-6c1a-4f43-9d7e-2b8c1f0a9e11",
        "name": "Heat pump rebate — web leads"
      },
      "lead": {
        "id": "2b7e4f55-0d3c-4a11-8a2f-9c6d5e4b3a21",
        "first_name": "Daniel",
        "last_name": "Okafor",
        "company": null,
        "crm_object": "contacts",
        "crm_record_id": "51234"
      },
      "agent": {
        "id": "0e6f7a8b-1c2d-4e3f-8a9b-0c1d2e3f4a5b",
        "name": "Priya Raman"
      },
      "phone": "+15125550142",
      "started_at": "2026-10-27T14:03:12.000Z",
      "connected_at": "2026-10-27T14:03:30.000Z",
      "ended_at": "2026-10-27T14:14:12.000Z",
      "talk_seconds": 642,
      "disposition": {
        "key": "appointment",
        "label": "Appointment set",
        "category": "contact_positive"
      },
      "notes": "Gas furnace, 19 years old. Booked Thursday 10am.",
      "ai_summary": "Homeowner wants to replace an aging furnace; in-home assessment booked.",
      "recording_url": "https://dialpad.com/r/abc123"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Responses

`200`	A page of calls.
`401`	Missing, malformed, unknown or revoked API key.
`403`	The key lacks the required scope, or the workspace is suspended.
`422`	The request failed validation.
`429`	Rate limit exceeded (120 requests per minute per key).

GET/api/v1/calls/{id}read scope

Get a call

Parameters

Name	In	Description
`id` required	path	Call id (UUID).

Example request

Shell

curl "https://nitrodialer.com/api/v1/calls/ID" \
  -H "Authorization: Bearer $NITRODIALER_API_KEY"

Response · 200

JSON

{
  "id": "c41d9a6e-7b2f-4e8a-9f10-3d2c1b0a9f88",
  "object": "call",
  "campaign": {
    "id": "8f0b5c2e-6c1a-4f43-9d7e-2b8c1f0a9e11",
    "name": "Heat pump rebate — web leads"
  },
  "lead": {
    "id": "2b7e4f55-0d3c-4a11-8a2f-9c6d5e4b3a21",
    "first_name": "Daniel",
    "last_name": "Okafor",
    "company": null,
    "crm_object": "contacts",
    "crm_record_id": "51234"
  },
  "agent": {
    "id": "0e6f7a8b-1c2d-4e3f-8a9b-0c1d2e3f4a5b",
    "name": "Priya Raman"
  },
  "phone": "+15125550142",
  "started_at": "2026-10-27T14:03:12.000Z",
  "connected_at": "2026-10-27T14:03:30.000Z",
  "ended_at": "2026-10-27T14:14:12.000Z",
  "talk_seconds": 642,
  "disposition": {
    "key": "appointment",
    "label": "Appointment set",
    "category": "contact_positive"
  },
  "notes": "Gas furnace, 19 years old. Booked Thursday 10am.",
  "ai_summary": "Homeowner wants to replace an aging furnace; in-home assessment booked.",
  "recording_url": "https://dialpad.com/r/abc123"
}

Responses

`200`	The call.
`401`	Missing, malformed, unknown or revoked API key.
`403`	The key lacks the required scope, or the workspace is suspended.
`404`	No such object in this workspace.
`429`	Rate limit exceeded (120 requests per minute per key).

Stats

GET/api/v1/stats/agentsread scope

Per-agent coaching stats

The same numbers as the Coaching screen. Default window is the last 7 days; maximum 366 days.

Parameters

Name	In	Description
`from`	query	Window start (ISO 8601). Default: 7 days before `to`.
`to`	query	Window end (ISO 8601). Default: now.
`campaign_id`	query	Limit to one campaign.

Example request

Shell

curl "https://nitrodialer.com/api/v1/stats/agents" \
  -H "Authorization: Bearer $NITRODIALER_API_KEY"

Response · 200

JSON

{
  "object": "list",
  "from": "2026-10-20T00:00:00.000Z",
  "to": "2026-10-27T00:00:00.000Z",
  "campaign_id": null,
  "data": [
    {
      "object": "agent_stats",
      "agent": {
        "id": "0e6f…",
        "name": "Priya Raman"
      },
      "dials": 412,
      "connects": 318,
      "contacts": 118,
      "conversations": 61,
      "appointments": 19,
      "talk_seconds": 64200,
      "rates": {
        "pickup": 0.2864,
        "appointment": 0.161,
        "dials_per_hour": 13.2
      }
    }
  ]
}

Responses

`200`	One row per agent with activity in the window.
`401`	Missing, malformed, unknown or revoked API key.
`403`	The key lacks the required scope, or the workspace is suspended.
`422`	The request failed validation.
`429`	Rate limit exceeded (120 requests per minute per key).

Do not call

GET/api/v1/dncread scope

List or look up do-not-call numbers

Without `phone`: your internal DNC list, newest first (paginate with `requested_before`), plus a count of national-list numbers. With `phone`: whether that number is blocked and why. National-list numbers are never listed — registry terms only allow compliance use.

Parameters

Name	In	Description
`phone`	query	Look up one number.
`limit`	query	1–100, default 50.
`requested_before`	query	Cursor: `next_requested_before` from the previous page.

Example request

Shell

curl "https://nitrodialer.com/api/v1/dnc" \
  -H "Authorization: Bearer $NITRODIALER_API_KEY"

Response · 200

JSON

{
  "object": "dnc_lookup",
  "phone": "+12125550142",
  "blocked": true,
  "internal": {
    "requested_at": "2026-10-27T14:20:00.000Z",
    "expires_at": "2031-10-27T14:20:00.000Z"
  },
  "national_dncl": false
}

Responses

`200`	A page of internal DNC numbers, or a lookup result.
`401`	Missing, malformed, unknown or revoked API key.
`403`	The key lacks the required scope, or the workspace is suspended.
`422`	The request failed validation.
`429`	Rate limit exceeded (120 requests per minute per key).

POST/api/v1/dncwrite scope

Add a number to the internal DNC list

Blocked immediately and kept for the workspace's retention period (US preset 5 years, Canada 3 years + 14 days). Queued leads with that number stop immediately and fire `lead.dnc`.

Request body

JSON

{
  "phone": "+1 647 555 0142",
  "reason": "Asked by email"
}

Example request

Shell

curl -X POST "https://nitrodialer.com/api/v1/dnc" \
  -H "Authorization: Bearer $NITRODIALER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+1 647 555 0142","reason":"Asked by email"}'

Response · 201

JSON

{
  "object": "dnc_number",
  "phone": "+15125550142",
  "requested_at": "2026-10-27T14:20:00.000Z",
  "expires_at": "2031-10-27T14:20:00.000Z",
  "leads_stopped": 1
}

Responses

`201`	Added.
`401`	Missing, malformed, unknown or revoked API key.
`403`	The key lacks the required scope, or the workspace is suspended.
`422`	The request failed validation.
`429`	Rate limit exceeded (120 requests per minute per key).

DELETE/api/v1/dncwrite scope

Remove a number from the internal DNC list

Only do this when the person has since given express consent to be called.

Parameters

Name	In	Description
`phone` required	query	The number to remove.

Example request

Shell

curl -X DELETE "https://nitrodialer.com/api/v1/dnc?phone=%2B15125550142" \
  -H "Authorization: Bearer $NITRODIALER_API_KEY"

Response · 200

JSON

{
  "object": "dnc_number",
  "phone": "+15125550142",
  "deleted": true
}

Responses

`200`	Removed.
`401`	Missing, malformed, unknown or revoked API key.
`403`	The key lacks the required scope, or the workspace is suspended.
`422`	The request failed validation.
`429`	Rate limit exceeded (120 requests per minute per key).

Dispositions

GET/api/v1/dispositionsread scope

List call outcomes

The outcomes agents pick after each call, with the CRM field updates each one applies.

Example request

Shell

curl "https://nitrodialer.com/api/v1/dispositions" \
  -H "Authorization: Bearer $NITRODIALER_API_KEY"

Response · 200

JSON

{
  "object": "list",
  "data": [
    {
      "object": "disposition",
      "key": "appointment",
      "label": "Appointment set",
      "category": "contact_positive",
      "is_appointment": true,
      "ends_lead": true,
      "add_to_dnc": false,
      "mark_number_bad": false,
      "requires_callback": false,
      "retry_after_minutes": null,
      "crm_field_updates": {
        "hs_lead_status": "OPEN_DEAL"
      },
      "active": true
    }
  ],
  "has_more": false
}

Responses

`200`	All dispositions.
`401`	Missing, malformed, unknown or revoked API key.
`403`	The key lacks the required scope, or the workspace is suspended.
`429`	Rate limit exceeded (120 requests per minute per key).

Objects

Campaign

Field	Type	Notes
`object`	"campaign"
`id`	string
`name`	string
`status`	string (draft, active, paused, archived)
`mode`	string (power, preview)
`call_type`	string (b2c, b2b)
`assignment`	string (shared, owner_only)
`source`	object
`caller_id`	string \| null
`last_synced_at`	string \| null
`created_at`	string
`queue`	Queue

Lead

Field	Type	Notes
`object`	"lead"
`id`	string
`campaign_id`	string
`status`	string (ready, claimed, in_call, callback, done, exhausted, dnc, removed)
`priority`	integer
`first_name`	string \| null
`last_name`	string \| null
`company`	string \| null
`email`	string \| null
`phones`	array of Phone
`city`	string \| null
`region`	string \| null
`postal_code`	string \| null
`timezone`	string	IANA zone used for legal calling hours.
`crm_object`	string \| null
`crm_record_id`	string \| null
`express_consent`	boolean
`attempts`	integer
`last_attempt_at`	string \| null
`next_eligible_at`	string
`callback_at`	string \| null
`last_disposition`	string \| null
`created_at`	string

LeadInput

At least one of phone, mobile or other_phone is required. Numbers are normalised to E.164 (North America by default). Rows without a valid number are skipped and counted.

Field	Type	Notes
`first_name`	string
`last_name`	string
`company`	string
`email`	string
`phone`	string
`mobile`	string
`other_phone`	string
`city`	string
`region`	string	State or province; sets the lead's time zone.
`postal_code`	string
`crm_object`	string	e.g. contacts (HubSpot), Lead (Salesforce), Leads (Zoho), persons (Pipedrive).
`crm_record_id`	string	Links the lead to its CRM record so call notes are written back. Also the de-duplication key: re-sending the same record updates it instead of adding a duplicate.
`express_consent`	boolean	The person gave express consent to be called (skips the national do-not-call list).
`consent_source`	string
`priority`	integer	Higher dials first. Use 100 for brand-new inbound leads (speed-to-lead).

Call

Field	Type	Notes
`object`	"call"
`id`	string
`campaign`	object
`lead`	object
`agent`	object
`phone`	string
`started_at`	string \| null
`connected_at`	string \| null
`ended_at`	string \| null
`talk_seconds`	integer
`disposition`	object \| null
`notes`	string \| null
`ai_summary`	string \| null
`recording_url`	string \| null

AgentStats

Definitions: see /docs/coaching-metrics.

Field	Type	Notes
`object`	"agent_stats"
`agent`	object
`dials`	integer
`connects`	integer
`contacts`	integer
`conversations`	integer
`appointments`	integer
`dnc_requests`	integer
`bad_numbers`	integer
`missing_dispositions`	integer
`talk_seconds`	integer
`avg_talk_seconds`	number \| null
`longest_talk_seconds`	integer \| null
`avg_ring_seconds`	number \| null
`avg_wrapup_seconds`	number \| null
`time`	object
`rates`	object

Disposition

Field	Type	Notes
`object`	"disposition"
`key`	string
`label`	string
`category`	string
`is_appointment`	boolean
`ends_lead`	boolean
`add_to_dnc`	boolean
`mark_number_bad`	boolean
`requires_callback`	boolean
`retry_after_minutes`	integer \| null
`crm_field_updates`	object
`active`	boolean

Error

Field	Type	Notes
`code`	string
`message`	string