Help
servflo.aiSign inStart free trial
DevelopersAPI referencePhone

Phone numbers API

REST endpoints for phone numbers in ServFlo: 6 operations with parameters, request and response fields, permissions and curl examples.

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.

OperationEndpointRisk
List phone numbersGET /organizations/{organizationId}/phone/numbersread
Buy or assign a numberPOST /organizations/{organizationId}/phone/numberssensitive
Numbers available to buyGET /organizations/{organizationId}/phone/numbers/availableread
Twilio numbers not in useGET /organizations/{organizationId}/phone/numbers/unassignedread
Change a numberPATCH /organizations/{organizationId}/phone/numbers/{phoneNumberId}write
Release a numberDELETE /organizations/{organizationId}/phone/numbers/{phoneNumberId}sensitive

List phone numbers

GET /organizations/{organizationId}/phone/numbers

The business's numbers: the main line and tracking numbers per source (website, Google Business Profile, a campaign, a QR code, a business unit, print), each with its ring group, menu and website number-insertion rule. includeReleased adds released ones. Read-only.

Permissionphone.read (Owner, Admin, Dispatcher, Member)
Riskread, OAuth scope servflo.read. Read: reads only.
MCP toolphoneNumbers_list (toolset marketing)

Parameters

NameInTypeRequiredDescription
includeReleasedquerybooleanNo

Example

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

Response

200: the answer's fields
FieldTypeDescription
itemsarray of object
items[].idstring
items[].e164string
items[].labelstring
items[].sourceenumOne of MAIN, WEBSITE, GOOGLE_BUSINESS, CAMPAIGN, QR_CODE, BUSINESS_UNIT, PRINT, OTHER, PERSONAL.
items[].userIdstring or nullWhose own line it is (source PERSONAL); null = the business's.
items[].fakeboolean
items[].campaignobject or null
items[].campaign.idstring
items[].campaign.namestring
items[].businessUnitobject or null
items[].businessUnit.idstring
items[].businessUnit.namestring
items[].qrCodeobject or null
items[].qrCode.idstring
items[].qrCode.namestring
items[].ringGroupobject or null
items[].ringGroup.idstring
items[].ringGroup.namestring
items[].ivrEnabledboolean
items[].ivrGreetingstring or null
items[].ivrOptionsarray of object
items[].ivrOptions[].digitstring
items[].ivrOptions[].labelstring
items[].ivrOptions[].ringGroupIdstring
items[].dniUtmSourcestring or null
items[].dniUtmMediumstring or null
items[].activeboolean
items[].releaseAfterstring (date-time) or nullScheduled release (the phone add-on was removed); null when kept.
items[].createdAtstring (date-time)
items[].updatedAtstring (date-time)

Buy or assign a number

POST /organizations/{organizationId}/phone/numbers

Money: mode BUY purchases the number in the business's ServFlo Twilio sub-account (billed monthly at Twilio's cost + 20%), or on its own Twilio account when it chose OWN; ASSIGN takes a number already on that account. Either way its voice webhooks are pointed at ServFlo and calls to it are tracked under source. Call GET /phone/numbers/available (or /unassigned) first.

Permissionphone.manage (Owner, Admin)
Risksensitive, OAuth scope servflo.sensitive. Sensitive: moves money, deletes, sends or shows something to a customer, or grants or revokes access.
MCP toolphoneNumbers_add (toolset marketing)
PlanNeeds the Phone system add-on.
ApprovalOver MCP, this tool asks for your OK first (in the AI app when it supports it, otherwise in ServFlo). See Approvals.

Request body

FieldTypeRequiredDescription
labelstringYesUp to 80 characters.
sourceenumNoWhere the number is published; its calls are reported under it. One of MAIN, WEBSITE, GOOGLE_BUSINESS, CAMPAIGN, QR_CODE, BUSINESS_UNIT, PRINT, OTHER.
campaignIdstring or nullNoA marketing campaign whose number this is.
businessUnitIdstring or nullNoA business unit whose calls this number takes.
qrCodeIdstring or nullNoA QR code (printed material) this number is on.
ringGroupIdstring or nullNoWho rings; null = the business's default ring group.
ivrEnabledbooleanNo
ivrGreetingstring or nullNoUp to 500 characters.
ivrOptionsarray of objectNoUp to 9 items.
ivrOptions[].digitstringYes
ivrOptions[].labelstringYesUp to 80 characters.
ivrOptions[].ringGroupIdstringYesThe ring group this choice rings (GET /phone/ring-groups).
dniUtmSourcestring or nullNoWebsite number insertion: show this number to visitors with this utm_source (e.g. google). Up to 60 characters.
dniUtmMediumstring or nullNo…and this utm_medium (e.g. cpc); blank = any. Up to 60 characters.
modeenumYesOne of BUY, ASSIGN.
e164stringYesA phone number; +E.164 is safest (+13125550100). 10 digits are read as US. Up to 32 characters.

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/phone/numbers" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label":"string","mode":"BUY","e164":"string"}'

Response

201: the answer's fields
FieldTypeDescription
idstring
e164string
labelstring
sourceenumOne of MAIN, WEBSITE, GOOGLE_BUSINESS, CAMPAIGN, QR_CODE, BUSINESS_UNIT, PRINT, OTHER, PERSONAL.
userIdstring or nullWhose own line it is (source PERSONAL); null = the business's.
fakeboolean
campaignobject or null
campaign.idstring
campaign.namestring
businessUnitobject or null
businessUnit.idstring
businessUnit.namestring
qrCodeobject or null
qrCode.idstring
qrCode.namestring
ringGroupobject or null
ringGroup.idstring
ringGroup.namestring
ivrEnabledboolean
ivrGreetingstring or null
ivrOptionsarray of object
ivrOptions[].digitstring
ivrOptions[].labelstring
ivrOptions[].ringGroupIdstring
dniUtmSourcestring or null
dniUtmMediumstring or null
activeboolean
releaseAfterstring (date-time) or nullScheduled release (the phone add-on was removed); null when kept.
createdAtstring (date-time)
updatedAtstring (date-time)

Numbers available to buy

GET /organizations/{organizationId}/phone/numbers/available

Local US numbers Twilio offers to buy, by area code and / or digits or letters inside the number (contains, e.g. 4210 or PLUMB; * for any digit) (fake mode: fictional 555-01xx numbers), and what one more number costs a month (offer: Twilio's cost + 20%, or included). Then POST /phone/numbers with mode BUY. Read-only.

Permissionphone.manage (Owner, Admin)
Riskread, OAuth scope servflo.read. Read: reads only.
MCP toolphoneNumbers_available (toolset marketing)

Parameters

NameInTypeRequiredDescription
areaCodequerystringNoThree-digit US area code, e.g. 512. Optional when contains is given.
containsquerystringNoDigits or letters the number must contain, anywhere (Twilio Contains): 2–10 of 0-9, A-Z (phone keypad: PLUMB = 75862) and * for any one digit, e.g. 4210 or 555****. Spaces and dashes are ignored. With neither field, any US local number. Up to 20 characters.

Example

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

Response

200: the answer's fields
FieldTypeDescription
itemsarray of object
items[].e164string+E.164; pass it as buyE164 / e164 to buy it.
items[].localitystring or nullTwilio's rate center (city), when known.
items[].regionstring or nullTwo-letter state, when known.
offerobjectWhat one more number costs a month.
offer.monthlyCentsintegerA local number's monthly price at Twilio's cost + 20%, in cents.
offer.includedbooleanIncluded: the phone add-on's number (or the texting number).
offer.includedByenum or nullOne of TEXTING, PHONE_ADDON.
offer.sourceenumOne of twilio, fallback.
offer.unavailableReasonstring or nullSet when one more number cannot be bought now (the free trial includes one number and it is held): POST /phone/numbers would refuse it. Null otherwise.

Twilio numbers not in use

GET /organizations/{organizationId}/phone/numbers/unassigned

Numbers already on the business's Twilio account that ServFlo does not use yet: assign one with POST /phone/numbers mode ASSIGN instead of buying. Empty in fake mode. Read-only.

Permissionphone.manage (Owner, Admin)
Riskread, OAuth scope servflo.read. Read: reads only.
MCP toolphoneNumbers_unassigned (toolset marketing)

Example

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

Response

200: the answer's fields
FieldTypeDescription
itemsarray of object
items[].sidstring
items[].e164string
items[].friendlyNamestring or null

Change a number

PATCH /organizations/{organizationId}/phone/numbers/{phoneNumberId}

Change a number's label, tracked source (campaign, QR code, business unit), ring group, menu (press 1 for … → a ring group) and website number-insertion rule. Applies from the next call.

Permissionphone.manage (Owner, Admin)
Riskwrite, OAuth scope servflo.write. Write: creates or changes records inside the business; nothing leaves it.
MCP toolphoneNumbers_update (toolset marketing)
PlanNeeds the Phone system add-on.

Parameters

NameInTypeRequiredDescription
phoneNumberIdpathstringYes

Request body

FieldTypeRequiredDescription
labelstringNoUp to 80 characters.
sourceenumNoWhere the number is published; its calls are reported under it. One of MAIN, WEBSITE, GOOGLE_BUSINESS, CAMPAIGN, QR_CODE, BUSINESS_UNIT, PRINT, OTHER.
campaignIdstring or nullNoA marketing campaign whose number this is.
businessUnitIdstring or nullNoA business unit whose calls this number takes.
qrCodeIdstring or nullNoA QR code (printed material) this number is on.
ringGroupIdstring or nullNoWho rings; null = the business's default ring group.
ivrEnabledbooleanNo
ivrGreetingstring or nullNoUp to 500 characters.
ivrOptionsarray of objectNoUp to 9 items.
ivrOptions[].digitstringYes
ivrOptions[].labelstringYesUp to 80 characters.
ivrOptions[].ringGroupIdstringYesThe ring group this choice rings (GET /phone/ring-groups).
dniUtmSourcestring or nullNoWebsite number insertion: show this number to visitors with this utm_source (e.g. google). Up to 60 characters.
dniUtmMediumstring or nullNo…and this utm_medium (e.g. cpc); blank = any. Up to 60 characters.

Example

curl -X PATCH "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/phone/numbers/{phoneNumberId}" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label":"string","source":"MAIN","campaignId":"campaign_id"}'

Response

200: the answer's fields
FieldTypeDescription
idstring
e164string
labelstring
sourceenumOne of MAIN, WEBSITE, GOOGLE_BUSINESS, CAMPAIGN, QR_CODE, BUSINESS_UNIT, PRINT, OTHER, PERSONAL.
userIdstring or nullWhose own line it is (source PERSONAL); null = the business's.
fakeboolean
campaignobject or null
campaign.idstring
campaign.namestring
businessUnitobject or null
businessUnit.idstring
businessUnit.namestring
qrCodeobject or null
qrCode.idstring
qrCode.namestring
ringGroupobject or null
ringGroup.idstring
ringGroup.namestring
ivrEnabledboolean
ivrGreetingstring or null
ivrOptionsarray of object
ivrOptions[].digitstring
ivrOptions[].labelstring
ivrOptions[].ringGroupIdstring
dniUtmSourcestring or null
dniUtmMediumstring or null
activeboolean
releaseAfterstring (date-time) or nullScheduled release (the phone add-on was removed); null when kept.
createdAtstring (date-time)
updatedAtstring (date-time)

Release a number

DELETE /organizations/{organizationId}/phone/numbers/{phoneNumberId}

Destructive: gives the number back to Twilio; it stops ringing and may be taken by someone else. Its call history stays. Cannot be undone.

Permissionphone.manage (Owner, Admin)
Risksensitive, OAuth scope servflo.sensitive. Sensitive: moves money, deletes, sends or shows something to a customer, or grants or revokes access.
MCP toolphoneNumbers_release (toolset marketing)
ApprovalOver MCP, this tool always waits for your approval in ServFlo. See Approvals.

Parameters

NameInTypeRequiredDescription
phoneNumberIdpathstringYes

Example

curl -X DELETE "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/phone/numbers/{phoneNumberId}" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields
FieldTypeDescription
idstring
e164string
labelstring
sourceenumOne of MAIN, WEBSITE, GOOGLE_BUSINESS, CAMPAIGN, QR_CODE, BUSINESS_UNIT, PRINT, OTHER, PERSONAL.
userIdstring or nullWhose own line it is (source PERSONAL); null = the business's.
fakeboolean
campaignobject or null
campaign.idstring
campaign.namestring
businessUnitobject or null
businessUnit.idstring
businessUnit.namestring
qrCodeobject or null
qrCode.idstring
qrCode.namestring
ringGroupobject or null
ringGroup.idstring
ringGroup.namestring
ivrEnabledboolean
ivrGreetingstring or null
ivrOptionsarray of object
ivrOptions[].digitstring
ivrOptions[].labelstring
ivrOptions[].ringGroupIdstring
dniUtmSourcestring or null
dniUtmMediumstring or null
activeboolean
releaseAfterstring (date-time) or nullScheduled release (the phone add-on was removed); null when kept.
createdAtstring (date-time)
updatedAtstring (date-time)

Phone API

REST endpoints for phone in ServFlo: 11 operations with parameters, request and response fields, permissions and curl examples.

Phone ring groups API

REST endpoints for phone ring groups in ServFlo: 4 operations with parameters, request and response fields, permissions and curl examples.

On this page

List phone numbersParametersExampleResponseBuy or assign a numberRequest bodyExampleResponseNumbers available to buyParametersExampleResponseTwilio numbers not in useExampleResponseChange a numberParametersRequest bodyExampleResponseRelease a numberParametersExampleResponse