👋 Welcome to the BigPhone API

Get organization

Get the organization that owns your API key.

GET/organization

Example payload

{"id": "7b8f32cd-1ae6-4d59-a374-d3892a4a912e", // Unique organization ID (UUID)."name": "Acme", // Organization name."created_at": "2026-09-07T14:00:00Z" // Creation time in ISO 8601 format.}

Example response200 OK

JSON

{
  "data": {
    "id": "7b8f32cd-1ae6-4d59-a374-d3892a4a912e",
    "name": "Acme",
    "created_at": "2026-09-07T14:00:00Z"
  }
}

const apiKey = process.env.BIGPHONE_API_KEY;
if (!apiKey) throw new Error("Set BIGPHONE_API_KEY");

const response = await fetch(
  "https://bigphone-front.vercel.app/api/v1/organization",
  {
    headers: {
      Authorization: `Bearer ${apiKey}`,
    },
  },
);

const result = await response.json();
if (!response.ok) {
  throw new Error(`${response.status}: ${result.error.message}`);
}
console.log(result.data);

export {};

List campaigns

Get campaigns in your organization.

GET/campaigns

Set limit to 1–100 records (default: 20). Pass pagination.next_cursor as after to get the next page, until the cursor is null.

Example payload

{"id": "9bc96054-7b88-4bde-8c8a-1e3051f6778c", // Unique campaign ID (UUID)."name": "September follow-up", // Campaign name."status": "draft", // draft, scheduled, running, paused, completed, or cancelled."total_leads": 1, // Number of leads in this campaign."created_at": "2026-09-07T14:00:00Z", // Creation time in ISO 8601 format."updated_at": "2026-09-07T14:00:00Z" // Last update in ISO 8601 format, or null if unavailable.}

Example response200 OK

JSON

{
  "data": [
    {
      "id": "9bc96054-7b88-4bde-8c8a-1e3051f6778c",
      "name": "September follow-up",
      "status": "draft",
      "total_leads": 1,
      "created_at": "2026-09-07T14:00:00Z",
      "updated_at": "2026-09-07T14:00:00Z"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null
  }
}

const apiKey = process.env.BIGPHONE_API_KEY;
if (!apiKey) throw new Error("Set BIGPHONE_API_KEY");

const response = await fetch(
  "https://bigphone-front.vercel.app/api/v1/campaigns?limit=20",
  {
    headers: {
      Authorization: `Bearer ${apiKey}`,
    },
  },
);

const result = await response.json();
if (!response.ok) {
  throw new Error(`${response.status}: ${result.error.message}`);
}
console.log(result.data);

export {};

Get campaign

Get one campaign by its UUID.

GET/campaigns/{id}

Replace {id} with a campaign UUID from List campaigns. Returns the same campaign fields as the list endpoint. Create and configure campaigns in the dashboard.

Example payload

{"id": "9bc96054-7b88-4bde-8c8a-1e3051f6778c", // Unique campaign ID (UUID)."name": "September follow-up", // Campaign name."status": "draft", // draft, scheduled, running, paused, completed, or cancelled."total_leads": 1, // Number of leads in this campaign."created_at": "2026-09-07T14:00:00Z", // Creation time in ISO 8601 format."updated_at": "2026-09-07T14:00:00Z" // Last update in ISO 8601 format, or null if unavailable.}

Example response200 OK

JSON

{
  "data": {
    "id": "9bc96054-7b88-4bde-8c8a-1e3051f6778c",
    "name": "September follow-up",
    "status": "draft",
    "total_leads": 1,
    "created_at": "2026-09-07T14:00:00Z",
    "updated_at": "2026-09-07T14:00:00Z"
  }
}

const apiKey = process.env.BIGPHONE_API_KEY;
if (!apiKey) throw new Error("Set BIGPHONE_API_KEY");

const response = await fetch(
  "https://bigphone-front.vercel.app/api/v1/campaigns/9bc96054-7b88-4bde-8c8a-1e3051f6778c",
  {
    headers: {
      Authorization: `Bearer ${apiKey}`,
    },
  },
);

const result = await response.json();
if (!response.ok) {
  throw new Error(`${response.status}: ${result.error.message}`);
}
console.log(result.data);

export {};

List leads

Get the leads in a campaign that belongs to your organization.

GET/campaigns/{id}/leads

Set limit to 1–100 records (default: 20). Pass pagination.next_cursor as after to get the next page, until the cursor is null.

Example payload

{"id": "806e184b-94aa-46e9-83ec-c7d81735588b", // Unique lead ID (UUID)."campaign_id": "9bc96054-7b88-4bde-8c8a-1e3051f6778c", // Campaign ID (UUID)."phone": "+14165550123", // Lead phone number in E.164 format."first_name": "Alex", // First name, or null if not provided."last_name": "Morgan", // Last name, or null if not provided."email": "alex@example.com", // Email address, or null if not provided."company": "Acme", // Company name, or null if not provided."external_id": "crm_123", // Your CRM or external reference, or null if not provided."notes": "Asked for a follow-up about pricing.", // Lead notes, or null if not provided."other": "Prefers afternoon calls.", // Other lead information, or null if not provided."language": "fr_ca", // Saved lead language, including locale codes such as fr_fr and fr_ca. Defaults to en when not provided."full_name": "Alex Morgan", // Derived from first and last name, or null if unavailable."verification_status": "active", // unverified, verifying, active, or inactive. API verification sets active for active/reachable lines and inactive for excluded results."verification_line_status": "reachable", // Twilio result: active, reachable, unreachable, inactive, or unknown. Null when not verified."verified_at": "2026-09-07T14:00:00Z", // Verification timestamp, or null when not verified."excluded": false, // True when phone verification or campaign suppression excludes this lead from calls."created_at": "2026-09-07T14:00:00Z", // Creation time in ISO 8601 format."updated_at": "2026-09-07T14:00:00Z" // Last update in ISO 8601 format.}

Example response200 OK

JSON

{
  "data": [
    {
      "id": "806e184b-94aa-46e9-83ec-c7d81735588b",
      "campaign_id": "9bc96054-7b88-4bde-8c8a-1e3051f6778c",
      "phone": "+14165550123",
      "first_name": "Alex",
      "last_name": "Morgan",
      "email": "alex@example.com",
      "company": "Acme",
      "external_id": "crm_123",
      "notes": "Asked for a follow-up about pricing.",
      "other": "Prefers afternoon calls.",
      "language": "fr_ca",
      "full_name": "Alex Morgan",
      "verification_status": "active",
      "verification_line_status": "reachable",
      "verified_at": "2026-09-07T14:00:00Z",
      "excluded": false,
      "created_at": "2026-09-07T14:00:00Z",
      "updated_at": "2026-09-07T14:00:00Z"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null
  }
}

const apiKey = process.env.BIGPHONE_API_KEY;
if (!apiKey) throw new Error("Set BIGPHONE_API_KEY");

const response = await fetch(
  "https://bigphone-front.vercel.app/api/v1/campaigns/9bc96054-7b88-4bde-8c8a-1e3051f6778c/leads?limit=20",
  {
    headers: {
      Authorization: `Bearer ${apiKey}`,
    },
  },
);

const result = await response.json();
if (!response.ok) {
  throw new Error(`${response.status}: ${result.error.message}`);
}
console.log(result.data);

export {};

Add lead to campaign

Add one lead to an existing campaign in your organization.

POST/campaigns/{id}/leads

Send Content-Type: application/json. Body limit: 16 KiB. Unknown fields return 400. Repeating a request for a phone already in the campaign leaves that lead unchanged. If it was excluded, the request restores it as an unverified lead. A successful request returns the lead object.

Warning: verification costs money on Twilio. Setting verify_lead: true runs a paid Line Status lookup using your organization’s connected Twilio account. Twilio may still charge for the lookup if the request times out or the lead cannot be added afterward.

Set verify_lead: true to verify the phone number before adding the lead. Only active and reachable results can be called. Invalid numbers and inactive, unreachable, or unknown results are added with excluded: true. Verification and exclusion are saved with the lead in one transaction.

Verification defaults to false. A missing Twilio connection returns 409. A failed, incomplete, or timed-out lookup returns 503 without adding a lead. A changed Twilio connection returns 409 without adding a lead. Lookup requests are not retried automatically.

verify_phone is still accepted as an alias for verify_lead. Both fields must be booleans. If both are provided, their values must match; conflicting values return 400 before any lookup or lead creation.

A running campaign may call the lead once creation succeeds. With verify_lead: true, verification finishes first and excluded leads cannot be called by the campaign. With verification disabled, the lead is added as unverified.

Example payload

{"phone": "+14165550123", // Required. E.164 number: + and 8–15 digits, starting with 1–9."first_name": "Alex", // Optional string or null. Up to 100 characters."last_name": "Morgan", // Optional string or null. Up to 100 characters."email": "alex@example.com", // Optional valid email or null. Up to 254 characters."company": "Acme", // Optional string or null. Up to 200 characters."external_id": "crm_123", // Optional CRM or external ID, or null. Up to 200 characters."notes": "Asked for a follow-up about pricing.", // Optional string or null. Up to 5,000 characters."other": "Prefers afternoon calls.", // Optional string or null. Up to 5,000 characters."language": "fr_ca", // Optional string or null, up to 50 characters. Saved as supplied after trimming, for example en, fr_fr, or fr_ca. Omitted, null, or blank defaults to en."verify_lead": true // Optional boolean, default false. Verify the phone number before adding the lead. WARNING: Twilio charges your connected account for this lookup. Invalid or non-reachable results are added as excluded.}

Example response201 Created

JSON

{
  "data": {
    "id": "806e184b-94aa-46e9-83ec-c7d81735588b",
    "campaign_id": "9bc96054-7b88-4bde-8c8a-1e3051f6778c",
    "phone": "+14165550123",
    "first_name": "Alex",
    "last_name": "Morgan",
    "email": "alex@example.com",
    "company": "Acme",
    "external_id": "crm_123",
    "notes": "Asked for a follow-up about pricing.",
    "other": "Prefers afternoon calls.",
    "language": "fr_ca",
    "full_name": "Alex Morgan",
    "verification_status": "active",
    "verification_line_status": "reachable",
    "verified_at": "2026-09-07T14:00:00Z",
    "excluded": false,
    "created_at": "2026-09-07T14:00:00Z",
    "updated_at": "2026-09-07T14:00:00Z"
  }
}

const apiKey = process.env.BIGPHONE_API_KEY;
if (!apiKey) throw new Error("Set BIGPHONE_API_KEY");

const response = await fetch(
  "https://bigphone-front.vercel.app/api/v1/campaigns/9bc96054-7b88-4bde-8c8a-1e3051f6778c/leads",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "phone": "+14165550123",
      "first_name": "Alex",
      "last_name": "Morgan",
      "email": "alex@example.com",
      "company": "Acme",
      "external_id": "crm_123",
      "notes": "Asked for a follow-up about pricing.",
      "other": "Prefers afternoon calls.",
      "language": "fr_ca",
      "verify_lead": true
    }),
  },
);

const result = await response.json();
if (!response.ok) {
  throw new Error(`${response.status}: ${result.error.message}`);
}
console.log(result.data);

export {};

Remove lead from campaign

Remove a lead from a campaign. The lead stays in your organization and its call history is preserved.

DELETE/campaigns/{id}/leads/{leadId}

Replace {id} with the campaign UUID and {leadId} with a lead UUID from List leads. Send your API key in the Authorization: Bearer header. No request body is needed.

Returns 404 if the lead is not in that campaign and organization, including when it was already removed. Invalid UUIDs return 400. A call already queued or in progress may still finish.

Example payload

{"id": "806e184b-94aa-46e9-83ec-c7d81735588b", // The lead that was removed from the campaign."campaign_id": null, // Null because the lead is no longer assigned to a campaign."removed": true // Confirms removal. The lead and its call history are preserved.}

Example response200 OK

JSON

{
  "data": {
    "id": "806e184b-94aa-46e9-83ec-c7d81735588b",
    "campaign_id": null,
    "removed": true
  }
}

const apiKey = process.env.BIGPHONE_API_KEY;
if (!apiKey) throw new Error("Set BIGPHONE_API_KEY");

const response = await fetch(
  "https://bigphone-front.vercel.app/api/v1/campaigns/9bc96054-7b88-4bde-8c8a-1e3051f6778c/leads/806e184b-94aa-46e9-83ec-c7d81735588b",
  {
    method: "DELETE",
    headers: {
      Authorization: `Bearer ${apiKey}`,
    },
  },
);

const result = await response.json();
if (!response.ok) {
  throw new Error(`${response.status}: ${result.error.message}`);
}
console.log(result.data);

export {};

List calls

Get campaign call history for your organization. Test calls are excluded.

GET/calls

Set limit to 1–100 records (default: 20). Pass pagination.next_cursor as after to get the next page, until the cursor is null.

Optionally add campaign_id to the URL query parameters to filter by a campaign UUID in your organization, as shown in the request below.

Every call includes a permanent recording_url. Open it or send a GET request to play or download the audio. Anyone with the link can access the recording without an API key or sign-in. The same call keeps the same link, with no expiry, even after the API key is revoked. It returns 404 while audio is not ready or if no recording is retained.

Example payload

{"id": "b6f3d38e-86a8-457b-a09c-248c8e32ff63", // Unique call ID (UUID)."campaign_id": "9bc96054-7b88-4bde-8c8a-1e3051f6778c", // Campaign ID (UUID)."lead_id": "806e184b-94aa-46e9-83ec-c7d81735588b", // Lead ID (UUID), or null if the lead was deleted."direction": "outbound", // inbound or outbound."from_number": "+14165550100", // Caller phone number."to_number": "+14165550123", // Recipient phone number."status": "ended", // registered, dialing, ongoing, ended, not_connected, or error."started_at": "2026-09-07T14:00:00Z", // Start time in ISO 8601 format, or null if unavailable."ended_at": "2026-09-07T14:01:15Z", // End time in ISO 8601 format, or null if unavailable."duration_ms": 75000, // Duration in milliseconds, or null if unavailable."created_at": "2026-09-07T14:00:00Z", // Creation time in ISO 8601 format."updated_at": "2026-09-07T14:01:15Z", // Last update in ISO 8601 format."recording_url": "https://bigphone-front.vercel.app/api/v1/recordings/8d3a612a6f3748ff9b0a12c74b81e073609ecaa31c354f148ba3e08191b2f445" // Permanent public audio URL. No API key or sign-in needed. Available once the recording is ready and while it is retained.}

Example response200 OK

JSON

{
  "data": [
    {
      "id": "b6f3d38e-86a8-457b-a09c-248c8e32ff63",
      "campaign_id": "9bc96054-7b88-4bde-8c8a-1e3051f6778c",
      "lead_id": "806e184b-94aa-46e9-83ec-c7d81735588b",
      "direction": "outbound",
      "from_number": "+14165550100",
      "to_number": "+14165550123",
      "status": "ended",
      "started_at": "2026-09-07T14:00:00Z",
      "ended_at": "2026-09-07T14:01:15Z",
      "duration_ms": 75000,
      "created_at": "2026-09-07T14:00:00Z",
      "updated_at": "2026-09-07T14:01:15Z",
      "recording_url": "https://bigphone-front.vercel.app/api/v1/recordings/8d3a612a6f3748ff9b0a12c74b81e073609ecaa31c354f148ba3e08191b2f445"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null
  }
}

const apiKey = process.env.BIGPHONE_API_KEY;
if (!apiKey) throw new Error("Set BIGPHONE_API_KEY");

const response = await fetch(
  "https://bigphone-front.vercel.app/api/v1/calls?limit=20&campaign_id=9bc96054-7b88-4bde-8c8a-1e3051f6778c",
  {
    headers: {
      Authorization: `Bearer ${apiKey}`,
    },
  },
);

const result = await response.json();
if (!response.ok) {
  throw new Error(`${response.status}: ${result.error.message}`);
}
console.log(result.data);

export {};

Get call

Get one call with its recording link, transcript, collected data, and disconnection reason.

GET/calls/{id}

Replace {id} with a call UUID from List calls. The transcript starts with four lines: call time in Eastern Time (ET), adjusted for daylight saving time, duration, From:, and To:. The caller and recipient lines include the phone number, the configured agent name or available lead identity, and (Agent) or (Lead). For inbound calls, the lead is the caller. Each message follows on its own line, prefixed with Agent: or Lead:. Missing details are shown as Unavailable; unknown duration is 0 seconds. If there are no messages, the string contains only the four header lines.

Example payload

{"id": "b6f3d38e-86a8-457b-a09c-248c8e32ff63", // Unique call ID (UUID)."campaign_id": "9bc96054-7b88-4bde-8c8a-1e3051f6778c", // Campaign ID (UUID)."lead_id": "806e184b-94aa-46e9-83ec-c7d81735588b", // Lead ID (UUID), or null if the lead was deleted."direction": "outbound", // inbound or outbound."from_number": "+14165550100", // Caller phone number."to_number": "+14165550123", // Recipient phone number."status": "ended", // registered, dialing, ongoing, ended, not_connected, or error."started_at": "2026-09-07T14:00:00Z", // Start time in ISO 8601 format, or null if unavailable."ended_at": "2026-09-07T14:01:15Z", // End time in ISO 8601 format, or null if unavailable."duration_ms": 75000, // Duration in milliseconds, or null if unavailable."created_at": "2026-09-07T14:00:00Z", // Creation time in ISO 8601 format."updated_at": "2026-09-07T14:01:15Z", // Last update in ISO 8601 format."recording_url": "https://bigphone-front.vercel.app/api/v1/recordings/8d3a612a6f3748ff9b0a12c74b81e073609ecaa31c354f148ba3e08191b2f445", // Permanent public audio URL. No API key or sign-in needed. Available once the recording is ready and while it is retained."transcript": "Call date and time: 2026-09-07T10:00:00-04:00 (ET)\nDuration: 75 seconds\nFrom: +14165550100 Sarah (Agent)\nTo: +14165550123 Alex Morgan (Lead)\nAgent: Hi Alex, is now a good time to talk?\nLead: Yes, go ahead.", // Multiline string. Four header lines: ET call time, duration, From, and To. Then one Agent: or Lead: message per line."data_collected": { // Fields depend on your agent configuration. Empty object when unavailable."interested": true, // Example custom field: whether the lead is interested."preferred_callback": "afternoon" // Example custom field: preferred callback time.},"disconnection_reason": "user_hangup" // Why the call ended, or null if unavailable.}

Example response200 OK

JSON

{
  "data": {
    "id": "b6f3d38e-86a8-457b-a09c-248c8e32ff63",
    "campaign_id": "9bc96054-7b88-4bde-8c8a-1e3051f6778c",
    "lead_id": "806e184b-94aa-46e9-83ec-c7d81735588b",
    "direction": "outbound",
    "from_number": "+14165550100",
    "to_number": "+14165550123",
    "status": "ended",
    "started_at": "2026-09-07T14:00:00Z",
    "ended_at": "2026-09-07T14:01:15Z",
    "duration_ms": 75000,
    "created_at": "2026-09-07T14:00:00Z",
    "updated_at": "2026-09-07T14:01:15Z",
    "recording_url": "https://bigphone-front.vercel.app/api/v1/recordings/8d3a612a6f3748ff9b0a12c74b81e073609ecaa31c354f148ba3e08191b2f445",
    "transcript": "Call date and time: 2026-09-07T10:00:00-04:00 (ET)\nDuration: 75 seconds\nFrom: +14165550100 Sarah (Agent)\nTo: +14165550123 Alex Morgan (Lead)\nAgent: Hi Alex, is now a good time to talk?\nLead: Yes, go ahead.",
    "data_collected": {
      "interested": true,
      "preferred_callback": "afternoon"
    },
    "disconnection_reason": "user_hangup"
  }
}

const apiKey = process.env.BIGPHONE_API_KEY;
if (!apiKey) throw new Error("Set BIGPHONE_API_KEY");

const response = await fetch(
  "https://bigphone-front.vercel.app/api/v1/calls/b6f3d38e-86a8-457b-a09c-248c8e32ff63",
  {
    headers: {
      Authorization: `Bearer ${apiKey}`,
    },
  },
);

const result = await response.json();
if (!response.ok) {
  throw new Error(`${response.status}: ${result.error.message}`);
}
console.log(result.data);

export {};