Phone API

Base URL: https://app.servflo.ai/api. Every call needs Authorization: Bearer sfk_… (Authentication); {organizationId} ($ORGANIZATION_ID in the examples) is your business's id.

Phone settings

The phone system's settings: on/off, the mode (twilio, or fake = simulated calls), business hours in the business's timezone, after-hours voicemail or forwarding, ring timeout and the default ring group, voicemail greeting, call recording with its consent announcement and retention, transcription and AI summaries, missed-call follow-ups and text-back, and the webhook URLs Twilio calls. Read-only.

Example

curl "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/phone/settings" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

Change phone settings

Change how calls are handled from the next call on: business hours, after hours, ring timeout, default ring group, voicemail greeting, recording (announced by default; two-party-consent states are always announced), retention, transcription, AI summaries (metered against AI credits), missed-call follow-ups and the missed-call text (sent only to known customers whose number is OK to text). enabled: false stops answering calls.

Request body

Example

curl -X PATCH "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/phone/settings" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true,"businessHours":{"sun":[{"start":"09:00","end":"09:00"}],"mon":[{"start":"09:00","end":"09:00"}],"tue":[{"start":"09:00","end":"09:00"}]},"afterHoursAction":"VOICEMAIL"}'

Response

Connect voice

Turn the phone system on. Makes the business's ServFlo Twilio sub-account the first time (MANAGED, the default; usage billed at Twilio's cost + 20%), then creates an API key and a TwiML App in that account (or in the business's own Twilio account when it chose OWN) for the browser phone; safe to repeat (the App's URLs are refreshed). In fake mode it records simulated ids. Call GET /phone/settings first to see the mode.

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/phone/connect" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

Browser phone token

What the browser phone needs for the signed-in person: mode TWILIO with a one-hour Twilio Voice access token (identity derived from the user; receives the ring group's calls, places calls through the business number), FAKE (simulated calls), OFF (phone system off) or UNAVAILABLE (connect voice first). Nothing else changes.

Permission: phone.calls (Owner, Admin, Dispatcher, Technician (own jobs)); risk write (OAuth scope servflo.write).

Request body

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/phone/softphone-token" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"platform":"ios"}'

Response

Calls ringing for me

Calls ringing for the signed-in person's ring groups and calls they are on: what the browser phone and the screen pop show. Poll every few seconds. Read-only (simulated calls nobody answered are ended as Twilio would).

Permission: phone.calls (Owner, Admin, Dispatcher, Technician (own jobs)); risk read (OAuth scope servflo.read).

Example

curl "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/phone/live" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

Simulate an inbound call (fake mode)

Only with simulated voice (SERVFLO_VOICE=fake; 409 otherwise): an inbound call from from to one of the business's numbers, through the same steps as Twilio's webhooks (routing, caller match, menu, recording, transcript, AI summary, follow-up, text-back). RING leaves it ringing for the browser phone; ANSWERED, MISSED and VOICEMAIL play it through. now is test-only (refused in production).

Request body

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/phone/simulate" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from":"2026-11-03"}'

Response

AI receptionist settings

The AI receptionist's settings: on/off, when it answers (ALWAYS, AFTER_HOURS, OVERFLOW instead of voicemail), greeting and instructions (whether the greeting introduces it as the virtual assistant, and how it names a known caller: callerGreeting), the trade template, voice and language, who a transfer rings, and what it may do (book real arrival windows and move a known caller's visit, take requests and cancellation requests, say pricebook prices by priceMode, tell a known caller their balance, text links). Also the trade templates, the greeting as spoken, and whether this server can run it (keys, booking mode, problems to fix). Read-only.

Example

curl "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/phone/ai-receptionist" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

Change the AI receptionist

Change the AI receptionist from the next call on. When on, Claude answers calls by voice in the chosen mode, always says the call is transcribed, says it is the virtual assistant in the greeting unless announceAssistant is false, names a caller whose number matches a customer by callerGreeting (FIRST_NAME, TITLE_LAST_NAME with the customer's own title, or GENERIC; unknown numbers are always greeted generically, and a known number is still verified by full name and service ZIP before their visits or account), and never claims to be a person (asked, it says it is the business's AI assistant). It may book arrival windows and move a known caller's visit to one (canBook; the online booking rules, confirmed with the caller first), take requests, messages and a known caller's cancellation request (canTakeRequests; it never cancels: the office confirms, with a follow-up on the call and a notification), say pricebook prices (priceMode OFF, STARTING_AT or EXACT; never a cost), tell a known caller their open balance once their name matches (canShareBalance), text known customers a link (canTextLinks; consent applies), and transfer to a ring group or number. It never invents prices or availability. Its model use is metered against AI credits and its voice minutes as ai_voice.minutes. transferRingGroupId must be one of the business's ring groups. Needs the phone add-on, except to switch it off.

Request body

Example

curl -X PATCH "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/phone/ai-receptionist" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true,"mode":"ALWAYS","greeting":"string"}'

Response

Hear a voice for the AI receptionist

Speaks the receptionist's opening line ("Thanks for calling <business>…") in a voice, so the owner can compare voices before choosing one. Returns a short 8 kHz WAV, base64, exactly as a caller hears it on the phone. Changes nothing (the voice is chosen with PATCH …/phone/ai-receptionist). The voices offered per provider and language are AI_VOICE_CATALOG (voiceId blank = the provider's default). MONEY: a live sample uses AI credits (about 1 per sample, for the provider's text-to-speech); 402 PLAN_LIMIT_REACHED when the business has none left. Limited per business. 409 when this server has no voice for that provider; simulated = silence (SERVFLO_VOICE_AI=fake), free.

Parameters

Example

curl "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/phone/ai-receptionist/voice-sample?provider=DEEPGRAM&language=en" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

Simulate a call to the AI receptionist (fake mode)

Only with simulated voice and SERVFLO_VOICE_AI=fake (409 otherwise): a call from from goes through routing to the receptionist, which runs the Twilio Media Streams protocol in-process with scripted speech-to-text (script: the caller's lines) and a scripted model (/tool name {json} calls a tool, bye ends the call, anything else is echoed). Writes the call log, the conversation, the request or booking it made and the summary, as a real call would. now is test-only.

Request body

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/phone/ai-receptionist/simulate" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from":"2026-11-03","script":["string"]}'

Response

Run phone work now

Run this business's pending phone work now instead of waiting for the worker: recording downloads into storage, AI summaries, simulated calls nobody answered, and recordings past retention. now is test-only (refused in production).

Request body

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/phone/run" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"now":"2026-11-03T15:00:00Z"}'

Response