Telephony 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.

Telephony account status

Which Twilio account the business's calls and texts run on (MANAGED: its ServFlo sub-account, billed at Twilio's cost + 20%; OWN: its own Twilio account), the sub-account's state (ACTIVE, SUSPENDED while the ServFlo subscription is unpaid or cancelled, CLOSED), the managed texting number, the A2P 10DLC status, numbers scheduled for release and warnings for the owner. Read-only.

Example

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

Response

Choose the Twilio account

Money: MANAGED moves calls (and, once a ServFlo texting number is chosen, texts) to the business's ServFlo Twilio sub-account, made now if needed; numbers, minutes and other usage are then billed at Twilio's cost + 20%. Turning MANAGED on needs the owner's acceptance of the phone system's usage terms: a current one on record, or acknowledgement with the priceVersion shown (billing.plan → addons[phone].terms); otherwise 409 with the current terms. OWN goes back to the business's own Twilio account (it must be connected in Settings → Messaging first). Numbers already set up stay where they are.

Request body

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/telephony/source" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source":"MANAGED"}'

Response

Find a texting number

US local numbers that can text, available to buy in the business's ServFlo account, by area code and / or digits or letters inside the number (contains, e.g. 4210 or PLUMB), or local to the business (near: true: its ZIP, then within 50 miles, then its team's area codes, then its state; matchedBy says which), and what the number would cost a month (offer: Twilio's cost + 20%, or included: the texting number is included on every plan). Call before POST /telephony/texting with buyE164 (or POST /telephony/texting/replace to swap the current texting number). Makes the ServFlo sub-account the first time (no charge until a number is bought).

Parameters

Example

curl "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/telephony/numbers/available" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

Text through ServFlo

Money, customer-visible: makes the business's texts go out of its ServFlo Twilio sub-account from phoneNumberId (one of its ServFlo numbers) or a number bought now (buyE164, from GET /telephony/numbers/available; billed monthly at Twilio's cost + 20%). Replaces the SMS provider in Settings → Messaging (your own Twilio credentials are removed) and switches the business to ServFlo-managed telephony. Texts keep going through consent, quiet hours and the queue; texts from a live account start once the A2P 10DLC registration is approved.

Request body

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/telephony/texting" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumberId":"phoneNumber_id","buyE164":"string","label":"string"}'

Response

Can the texting number be replaced

Before POST /telephony/texting/replace ("change the main number"): whether the business's ServFlo texting number, its main line, can be swapped for another now, and what happens. Allowed before an A2P 10DLC registration is submitted (or after one refused before the brand was approved): the old number is released afterwards unless something else uses it (oldNumber.keptBecause). Refused while the registration is under review. After a standard brand is approved the new number joins its Messaging Service first; a sole proprietor's one number is swapped in it (mode SWAP_CAMPAIGN_NUMBER: carriers register the new number, usually within hours); with an approved campaign the old number is kept unless oldNumber is RELEASE. cost says what it adds to the bill. Read-only.

Parameters

Example

curl "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/telephony/texting/replacement" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

Replace the texting number

Money, customer-visible, destructive: changes the business's main number: swaps its ServFlo texting number for buyE164 (bought now; from GET /telephony/numbers/available, near: true for a local one) or phoneNumberId (one of its ServFlo numbers). Call GET /telephony/texting/replacement first: refused with 409 for the same reasons (A2P registration under review, the free trial's one change). The new number is in place (and in the A2P Messaging Service when there is one; a sole proprietor's one number is swapped there) before texts move to it. It becomes the main line (default caller ID) with the old one's ring group and menu, and the business phone customers see (and the website draft) follows when it showed the old number (updateBusinessPhone: false to leave them). Then the old number is released back to Twilio unless something else uses it (ring routing, tracking, call history, an approved campaign) or oldNumber says KEEP / RELEASE. Customers see the new number on every text from now on. A number is billed monthly at Twilio's cost + 20% (the texting number is included), with no refund for the released number's month.

Request body

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/telephony/texting/replace" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"buyE164":"string","phoneNumberId":"phoneNumber_id","label":"string"}'

Response

A2P 10DLC registration

The business's A2P 10DLC registration in its ServFlo sub-account (US carriers require it for texts from business numbers): NOT_STARTED, PROFILE_SUBMITTED, BRAND_PENDING, OTP_PENDING (a sole proprietor must reply YES to the confirmation text), BRAND_APPROVED, CAMPAIGN_PENDING, APPROVED or FAILED (with issues: what Twilio refused, per field, in plain English), what was submitted, and suggestions from the business profile, website and the signed-in person. Read-only.

Example

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

Response

Register for A2P 10DLC

Money, sends data out: submits the business (legal name, EIN, address, website, an authorized representative) and its texting campaign (use case, description, opt-in flow, sample messages) to Twilio and The Campaign Registry from the business's ServFlo sub-account. Twilio's brand and campaign fees are billed at cost + 20%. brandType STANDARD needs the EIN; SOLE_PROPRIETOR (no EIN) registers the owner, who then confirms by replying YES to a text (OTP_PENDING; one number, lower volume). Needs a ServFlo texting number first, and refused with 400 and data.items while GET /telephony/a2p/readiness has a failure (call it first). Approval takes days: the status updates by itself (GET /telephony/a2p). A FAILED registration can be corrected and submitted again: issues name the fields Twilio refused; a failed campaign under an approved brand is replaced (a new campaign vetting fee).

Request body

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/telephony/a2p" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"legalName":"string","businessType":"Sole Proprietorship","websiteUrl":"https://example.com","street":"string","city":"string","region":"string","postalCode":"string","representative":{"firstName":"string","lastName":"string","email":"dana@example.com","phone":"+15555550123","title":"string"},"description":"string","messageFlow":"string","sampleMessages":["string"]}'

Response

Check an A2P registration before submitting

Runs the checks that keep an A2P 10DLC registration from being rejected, without sending anything: texting number, legal name vs business type (match the IRS EIN letter), EIN, physical address, website / privacy / terms open publicly (fetched now), the privacy policy's SMS clause and the booking page's consent checkbox, the representative, the campaign text and samples (business name, STOP), lengths and restricted content. Checks what was submitted, else the suggestions; websiteUrl, privacyUrl, termsUrl check other addresses. Each item is pass, warn or fail; POST /telephony/a2p is refused while any fails. Read-only.

Parameters

Example

curl "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/telephony/a2p/readiness" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

Resend the sole proprietor confirmation text

Sends a text: a sole proprietor's brand is confirmed by its owner replying YES to a text Twilio sends to the representative's mobile (valid 24 hours). This asks Twilio to send it again; only while the status is OTP_PENDING, at most every five minutes.

Example

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

Response

Check the A2P status now

Asks Twilio for the brand or campaign status now instead of waiting for the worker; once the brand is approved this creates the Messaging Service in the sub-account, adds the texting number and submits the campaign.

Example

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

Response

Telephony usage this month

This month's telephony from the business's ServFlo sub-account per category (voice minutes, numbers, texts, recordings, transcriptions, registration fees, other): counts, what is billed so far and the estimate to date at Twilio's cost × 1.2. Texts are shown but billed by the plan's text allowance. Read-only.

Example

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

Response

Run telephony jobs now

Run this business's telephony jobs now instead of waiting for the worker: reconcile the sub-account with the ServFlo subscription (suspend, reactivate, close, scheduled number releases), bill settled Twilio usage (each account × day × category once) and check the A2P registration. now is test-only (refused in production).

Request body

Example

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

Response