# CallBix developer reference > CallBix (callbix.app) is call tracking for sales teams that sell from Android phones. An Android app logs every call on the team's existing SIM numbers (and WhatsApp calls), uploads the recordings the phone's dialer saves, and syncs each call with its outcome, notes and custom fields to Zoho CRM, Salesforce, HubSpot, Pipedrive, Freshsales, LeadSquared, Microsoft Dynamics 365 or any system through signed webhooks. Developers can push leads to agents' phones with an API key, fill call lists, read call history, export the call log, and receive every call as signed JSON. Key facts: - Multi-tenant SaaS. Each customer has a workspace; API keys and webhooks belong to one workspace. - No new phone numbers and no VoIP: calls go out from the agent's own phone and SIM. There are no per-minute charges. - Android 8+ app, installed from https://www.callbix.app/download (not the Play Store), plus a web dashboard at https://www.callbix.app/app. - Priced per user, billed monthly or yearly, in INR (Razorpay) or USD (Stripe). Prices exclude GST (or local taxes for USD), which is extra, as applicable. A free trial with no card needed (its current length is on the pricing page). Plans: https://www.callbix.app/pricing - API base URL: https://api.callbix.app/api/v1/hooks - Operated by Thinkbix Technologies Private Limited, Pune, India. Contact: hello@callbix.app This file has the complete Automation API and webhook reference. Human-friendly versions: https://www.callbix.app/docs/api and https://www.callbix.app/docs/webhooks. ## Choosing an integration | You want to… | Use | | --- | --- | | Ring an agent's phone about a new lead, with a Call now button | POST /call-request | | Load many leads for the team to call through | POST /leads or POST /lists | | Send a push notification to people's phones | POST /notify | | Plan a field visit for someone, with a reminder on their phone | POST /visits (or /visits/bulk) | | Get calls, visits, leads or deals pushed to your app as they happen | Event webhooks (dashboard → Webhooks) or POST /subscriptions | | Show a number's call history inside your CRM or tool | GET /calls?phone= | | Write each number's latest call result next to a row | POST /calls/summary | | Keep a copy of the whole call log | GET /call-log (paged), or webhooks | | Get every call, outcome, custom fields and recording as it happens | Webhooks | | Send leads from your website or a lead portal | A lead source (website form / portal URL) | ## Authentication Create an API key in the dashboard: Automations & API → API keys (workspace admins). Keys look like `cb_live_…` and are shown once. Send the key on every request: ``` Authorization: Bearer cb_live_… # or X-Api-Key: cb_live_… ``` Keys act for one workspace. Keep them on a server. A workspace can have up to 20 active keys. Revoke a key in the dashboard if it leaks. Each key has scopes. A request outside the key's scopes gets 403 `scope_missing`. | Scope | Allows | | --- | --- | | calls.request | POST /call-request, GET /call-request/:id, POST /call-requests, GET /call-requests, POST /call-request/:id/cancel, POST /notify | | leads.write | POST /leads, POST /lists | | directory.read | GET /people, GET /teams, GET /lists | | calls.read | GET /calls, POST /calls/summary | | calls.export | GET /call-log | | visits.write | POST /visits, POST /visits/bulk, PATCH /visits/:id, POST /visits/:id/cancel | | visits.read | GET /visits, GET /visits/:id | | events.subscribe | GET /events, GET /events/:event/sample, GET/POST /subscriptions, DELETE /subscriptions/:id | Rate limit: 600 requests a minute per API key. Over the limit you get 429; wait and retry. Base URL: `https://api.callbix.app/api/v1/hooks`. Requests and responses are JSON (`Content-Type: application/json`). Times are ISO 8601 in UTC. Phone numbers can be in any format; include the country code (numbers without one are read as India, +91, unless the server is set otherwise). ## GET /ping Checks a key. ```json { "ok": true, "workspace": { "id": "…", "name": "Acme Homes" }, "push": true, "scopes": ["calls.request", "leads.write", "directory.read", "calls.read", "calls.export"] } ``` `push: false` means this server can't deliver phone notifications yet; requests still work and are logged. ## POST /call-request Ask an agent to call someone now. The agent's phone shows a notification with Call now and WhatsApp buttons; Call dials straight away. The request stays OPEN until that agent calls the number from their phone; the time it took is recorded as speed to lead. If nobody calls in time, an automation reminds the agent and tells their managers. | Field | Type | Notes | | --- | --- | --- | | phone | string, required | 6–64 characters, any format. | | name | string | Shown on the notification: "Call Priya Sharma now". | | company | string | | | notes | string | Up to 1,000 characters. Context for the agent. | | assignTo | string | An agent's email or id; `team:` for a team in turn; `owner:` for the CRM record's owner; leave out for the workspace's routing (everyone in turn by default). | | listId | string | Also add the person to this call list. | | externalId | string | Your reference, e.g. a CRM record id. Returned when you check the request. | | title | string | Override the notification title. | ```bash 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: ```json { "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 } } ``` ## GET /call-request/:id ```json { "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, CALLED or CANCELED. The call's outcome, notes and recording reach your CRM through the normal sync or your webhook. ## POST /call-requests (bulk) Up to 200 call requests at once. Each item succeeds or fails on its own. ```json { "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" }, "source": "zoho" } ``` `assign.mode`: `default` (workspace routing), `person` (with `to`: email or id), `team` (with `teamId`), or `owner` (each item's `ownerEmail`). 201 Created: ```json { "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" } } ] } ``` ## GET /call-requests?externalId= (or ?phone=) Requests for one CRM record or number, newest first. ## POST /call-request/:id/cancel Withdraws a request nobody has called yet. 204 No Content; 404 if there is no open request with that id. ## POST /leads Adds leads to an existing call list. They are shared between the list's agents like an Excel import, and each agent is told how many new leads they got. Needs a plan with call lists (otherwise 402). ```json { "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. ## POST /lists Creates a call list, optionally with leads. | Field | Type | Notes | | --- | --- | --- | | name | string, required | Up to 120 characters. | | script | string | What agents see while calling. | | userIds / emails | string[] | Who works the list. | | teamId | string | Or a whole team. | | leads | array | Same shape as POST /leads, up to 5,000. | ## GET /people, GET /teams, GET /lists - `/people`: active people with id, name, email, phone, teams, and `hasApp` (a phone is signed in). - `/teams`: teams with id, name and member count. Use the id as `team:`. - `/lists`: active call lists with id, name and number of agents. ## POST /notify Push a notification to people's phones. ```json { "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 }`, `{ "emails": [...] }`, `{ "userIds": [...] }` or `{ "teamIds": [...] }`. `title` up to 120 characters, `body` up to 1,000. `action.kind`: | kind | Extra fields | On the phone | | --- | --- | --- | | OPEN_APP | — | Opens CallBix (default). | | CALL | phone (required), name, company, notes | Call now and WhatsApp buttons. | | OPEN_LIST | listId (required) | Opens that call list's dialer. | | URL | url (required, https) | Opens the link. | 201 Created: `{ "id": "…", "recipients": 1, "stats": { … }, "note": null }` ## GET /calls?phone=&limit= A number's call history with the team (newest first, `limit` 1–50, default 20). ```json { "phone": "+919876543210", "summary": { "calls": 3, "connected": 2, "talkSec": 512, "lastCallAt": "2026-10-02T06:09:12.000Z", "openFollowUp": null }, "calls": [ { "id": "…", "direction": "OUTGOING", "channel": "SIM", "startedAt": "2026-10-02T06:09:12.000Z", "durationSec": 252, "outcome": "Interested", "notes": "Wants a site visit on Saturday.", "followUpAt": "2026-10-04T04:30:00.000Z", "agent": { "id": "…", "name": "Ravi Kumar" }, "recordingUrl": "https://…" } ] } ``` `recordingUrl` is a signed link that works for 7 days, and only on plans with call recording. `channel` is SIM or WHATSAPP. ## POST /calls/summary The latest call with each of up to 500 numbers, in the order you sent them. Request: `{ "phones": ["+91 98765 43210", "98200 11111"] }` ```json { "results": [ { "phone": "+91 98765 43210", "normalized": "+919876543210", "valid": true, "calls": 3, "connected": 2, "talkSec": 512, "openRequests": 0, "last": { "startedAt": "…", "direction": "OUTGOING", "durationSec": 252, "outcome": "Interested", "notes": "…", "agent": "Ravi Kumar", "followUpAt": null } } ] } ``` ## GET /call-log?from=&to=&cursor=&limit= Every call in a period, oldest first, a page at a time (`limit` 1–1000, default 500). Pass the returned `next` as `cursor` until it is null. Needs a plan with exports (otherwise 402); `from` is limited to the plan's call history. ```json { "items": [ { "id": "…", "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": "…", "followUpAt": null, "agent": { "name": "Ravi Kumar", "email": "ravi@acme.in" }, "recorded": true } ], "next": "1727849352000_6702f1d0a9e1b2c3d4e5f777" } ``` Calls change after they are made (notes, outcome), so a sync should re-read the last day or two and update rows by `id`. ## POST /visits Plans a field visit: it shows on the person's phone with directions, with a reminder before it (30 minutes by default). Checking in there starts it; one nobody starts within a day of its time becomes MISSED. Needs field visits turned on and a plan that includes them. ```json { "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", "externalId": "Leads:4876000000123", "source": "zoho" } ``` - `scheduledAt` (required): ISO 8601 with an offset; up to a year ahead. - A name or a phone is required. `assignTo`: an email, a user id, `team:`, `owner:`, or empty for the workspace's routing. - 201 returns the visit: `id`, `status` ("PLANNED"), `user`, `scheduledAt`, `address`, `source` ("crm:zoho"), `externalId`, `checkIn` (null), `checkOut`, `outcome`, `notes`, `durationSec`, `flags`. Also: - POST /visits/bulk: `{ "items": [ …up to 200 visits, each may have ownerEmail… ], "assign": { "mode": "default" | "person" (+ "to") | "team" (+ "teamId") | "owner" }, "source": "zoho" }` → `{ created, failed, results: [{ externalId, ok, id, assignedTo } | { externalId, ok: false, error }] }`. - GET /visits?externalId=&phone=&status=&from=&to=&limit=: visits, newest first. Status: PLANNED, OPEN (checked in), DONE, CANCELED, MISSED. - GET /visits/:id, PATCH /visits/:id (scheduledAt, address, name, phone, company, purpose, instructions, durationMin, assignTo; planned visits only), POST /visits/:id/cancel `{ "reason": "…" }`. - Website forms (lead sources) can ask for a visit: a `visit_at` field, or `visit_date` + `visit_time` (local time), plans one for the agent who gets the lead. ## POST /subscriptions Subscribes a URL to events, for Zapier / Make / n8n instant triggers (REST hooks). Needs a plan with Workflows. ```json { "hookUrl": "https://hooks.zapier.com/hooks/standard/…", "event": "visit.checked_out", "source": "zapier" } ``` Answers `{ "id": "…", "url": "…", "events": ["visit.checked_out"], "secret": "whsec_…" }`. Use `events: [...]` for several, or `"*"` for all. Deliveries use the event-webhook format below. Answer 410 Gone to unsubscribe, or DELETE /subscriptions/:id. GET /events lists the events; GET /events/:event/sample returns `[sample delivery]`. ## Errors | Status | error | Meaning | | --- | --- | --- | | 400 | bad_request | Something in the body is missing or invalid; `message` says what. | | 401 | unauthorized | Missing, unknown or revoked API key. | | 402 | upgrade_required / subscription_inactive | The plan doesn't include this, or the trial or subscription ended. | | 403 | scope_missing / org_suspended | The key lacks the scope, or the workspace is suspended. | | 404 | not_found | The list, call request or record doesn't exist in this workspace. | | 429 | | Over 600 requests a minute for this key. | ```json { "error": "bad_request", "message": "No active person with the email ravi@acme.in" } ``` ## Event webhooks Dashboard → Webhooks: add any number of https endpoints and choose events for each (or all). Each event is a signed POST: ```json { "event": "visit.checked_out", "id": "5f0c2d1e-7a3b-4c55-9d6a-0b7d3e2f9a41", "occurredAt": "2026-10-16T11:05:00.000Z", "workspace": { "id": "…", "name": "Acme Homes" }, "data": { "visit": { "id": "…", "status": "DONE", "contactName": "Priya Raman", "phone": "+919811122222", "scheduledAt": "…", "address": "…", "checkInAt": "…", "checkOutAt": "…", "outcome": "Interested", "notes": "…", "durationSec": 2100, "flags": "", "url": "https://www.callbix.app/app/visits?visit=…" }, "agent": { "id": "…", "name": "Ravi Kumar", "email": "ravi@acme.in", "phone": "+919800000001", "teams": "North" }, "contact": { "id": "…", "name": "Priya Raman", "phone": "+919811122222", "email": null, "company": "Raman Interiors", "tags": "hot", "crm": null } } } ``` Events: call.logged, call.answered, call.missed, call.not_picked, call.outcome_saved, call.notes_saved, call.recording_added, follow_up.scheduled, follow_up.due, follow_up.done, call_request.created, call_request.called, call_request.canceled, visit.scheduled, visit.rescheduled, visit.canceled, visit.reminder, visit.checked_in, visit.checked_out, visit.missed, lead.received, deal.stage_changed, deal.won, deal.lost, target.reached. Call events carry `call`; call requests `request`; visits `visit`; leads `lead`; deals `deal`; all carry `agent` and `contact`. Headers: X-CallBix-Event, X-CallBix-Event-Id (= `id`, the same on every retry: de-duplicate on it), X-CallBix-Delivery, X-CallBix-Timestamp (Unix seconds), X-CallBix-Signature (hex HMAC-SHA256 of the raw body with the endpoint's secret, shown once when created). Any 2xx within 15 s counts as delivered. Failures are retried after 1, 5, 15, 60, 180, 360 and 720 minutes; 3xx/4xx other than 408/425/429 aren't retried. After 10 deliveries in a row fail for good the endpoint is turned off (the dashboard says why). Deliveries are listed for 30 days, with "Send again". ## Webhooks Use a webhook to send every call to a system without a built-in connector: your own CRM or ERP, Odoo, or Zapier, Make and n8n. Set it up in the dashboard: Integrations → Webhook → Connect (Growth plan and above). The endpoint must be https and public. Set a signing secret of at least 16 characters, and press "Send test event". ### Events | Event | When | | --- | --- | | call.created | A call from an agent's phone is logged. Sent once per call, about two minutes after it ends, so notes and the recording usually come with it. | | call.updated | Someone saves the call's outcome, notes, follow-up or custom fields. Changes close together are combined. | | recording.added | The recording finishes uploading (or is replaced). `call.recordingUrl` is set. | | ping | "Send test event" in the dashboard. Body has `"test": true` and a sample call. | Every event carries the whole current state of the call, not only what changed. ### Payload ```json { "event": "call.updated", "deliveryId": "8b0f6c1e-3a52-4c55-9d6a-0b7d3e2f9a41", "sentAt": "2026-10-02T06:15:31.204Z", "call": { "id": "66fc1f5e9b1d4a0012a3b4c5", "phoneNumber": "+91 98765 43210", "normalizedNumber": "+919876543210", "contactName": "Priya Sharma", "direction": "OUTGOING", "startedAt": "2026-10-02T06:09:12.000Z", "durationSec": 252, "disposition": "Interested", "notes": "Wants a site visit on Saturday.", "followUpAt": "2026-10-04T04:30:00.000Z", "tags": [], "recordingUrl": "https://api.callbix.app/public/recordings/66fc1f5e…?exp=…&sig=…", "fields": { "budget": 7500000, "site_visit_booked": true, "product_interest": ["2 BHK", "3 BHK"] }, "agent": { "id": "66f9a2b1c3d4e5f601234567", "name": "Ravi Kumar", "email": "ravi@acme.in", "phone": "+91 99887 76655" } }, "contact": null } ``` - `call.id` is stable across every event for a call: use it as your key. - `call.direction`: INCOMING, OUTGOING, MISSED, REJECTED, BLOCKED or UNKNOWN. - `call.durationSec` is talk time; 0 for unanswered calls. - `call.disposition` is the outcome the agent picked. - `call.recordingUrl` redirects to the audio file and stays valid for a year by default; null until uploaded. - `call.fields` holds your custom fields (Webhook → Fields & status), keyed by the key you chose. Text, email, phone and link are strings; number is a number; yes/no is a boolean; date is "YYYY-MM-DD"; date & time is ISO 8601 UTC; pick one is a string; pick many is an array of strings; empty is null or missing. - `contact` is always null for webhooks. ### Headers | Header | Value | | --- | --- | | Content-Type | application/json | | User-Agent | CallBix-Webhook/1.0 | | X-CallBix-Event | The event name. | | X-CallBix-Delivery | Unique id of this request (same as deliveryId). | | X-CallBix-Event-Id | The call id; the same for every event and retry about one call. | | X-CallBix-Signature | Hex HMAC-SHA256 of the raw body, keyed with your signing secret. Sent when a secret is set. | ### Verifying signatures Compute HMAC-SHA256 over the raw request body exactly as received, hex-encode it, and compare with `X-CallBix-Signature` in constant time. Don't parse and re-serialise the JSON first. Reject events whose `sentAt` is more than about five minutes old to stop replays. ```js import crypto from "node:crypto"; import express from "express"; const app = express(); app.post("/callbix", express.raw({ type: "application/json" }), (req, res) => { const expected = crypto.createHmac("sha256", process.env.CALLBIX_WEBHOOK_SECRET).update(req.body).digest("hex"); const received = req.get("X-CallBix-Signature") ?? ""; if (received.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected))) return res.status(401).send("bad signature"); const event = JSON.parse(req.body.toString("utf8")); if (Date.now() - Date.parse(event.sentAt) > 5 * 60_000) return res.status(400).send("too old"); queue.add(event); // answer fast, work in the background res.sendStatus(204); }); ``` ```php ` (the token is the credential). - Facebook and Instagram lead ads: connect the Pages and forms; no code. - Google Ads lead forms: paste the URL and key into the form's webhook settings. - IndiaMART: pulled from Lead Manager every 10 minutes. - Property and listing portals (JustDial, MagicBricks, 99acres, Housing.com, NoBroker, Sulekha, TradeIndia and others): the portal pushes each lead to the URL by POST, or GET with the lead in the query. - Website forms: post a form to the URL. ### Posting a website form from your server From a server (PHP, Contact Form 7 hook, Zapier, your backend), send the source's key in `X-CallBix-Key`. JSON, form-encoded and multipart bodies all work. ```bash curl -X POST https://api.callbix.app/public/leads/ \ -H "X-CallBix-Key: " \ -H "Content-Type: application/json" \ -d '{"name":"Neha Gupta","phone":"+91 98765 00001","email":"neha@example.com","company":"Gupta Traders","message":"Need a quote for 200 units","city":"Pune"}' ``` Answers `{ "ok": true }`, or `{ "ok": false, "message": "…" }` with a 4xx. Field names are matched loosely: - Phone: phone, mobile, tel, phone_number, mobile_number, contact_number, whatsapp… - Name: name, full_name, your_name (or first_name + last_name) - Email: email, email_address - Company: company, company_name, business, organisation - Notes: message, notes, comments, enquiry, query, requirement, description Any other fields are kept with the lead and shown to the agent. A plain HTML form posted from a browser is also supported. The dashboard gives the snippet, which includes the spam protection the browser needs, and sends the visitor to your thank-you page. ## Built-in connectors (no code) - CRMs: Zoho CRM, Salesforce, HubSpot, Pipedrive, Freshsales, LeadSquared, Microsoft Dynamics 365. Calls are logged on the matching contact or lead with duration, outcome, notes and recording; fields can be read before the call and written back after; follow-ups become tasks; deals can be opened from a call result. - WhatsApp messages through MotherBot: approved templates after calls, after missed calls and before call-backs. - Team chat alerts: Slack, Microsoft Teams and Google Chat incoming webhooks, for missed calls, call requests, new leads, hot leads, customers going cold, unhappy customers and targets reached. - AI on your own keys: OpenAI, Google Gemini, Deepgram or Sarvam transcribe recordings and write summaries, key points, action items, sentiment and a lead score. ## Recipes - New website or Facebook lead → call within a minute: on "new lead" in Zapier, Make or n8n, POST /call-request with the phone and name. - CRM lead becomes "Hot" → call it: a Zoho workflow, HubSpot workflow or Salesforce Flow calls POST /call-request with `assignTo: "owner:"`. - Nightly batch: POST /leads with tomorrow's leads; agents see them in the app's Lists tab in the morning. - Close the loop: point a webhook at your system to get each call's outcome, notes and recording. - A booking becomes a visit: Calendly, your booking page or a CRM workflow calls POST /visits with the time and address; subscribe to visit.checked_out to get how it went. - Anything else, no code: a Workflow in the dashboard (e.g. missed call → wait 15 min → if still unanswered, push the agent and post to Slack). - Spreadsheet of results: POST /calls/summary with a column of numbers, or page through GET /call-log.