Developer docs

Automation API

Let your CRM, website forms or an automation tool (Zapier, Make, n8n, Zoho Flow…) drive CallBix: put a fresh lead on an agent's phone with a one-tap Call button, feed leads into call lists, or notify the team. For data going the other way — calls into your systems — see Webhooks.

Overview

Base URL: https://api.callbix.app/api/v1/hooks. Requests and responses are JSON. Everything an endpoint sends to a phone also appears under Notifications in the dashboard, with delivery and open counts.

Using an AI assistant to write your integration? Give it llms-full.txt: this page and the webhook docs in one plain-text file.

Authentication

Create a key in Automations & API (workspace admins). Send it on every request in either header:

Authorization: Bearer cb_live_…
# or
X-Api-Key: cb_live_…

Keys belong to one workspace and act for it. Keep them server-side; revoke one in the dashboard if it leaks. A workspace can have up to 20 keys, and each key can make up to 600 requests a minute.

When you create a key, choose what it may do. Give each tool only what it needs:

ScopeAllows
calls.requestCall requests (single, bulk, check, cancel) and notifications.
leads.writeAdd leads to call lists and create lists.
directory.readSee people, teams and call lists.
calls.readA number's past calls, and the latest call for many numbers.
calls.exportThe whole call log, a page at a time.
visits.writePlan, move and cancel field visits.
visits.readSee field visits (by record id, number, status or period).
events.subscribeSubscribe a URL to events — what Zapier, Make and n8n instant triggers use.

Ask an agent to call

POST/call-request

The fastest way to work a new lead. The chosen agent gets a notification with Call now and WhatsApp buttons; tapping Call dials immediately. The request stays open until that agent calls the number from their phone, and the time it took is recorded (Speed to lead in the dashboard). If nobody calls in time, an automation nudges the agent and tells their managers.

FieldType
phonestring, requiredAny format. Include the country code; numbers without one are read as the server's default country (India unless set otherwise).
namestringShown on the notification: “Call Priya Sharma now”.
companystring
notesstringContext for the agent, e.g. what they asked for.
assignTostringAn agent's email or id; team:<id> for a team in turn; owner:<crm email> for the CRM record's owner; or leave it out for the workspace's routing (Integrations → Zoho CRM extension → Who gets calls) — everyone in turn by default.
listIdstringAlso add the person to this call list, so their attempts are tracked there.
externalIdstringYour reference (e.g. CRM record id); returned when you check the request.
titlestringOverride the notification title.
Request
curl -X POST https://api.callbix.app/api/v1/hooks/call-request \
  -H "Authorization: Bearer cb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+91 98765 43210",
    "name": "Priya Sharma",
    "company": "Sharma Interiors",
    "notes": "Filled the 3BHK enquiry form",
    "externalId": "zoho-lead-48213"
  }'
201 Created
{
  "id": "6702f0c1a9e1b2c3d4e5f601",
  "status": "OPEN",
  "assignedTo": { "id": "66f9a2b1c3d4e5f601234567", "name": "Ravi Kumar", "email": "ravi@acme.in" },
  "notification": { "id": "…", "stats": { "devices": 1, "delivered": 1, "failed": 0 }, "note": null }
}

Check a call request

GET/call-request/:id

200 OK
{
  "id": "6702f0c1a9e1b2c3d4e5f601",
  "status": "CALLED",
  "phone": "+91 98765 43210",
  "externalId": "zoho-lead-48213",
  "createdAt": "2026-10-02T06:09:12.000Z",
  "calledAt": "2026-10-02T06:11:40.000Z",
  "responseSec": 148,
  "callId": "6702f1d0a9e1b2c3d4e5f777"
}

status is OPEN until the agent calls the number, then CALLED (or CANCELED if you withdraw it). The call itself (outcome, notes, recording) reaches your CRM through the normal sync or your webhook.

For CRM extensions

What the Zoho CRM extension uses — available to any CRM or tool.

POST/call-requests

Up to 200 “call now” requests at once. Each item is answered on its own, so one bad number doesn't stop the rest.

Request
{
  "items": [
    { "phone": "+91 98200 11111", "name": "Priya Raman", "externalId": "Leads:1001", "ownerEmail": "ravi@acme.com" },
    { "phone": "+91 98200 22222", "name": "Vikram Shah", "externalId": "Leads:1002" }
  ],
  "assign": { "mode": "owner" },   // "default" | "person" (+ "to") | "team" (+ "teamId") | "owner"
  "source": "zoho"
}
201 Created
{
  "created": 2,
  "failed": 0,
  "results": [
    { "externalId": "Leads:1001", "ok": true, "id": "…", "assignedTo": { "id": "…", "name": "Ravi Kumar", "email": "ravi@acme.com" } },
    { "externalId": "Leads:1002", "ok": true, "id": "…", "assignedTo": { "id": "…", "name": "Asha Mehta", "email": "asha@acme.com" } }
  ]
}
EndpointWhat it returns
GET /peopleActive people, their teams, and whether a phone is signed in (hasApp).
GET /teamsTeams with member counts — use the id as team:<id>.
GET /listsActive call lists to add leads to.
POST /listsA new call list with leads, worked by userIds / emails or a teamId.
GET /calls?phone=A number's calls with the team: outcome, notes, agent, recording link (7 days), totals and open follow-up.
GET /call-requests?externalId=Requests for one CRM record (or ?phone=), newest first.
POST /call-request/:id/cancelWithdraws a request nobody has called yet.

Call history & call log

POST/calls/summary

The latest call with each of up to 500 numbers, in the order you sent them — what the Google Sheets add-on writes next to each row.

Request
{ "phones": ["+91 98765 43210", "98200 11111"] }
200 OK
{
  "results": [
    {
      "phone": "+91 98765 43210",
      "normalized": "+919876543210",
      "valid": true,
      "calls": 3,
      "connected": 2,
      "talkSec": 512,
      "openRequests": 0,
      "last": { "startedAt": "2026-10-02T06:09:12.000Z", "direction": "OUTGOING", "durationSec": 252, "outcome": "Interested", "notes": "…", "agent": "Ravi Kumar", "followUpAt": null }
    }
  ]
}

GET/call-log?from=2026-10-01&cursor=&limit=500

Every call in a period, oldest first. Pass the returned next as cursor until it's null. Needs a plan with exports; the earliest from is your plan's call history.

200 OK
{
  "items": [
    {
      "id": "6702f1d0a9e1b2c3d4e5f777",
      "startedAt": "2026-10-02T06:09:12.000Z",
      "direction": "OUTGOING",
      "channel": "SIM",
      "phone": "+91 98765 43210",
      "contact": "Priya Sharma",
      "company": "Sharma Interiors",
      "durationSec": 252,
      "outcome": "Interested",
      "notes": "Wants a site visit on Saturday.",
      "followUpAt": null,
      "agent": { "name": "Ravi Kumar", "email": "ravi@acme.in" },
      "recorded": true
    }
  ],
  "next": "1727849352000_6702f1d0a9e1b2c3d4e5f777"
}

Notes and outcomes can change after a call, so a sync should re-read the last day or two and update rows by id. For changes as they happen, use webhooks.

Add leads to a call list

POST/leads

Appends leads to a list (find its id in the list's web address). They're shared between the list's agents just like an Excel import, and each agent is told how many new leads they got. Needs a plan with call lists.

Request
{
  "listId": "6702e0b0a9e1b2c3d4e5f500",
  "skipDuplicates": true,
  "leads": [
    { "phone": "9876500001", "name": "Neha Gupta", "company": "Gupta Traders", "extra": { "Budget": "75L", "Source": "Facebook" } },
    { "phone": "+91 98765 00002", "name": "Om Prakash" }
  ]
}
201 Created
{ "imported": 2, "duplicates": 0, "invalid": 0 }

Up to 5,000 leads per request. extra holds any other columns; agents see them on the dialer screen.

Plan field visits

POST/visits

Plans a visit for a person at a time: it lands on their phone with directions, and they're reminded before it (30 minutes by default; the workspace can change it). Checking in there starts the visit; one nobody starts within a day of its time is marked missed. Needs field visits turned on and a plan that includes them.

Request
{
  "phone": "+91 98111 22222",
  "name": "Priya Raman",
  "company": "Raman Interiors",
  "address": "ITPL Main Rd, Whitefield, Bengaluru",
  "scheduledAt": "2026-10-17T11:30:00+05:30",
  "durationMin": 45,
  "purpose": "Site visit",
  "instructions": "Carry the brochure",
  "assignTo": "owner:ravi@acme.com",   // email · user id · "team:<id>" · "owner:<crm email>" · empty = your routing
  "externalId": "Leads:4876000000123",
  "source": "zoho"
}
201 Created
{
  "id": "6660bb229b1e8a0012340002",
  "status": "PLANNED",
  "user": { "id": "…", "name": "Ravi Kumar" },
  "contactName": "Priya Raman",
  "scheduledAt": "2026-10-17T06:00:00.000Z",
  "address": "ITPL Main Rd, Whitefield, Bengaluru",
  "source": "crm:zoho",
  "externalId": "Leads:4876000000123",
  "checkIn": null, "checkOut": null, "outcome": null, "flags": []
}
EndpointWhat it does
POST /visits/bulkUp to 200 at once, each answered on its own; assign works like bulk call requests (default · person · team · owner).
GET /visitsBy externalId, phone, status (PLANNED · OPEN · DONE · CANCELED · MISSED) or a period (from / to).
GET /visits/:idOne visit: plan, check-in and check-out places, outcome, notes, time spent, flags.
PATCH /visits/:idMove it (scheduledAt), change the address or details, or hand it over (assignTo). Planned visits only.
POST /visits/:id/cancelCancels a planned visit, with an optional reason; the person is told.

Website forms can ask for a visit too: send a visit_at field (or visit_date and visit_time) with the lead, and the visit is planned for the agent who gets it.

Subscribe to events

Instead of polling, have CallBix push events to you the moment they happen — what Zapier, Make and n8n "instant" triggers do. Every delivery is signed and retried like a webhook; answer 410 Gone and the subscription removes itself. Needs a plan with Workflows.

POST/subscriptions

Request
{ "hookUrl": "https://hooks.zapier.com/hooks/standard/…", "event": "visit.checked_out", "source": "zapier" }
// or several: { "url": "https://…", "events": ["call.missed", "lead.received"], "source": "make" }
201 Created
{ "id": "6661aa…", "url": "https://hooks.zapier.com/…", "events": ["visit.checked_out"], "secret": "whsec_…" }
EndpointWhat it does
GET /eventsEvery event you can subscribe to, with a label and description.
GET /events/:event/sampleA realistic sample delivery of that event (for mapping fields).
GET /subscriptionsSubscriptions made through the API.
DELETE /subscriptions/:idStops one.

Send a notification

POST/notify

Request
{
  "to": { "emails": ["ravi@acme.in"] },
  "title": "Site visit confirmed for 4 pm",
  "body": "Priya Sharma — 12 MG Road. Call her if you're running late.",
  "action": { "kind": "CALL", "phone": "+91 98765 43210", "name": "Priya Sharma" }
}
to
{ "all": true }Everyone active in the workspace.
{ "emails": [...] }People by sign-in email.
{ "userIds": [...] }People by CallBix id.
{ "teamIds": [...] }Everyone in these teams.

Notification actions

kindExtra fieldsOn the phone
OPEN_APP—Opens CallBix (default).
CALLphone required, name, company, notesCall now and WhatsApp buttons; Call dials straight away.
OPEN_LISTlistId requiredOpens that call list's dialer.
URLurl required, https onlyOpens the link.
OPEN_VISITvisitIdOpens the planned visit, with a Call button when there's a phone.

Test your key

GET/ping

200 OK
{ "ok": true, "workspace": { "id": "…", "name": "Acme Homes" }, "push": true }

push: false means this CallBix server can't deliver notifications yet; requests still work and are logged.

Errors

StatusMeaning
400Something in the body is missing or invalid; message says what.
401Missing, unknown or revoked API key.
402The workspace's plan doesn't include this, or its trial/subscription ended.
403The workspace is suspended, or the key doesn't have the scope this needs.
404The list or call request doesn't exist in this workspace.
429More than 600 requests a minute with this key. Wait a little and retry.
Error body
{ "error": "bad_request", "message": "No active person with the email ravi@acme.in" }

Recipes

  • New website or Facebook lead → call within a minute. In Zapier/Make/n8n, on “new lead”, send a Webhooks POST to /call-request with the lead's phone and name. Turn on Call request not acted on in Automations so managers hear about slow responses.
  • CRM lead status changes to “Hot” → call it. Zoho Workflow, HubSpot workflow or Salesforce Flow calling /call-request with assignTo set to the lead owner's email.
  • Nightly batch for tomorrow's calling. Push the day's leads to /leads; agents see them in the app's Lists tab in the morning.
  • A booking becomes a visit. Calendly, your booking page or a CRM workflow calls /visits with the time and address; the agent gets directions and a reminder, and you get visit.checked_out back with how it went.
  • Close the loop. Point a webhook back at your system to receive each call's outcome, notes and recording.