API Reference
A complete reference for the Team Connect Account API. Make outbound calls, send and receive SMS, and integrate every Team Connect number you own with your own CRM, helpdesk or workflow tool.
01 Introduction
The Team Connect Account API lets your systems do everything you can do from the Team Connect dashboard, but from your own code. It is designed for CRM and back-office integrations.
The API authenticates as your Team Connect account using a single key, and every call is billed against the same Team Connect plan that powers your dashboard. There are no separate API charges, top-ups, or credit pools. If your plan has minutes and SMS credits available, your API calls work. If it runs out, the API returns a clear payment-required response and your dashboard prompts you to top up.
Each request operates on one or more of the Team Connect numbers you have registered on your account. Every number is identified by a stable phoneDocId which you discover at runtime through GET /v1/numbers. This means you never hard-code numbers in your integration — your CRM picks the right number for each call automatically, and adding a new Team Connect number requires no redeploy on your side.
What you can do
- List every voice + paired SMS number on your account.
- Place manual outbound calls from any of your numbers, with a server-side two-leg dial that rings your agent first then bridges to the customer.
- Place AI outbound calls, where the Team Connect AI dials the customer from your number and holds the conversation for you.
- Read your outbound call history — manual and AI — with status, duration and recording details.
- Send SMS from any SMS-enabled number on your account.
- Read sent and received SMS history with full delivery status.
- Poll for inbound SMS to feed into your CRM's notification flow.
02 Authentication
Every request must include your API key. Two interchangeable headers are accepted:
Pass either one — never both. All keys are prefixed with tca_. You can recognise a Team Connect API key at a glance by the prefix.
Getting a key
Sign in to your Team Connect dashboard and open the Account API page. Click Generate Key. The full key is shown to you exactly once — copy it and store it in your secret manager or server environment immediately. After dismissing the dialog, only a masked version of the key is visible. If you lose it, rotate the key to issue a new one.
Authentication errors
Missing or malformed credentials return 401 Unauthorized with a JSON body explaining what went wrong:
A suspended account (zero minutes or zero credits and past the grace period) returns 402 Payment Required. The CRM should surface this to the operator with a prompt to top up.
03 Base URL
All endpoints are served under a single versioned base URL:
The /v1 path segment is the API version. Future breaking changes will be released under /v2, and /v1 will continue to function for at least 12 months after the release of a successor version. Non-breaking changes (additive fields, new endpoints) are made in place within the current version.
04 Quick Start
From key to first call in three steps.
Step 1 — Discover your numbers
List every number on your account and note the phoneDocId for the line you want to use:
Step 2 — Place a call
Two-leg dial. Your agent's phone rings first; when they answer, the customer is dialled and connected:
Step 3 — Send an SMS
That is the entire surface needed to integrate. The remainder of this reference documents the request shape, response shape, and error behaviour of each endpoint in full.
05 Numbers
Numbers are the addressable units of your account. Each Team Connect number has a unique phoneDocId that identifies it across both voice and SMS, plus the dialable voice number and (where configured) the paired SMS sender number.
List numbers
Returns every voice number on your account, with each number's paired SMS sender if SMS is enabled.
Query parameters
None.
Response
Response fields
| Field | Type | Description |
|---|---|---|
| phoneDocId | string | Stable identifier for this number. Use it in all subsequent requests. |
| label | string | The business name or label you have assigned to this number in your dashboard. |
| voiceNumber | string | The E.164 phone number used as caller ID for outbound calls and as the destination for inbound calls. |
| smsNumber | string · nullable | The E.164 number used for sending and receiving SMS. null if no SMS number is paired with this line. |
| smsEnabled | boolean | Whether SMS sending is enabled on this number. |
| status | string | Current operational status. Always active for usable lines. |
/v1/numbers in your CRM and refresh on a schedule (every few hours is plenty) rather than calling it on every interaction.
06 Voice Calls
The API supports two kinds of outbound call, selected with the mode field on POST /v1/calls:
- Manual (default). A server-side two-leg dial. The API rings your agent's phone first, using the Team Connect business number as caller ID. When the agent answers, the customer is dialled from the same business number and the two parties are bridged on a recorded call. Your agent can be on any phone — mobile, desk, landline — no browser, SDK or softphone required.
- AI. The Team Connect AI places the call. Nobody rings on your side — the AI dials the customer directly from your number, introduces itself as your business, and holds the conversation in real time. Ideal for follow-ups, reminders, callbacks and confirmations triggered straight from your CRM.
Create a call
Initiates an outbound call. Defaults to a manual two-leg call; pass mode: "ai" to have the AI place the call instead (see AI calls below).
Request body
| Field | Type | Description | |
|---|---|---|---|
| phoneDocId | string | Required | The Team Connect number to call from. Obtained via GET /v1/numbers. |
| to | string | Required | The customer's phone number in E.164 format (e.g. +447700900222). |
| mode | string | Optional | "manual" (default) or "ai". Selects who makes the call: your agent, or the Team Connect AI. |
| agentPhone | string | Manual only | The phone number to ring first. If omitted, falls back to the default agent phone set on your API key. If neither is set, the request is rejected. Must be your own mobile, desk or landline — Team Connect numbers are rejected with agent_phone_is_tc_number (dialling your own Team Connect number would put your AI on the agent leg; use mode: "ai" if you want the AI to make the call). |
| customerName | string | AI only | The customer's name, so the AI can greet them personally. |
| callPurpose | string | AI only | What the call is about, e.g. "general" (default) or "custom" combined with customCallReason. |
| customCallReason | string | AI only | A plain-English reason for the call, e.g. "Confirm tomorrow's 10am appointment". Used when callPurpose is "custom". |
| aiInstructions | string | AI only | Extra steering for the AI on this specific call, e.g. "If they want to rebook, offer Thursday or Friday." |
The AI speaks with the voice already configured on the number, and uses your business name and details from your Team Connect setup — no per-call voice configuration needed.
Example
Response
Call flow
- Leg 1. Your agent's phone rings, showing the Team Connect business number as caller ID. They have 25 seconds to answer.
- Leg 2. When the agent picks up, they hear a brief "Connecting your call" message while the customer is dialled from the same business number.
- Bridge. When the customer answers, the two parties are connected on a recorded call.
- Billing. Minutes are deducted from your Team Connect plan when the call completes, using the duration from when the agent answered.
Edge cases
| Scenario | Final status | Billed? |
|---|---|---|
| Agent does not answer within 25 seconds | no-answer-agent | No |
| Agent answers, customer does not answer | completed | Yes — agent-leg duration only |
| Customer's number is busy | busy | Agent-leg duration only |
| Either party hangs up early | completed | Yes — actual duration |
| Customer voicemail picks up | completed | Yes — full duration |
Create an AI call
The Team Connect AI dials the customer directly from your number and holds the conversation. Use it to trigger follow-ups, appointment confirmations, callbacks and reminders straight from your CRM — no one on your team needs to pick up a phone.
Example
Response
Note that for AI calls, callId and callSid are the same value — use it with GET /v1/calls?mode=ai to check the outcome.
Call flow
- Dial. The AI dials the customer from your Team Connect number. Voicemail is detected automatically.
- Conversation. The AI introduces itself as your business, states the reason for the call, and responds to the customer in real time using your configured voice.
- Wrap-up. The call, transcript and outcome are recorded to your account and appear in the AI Outbound section of your dashboard, and via
GET /v1/calls?mode=ai. - Billing. AI calls deduct AI minutes from your plan — a separate allowance from the standard call minutes used by manual calls. If the account has no AI minutes available, the request is rejected with
402 insufficient_ai_minutesbefore any call is placed.
List calls
Returns your outbound call history, most recent first. Manual and AI calls are stored separately — select which history to read with the mode parameter.
Query parameters
| Parameter | Type | Description | |
|---|---|---|---|
| mode | string | Optional | "manual" (default) or "ai". Which call history to read. |
| phoneDocId | string | See desc | Restrict to one Team Connect number. Optional for manual history; required when mode=ai. |
| callId | string | Optional | Look up a single call. Requires phoneDocId. For AI calls this is the callSid returned at creation. |
| peer | string | Optional | Filter to calls with one customer number (E.164). |
| since | string | Optional | ISO-8601 timestamp lower bound, e.g. 2026-07-01T00:00:00Z. |
| status | string | Optional | Filter by call status, e.g. completed. |
| limit | number | Optional | Default 50, maximum 200. |
Example — recent AI calls
Response
Manual-mode results use the manual call shape instead: agentPhone, durationSeconds, startedAt, agentAnsweredAt, endedAt, recordingUrl and related fields.
07 SMS
Send and receive SMS from any number on your account that has an SMS sender configured. Sending is synchronous — you get a Twilio message SID back as soon as the message is accepted for delivery. Inbound messages land in your Team Connect inbox automatically and are readable via GET /v1/sms?direction=received.
Send an SMS
Request body
| Field | Type | Description | |
|---|---|---|---|
| phoneDocId | string | Required | The Team Connect number to send from. The number's paired SMS sender is used. |
| to | string | Required | Recipient phone number in E.164 format. |
| message | string | Required | Message content. Up to 1600 characters. Messages over 160 characters are sent as multiple SMS segments — see the response for the count. |
Example
Response
The messageId is Twilio's SID for the message. Use it later with GET /v1/sms?messageId=... to check delivery status (which transitions from sent to delivered once the carrier confirms receipt).
List SMS messages
Read sent or received SMS history. Supports four common patterns: single-message lookup, recent sent/received polling, conversation view with a specific peer, and time-windowed queries.
Query parameters
| Param | Type | Description | |
|---|---|---|---|
| phoneDocId | string | Optional | Restrict to messages on a specific Team Connect number. |
| direction | string | Optional | Either sent or received. If omitted with peer or phoneDocId set, both directions are returned (conversation view). |
| peer | string | Optional | Filter to messages exchanged with this E.164 number. |
| since | string · ISO 8601 | Optional | Only return messages sent at or after this timestamp. Use for inbound polling. |
| messageId | string | Optional | Look up one specific message by its Twilio SID. Overrides every other filter. |
| limit | integer | Optional | Maximum messages to return. Default 50, maximum 200. |
Examples
Response
The nextSince field is the timestamp of the oldest returned message. Pass this as since on the next call to paginate backwards through history.
GET /v1/sms?direction=received&since=<lastCheck> on a 30-second cadence. Save the highest sentAt from each response as your next since cursor. This is the simplest reliable inbound integration.
08 Errors
Every error response follows the same envelope:
Additional context fields may be present depending on the error.
HTTP status codes
| Code | Meaning | Common causes |
|---|---|---|
| 200 | OK | Successful read. |
| 201 | Created | Successful call placement or SMS send. |
| 400 | Bad Request | Missing or invalid field, malformed phone number, message too long. |
| 401 | Unauthorized | Missing or invalid API key. Key was revoked or rotated. |
| 402 | Payment Required | Account suspended, no minutes, or no SMS credits. Top up the Team Connect plan. |
| 403 | Forbidden | Key is scoped to a subset of numbers and the request targeted one outside that scope. |
| 404 | Not Found | No phoneDoc or message with the supplied ID exists on this account. |
| 405 | Method Not Allowed | Wrong HTTP verb. Check the endpoint reference. |
| 429 | Too Many Requests | Rate limit exceeded. Slow down and retry with backoff. |
| 500 | Internal Server Error | Unexpected failure. Retryable. |
| 502 | Bad Gateway | Downstream carrier rejected the request. Response includes the carrier code. |
Application error codes
| HTTP | Error code | Description |
|---|---|---|
| 401 | missing_api_key | No Authorization or X-API-Key header on the request. |
| 401 | invalid_api_key | Key not recognised, revoked, or has an incorrect prefix. |
| 401 | key_disabled | Key exists but has been administratively disabled. |
| 402 | account_suspended | Team Connect account is suspended. |
| 402 | insufficient_minutes | Voice call attempted with zero minutes available. |
| 400 | missing_field | A required body field was not supplied. |
| 400 | missing_agent_phone | No agentPhone in request and no default set on the key (manual calls only). |
| 400 | invalid_mode | mode must be "manual" or "ai". |
| 400 | agent_phone_is_tc_number | agentPhone is one of your own Team Connect numbers. Use your real phone, or mode:"ai". |
| 402 | insufficient_ai_minutes | AI call attempted with zero AI minutes available. |
| 404 | call_not_found | No call with that callId on the given phoneDocId. |
| 400 | invalid_number | A phone number is not valid E.164. |
| 400 | message_too_long | SMS body exceeds 1600 characters. |
| 400 | phoneDoc_sms_not_configured | The selected number has no SMS sender paired. |
| 400 | phoneDoc_sms_disabled | SMS is paired but disabled on this number. |
| 403 | phoneDocId_not_permitted | Key is scoped and the requested phoneDocId is not in its allow-list. |
| 404 | phoneDoc_not_found | No number with that phoneDocId on this account. |
| 404 | message_not_found | No SMS with that messageId on this account. |
09 Rate Limits & Billing
Rate limits
Each API key has a default rate limit of 600 requests per minute, shared across all endpoints. Exceeding the limit returns 429 Too Many Requests. Retry with exponential backoff — most CRM workloads never come close to this ceiling.
Billing
There are no separate API charges. Every API request that consumes a resource — a voice minute, an AI minute, an SMS segment — draws from the same plan allowance as your Team Connect dashboard usage. Manual calls deduct standard call minutes; AI calls deduct AI minutes — the same allowances your dashboard usage draws from. Read endpoints (GET /v1/numbers, GET /v1/calls, GET /v1/sms) are free.
Your Team Connect plan uses a two-bucket credit system: a subscription bucket that refills monthly, and a topup bucket that you can purchase at any time. The API draws from the subscription bucket first, then the topup bucket. You can never go negative — once both buckets are empty, write endpoints return 402 Payment Required and the dashboard prompts a top-up.
Suspension
Accounts at zero minutes are automatically suspended after a grace period. While suspended, the API returns 402 account_suspended on every request — including read endpoints — until credit is restored.
10 Security
Treat your API key like a password. Anyone who has it can act on your Team Connect account — read messages, send messages, and place chargeable phone calls.
- Store the key server-side. Use environment variables or a dedicated secret manager. Never paste it into front-end code, public repositories, screenshots or support tickets.
- HTTPS only. The API rejects plain-text requests. Every system that calls it must use TLS 1.2 or higher.
- Rotate periodically. Generate a fresh key on a regular cadence and after any staff change with access to the secret. Rotating revokes the old key immediately.
- Revoke on exposure. If you suspect the key has leaked, revoke it from the Account API page and issue a new one. The old key stops working the same second.
- Scope by number. If only some Team Connect numbers should be callable from your integration, restrict the key to those
phoneDocIds when you generate it. A scoped key cannot call or message from numbers outside its allow-list. - Monitor activity. The Account API page in your Team Connect dashboard shows total request count and last-used timestamp for the active key. Sudden jumps suggest a leak or a misbehaving integration.
11 Support
Questions about integration, billing, or specific error responses go to the Team Connect support team via the in-product support page in your dashboard.
When reporting an issue, please include:
- The endpoint you called and the HTTP method.
- The exact request body or query string (with the API key redacted).
- The full response — status code, headers, and body.
- A timestamp of the request, accurate to the minute.
The masked first 8 and last 4 characters of your API key are enough for support to locate the affected request in our logs. Never paste a full key into a support ticket.