MB SuiteMB Suite
Menu

API reference · Phones

Lines

crm_phones · lines · 6 operations

GET/v1/phones/linesGET/v1/phones/lines/{line_id}POST/v1/phones/lines/{line_id}/renamePOST/v1/phones/lines/{line_id}/destinationPATCH/v1/phones/lines/{line_id}/inboundPOST/v1/phones/lines/{line_id}/receivers
GET/v1/phones/lines

List the organization's phone lines

crm_phones.lines.list

ReadIdempotentSince 2026-11-01

Lists the phone numbers the organization bought in Phones, in the order of Settings → Lines (manual order first, then newest), paginated by cursor (limit up to 200): number, name, country, type, capabilities (voice, sms, mms), status (active, cancelling = release scheduled at cancel_at, suspended_unpaid, released), destination (which part of the product uses the line: crm or support), monthly list price in USD cents, who pays it (own subscription or the parent workspace), who rings on incoming calls, ring timeout, voicemail, call recording and whether it is dedicated to WhatsApp. Released lines are history and are left out unless include_released=true or status=released. Filters (status, destination) apply to the lines read, up to 500. Buying and releasing numbers is done on the Phones screen. Requires view access to Phones.

Scope
crm_phones:read
Permission
View the module
MCP tool
crm_phones_lines_listOn the full surface; on the compact one, mb_execute_operation with id: "crm_phones.lines.list".

Declared cost: up to 500 reads and 0 writes per call (they count against the daily quota).

Parameters

limitintegerqueryoptional

How many items this page brings at most (see the maximum and the default in the schema).

Default: 50

cursorstringqueryoptional

The next_cursor of the previous page, exactly as it came (only for the same list and filters); without it, the first page.

statusenumqueryoptional

Only the lines in this status: active, cancelling, suspended_unpaid, suspended, releasing or released.

Values: active, cancelling, released, suspended_unpaid, suspended, releasing

destinationenumqueryoptional

Only the lines of this part of the product: crm or support.

Values: crm, support

include_releasedbooleanqueryoptional

Also the released lines (history: the number went back to the carrier).

Response

dataarray<object>
has_moreboolean
next_cursorstring

Errors

invalid_inputunknown_fieldauthentication_requiredscope_insufficientmodule_access_deniedoperation_not_foundrate_limitedquota_exceeded

Example

curl "https://api.mb-suite.com/v1/phones/lines" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl "https://api.mb-suite.com/v1/phones/lines" \
  -H "Authorization: Bearer $MB_TEST_KEY"
GET/v1/phones/lines/{line_id}

Get one phone line

crm_phones.lines.get

ReadIdempotentSince 2026-11-01

Returns one phone line of the organization by its id (the id crm_phones.lines.list returns): number, name, country, type, capabilities, status, destination, monthly price, billing mode, incoming-call settings (receivers, ring timeout in seconds, voicemail and its greeting, recording and the notice version accepted) and whether it is dedicated to WhatsApp (whatsapp_phone_number_id is the WhatsApp line in crm.lines.list). Not found (line_not_found) if the id is not a line of this organization. Requires view access to Phones.

Scope
crm_phones:read
Permission
View the module
MCP tool
crm_phones_lines_getOn the full surface; on the compact one, mb_execute_operation with id: "crm_phones.lines.get".

Declared cost: up to 1 reads and 0 writes per call (they count against the daily quota).

Parameters

line_idstringpathrequired

The phone line: an id from crm_phones.lines.list.

Response

idstring
phone_numberstring
friendly_namestring | null
country_isostring
typestring

local, mobile, toll-free, national or international.

capabilitiesarray<string>

voice, sms, mms and/or fax.

statusstring

active, cancelling (release scheduled at cancel_at), suspended_unpaid, suspended, releasing or released.

destinationstring

The part of the product that uses the line: crm or support.

monthly_cost_usd_centsnumber

The monthly list price, in USD cents.

billing_modestring

Who pays it: own_subscription or parent_child_billing (the parent workspace).

purchased_atnumber | null
cancel_atnumber | null

With a release scheduled: when the number is released.

release_scheduled_atnumber | null
inbound_receiversarray<string>

The members who ring on an incoming call, all at once.

inbound_timeout_secnumber
voicemail_enabledboolean
voicemail_greetingstring | null
recording_enabledboolean
recording_enabled_atnumber | null
recording_notice_ack_versionstring | null
whatsapp_lockedboolean

Dedicated to WhatsApp: it makes no outbound voice calls and cannot be the default line.

whatsapp_phone_number_idstring | null

The CRM WhatsApp line on this number (crm.lines.list), if any.

sort_ordernumber | null
created_by_idstring | null
created_atnumber
updated_atnumber

Errors

line_not_foundinvalid_inputunknown_fieldauthentication_requiredscope_insufficientmodule_access_deniedoperation_not_foundrate_limitedquota_exceeded

Example

curl "https://api.mb-suite.com/v1/phones/lines/{line_id}" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl "https://api.mb-suite.com/v1/phones/lines/{line_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"
POST/v1/phones/lines/{line_id}/rename

Rename a phone line

crm_phones.lines.rename

WriteIdempotentSince 2026-11-01

Sets the name people see for a phone line (friendly_name, 1 to 80 characters) in the dialer, the call log and the lists. Only the name changes: the number, its destination and its incoming-call settings stay. Idempotent. Returns the line. Requires edit access to Phones.

Scope
crm_phones:write
Permission
Edit in the module
MCP tool
crm_phones_lines_renameOn the full surface; on the compact one, mb_execute_operation with id: "crm_phones.lines.rename".

Declared cost: up to 1 reads and 1 writes per call (they count against the daily quota).

Parameters

line_idstringpathrequired

The phone line: an id from crm_phones.lines.list.

friendly_namestringbodyrequired

The name the app shows for the line (up to 80 characters).

Response

idstring
phone_numberstring
friendly_namestring | null
country_isostring
typestring

local, mobile, toll-free, national or international.

capabilitiesarray<string>

voice, sms, mms and/or fax.

statusstring

active, cancelling (release scheduled at cancel_at), suspended_unpaid, suspended, releasing or released.

destinationstring

The part of the product that uses the line: crm or support.

monthly_cost_usd_centsnumber

The monthly list price, in USD cents.

billing_modestring

Who pays it: own_subscription or parent_child_billing (the parent workspace).

purchased_atnumber | null
cancel_atnumber | null

With a release scheduled: when the number is released.

release_scheduled_atnumber | null
inbound_receiversarray<string>

The members who ring on an incoming call, all at once.

inbound_timeout_secnumber
voicemail_enabledboolean
voicemail_greetingstring | null
recording_enabledboolean
recording_enabled_atnumber | null
recording_notice_ack_versionstring | null
whatsapp_lockedboolean

Dedicated to WhatsApp: it makes no outbound voice calls and cannot be the default line.

whatsapp_phone_number_idstring | null

The CRM WhatsApp line on this number (crm.lines.list), if any.

sort_ordernumber | null
created_by_idstring | null
created_atnumber
updated_atnumber

Errors

line_not_foundinvalid_inputunknown_fieldauthentication_requiredscope_insufficientcrm_action_deniedidempotency_key_reusedrate_limitedquota_exceeded

Example

curl -X POST "https://api.mb-suite.com/v1/phones/lines/{line_id}/rename" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "friendly_name": "FRIENDLY_NAME"
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X POST "https://api.mb-suite.com/v1/phones/lines/{line_id}/rename" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "friendly_name": "FRIENDLY_NAME"
}'
POST/v1/phones/lines/{line_id}/destination

Move a phone line to another part of the product

crm_phones.lines.set_destination

WriteIdempotentSince 2026-11-01

Moves a phone line to another destination: crm (the CRM's dialer and inbox) or support. Every number is bought in the CRM and, once it is set up, moved where it is used; its calls and messages move with it (each inbox filters by line). Idempotent: moving it to the destination it already has changes nothing (changed=false). Returns from, to and changed. For a WhatsApp line use crm_phones.whatsapp_lines.set_destination. Requires edit access to Phones; moving a line into or out of a part of the product with restricted access also needs edit access to that part (403 module_access_denied) and, for a key, its write scope (403 scope_insufficient).

Scope
crm_phones:write
Permission
Edit in the module
MCP tool
crm_phones_lines_set_destinationOn the full surface; on the compact one, mb_execute_operation with id: "crm_phones.lines.set_destination".

Declared cost: up to 1 reads and 1 writes per call (they count against the daily quota).

Parameters

line_idstringpathrequired

The phone line: an id from crm_phones.lines.list.

destinationenumbodyrequired

The part of the product that uses the line: crm or support.

Values: crm, support

Response

line_idstring
fromstring
tostring
changedboolean

Errors

line_not_foundinvalid_inputunknown_fieldauthentication_requiredscope_insufficientcrm_action_deniedidempotency_key_reusedrate_limitedquota_exceeded

Example

curl -X POST "https://api.mb-suite.com/v1/phones/lines/{line_id}/destination" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "destination": "crm"
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X POST "https://api.mb-suite.com/v1/phones/lines/{line_id}/destination" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "destination": "crm"
}'
PATCH/v1/phones/lines/{line_id}/inbound

Configure how a line handles incoming calls

crm_phones.lines.configure_inbound

WriteIdempotentSince 2026-11-01

Sets how a phone line handles incoming calls: receivers, if sent, replaces the whole list of people (user ids, up to 10; an empty list rings nobody) who ring at the same time (to add one person use crm_phones.lines.add_receiver), each one with access to Phones (receiver_without_phones_access otherwise); inbound_timeout_sec how long it rings before voicemail (10 to 60); voicemail_enabled and voicemail_greeting (up to 200 characters; an empty greeting keeps the current one); recording_enabled records every call on the line. Turning recording on means the organization accepts the recording notice (the people on the call must be told it is recorded): send recording_notice_accepted=true or it fails with recording_notice_required; who accepted it and when are stored. Fields not sent stay as they are, the receivers included. Idempotent. Returns the line. Requires edit access to Phones.

Scope
crm_phones:write
Permission
Edit in the module
MCP tool
crm_phones_lines_configure_inboundOn the full surface; on the compact one, mb_execute_operation with id: "crm_phones.lines.configure_inbound".

Declared cost: up to 21 reads and 1 writes per call (they count against the daily quota).

Parameters

line_idstringpathrequired

The phone line: an id from crm_phones.lines.list.

receiversarray<string>bodyoptional

The people who ring at the same time (user ids, up to 10), replacing the whole list; an empty list rings nobody. Without it, the people who ring today stay.

inbound_timeout_secintegerbodyoptional

How many seconds it rings before voicemail (10 to 60).

voicemail_enabledbooleanbodyoptional

Whether an unanswered call goes to voicemail.

voicemail_greetingstringbodyoptional

The voicemail greeting read to the caller (up to 200 characters; empty keeps the current one).

recording_enabledbooleanbodyoptional

Record every call on the line (turning it on needs recording_notice_accepted).

recording_notice_acceptedbooleanbodyoptional

true accepts, for the organization, the recording notice (the people on the call must be told it is recorded).

Response

idstring
phone_numberstring
friendly_namestring | null
country_isostring
typestring

local, mobile, toll-free, national or international.

capabilitiesarray<string>

voice, sms, mms and/or fax.

statusstring

active, cancelling (release scheduled at cancel_at), suspended_unpaid, suspended, releasing or released.

destinationstring

The part of the product that uses the line: crm or support.

monthly_cost_usd_centsnumber

The monthly list price, in USD cents.

billing_modestring

Who pays it: own_subscription or parent_child_billing (the parent workspace).

purchased_atnumber | null
cancel_atnumber | null

With a release scheduled: when the number is released.

release_scheduled_atnumber | null
inbound_receiversarray<string>

The members who ring on an incoming call, all at once.

inbound_timeout_secnumber
voicemail_enabledboolean
voicemail_greetingstring | null
recording_enabledboolean
recording_enabled_atnumber | null
recording_notice_ack_versionstring | null
whatsapp_lockedboolean

Dedicated to WhatsApp: it makes no outbound voice calls and cannot be the default line.

whatsapp_phone_number_idstring | null

The CRM WhatsApp line on this number (crm.lines.list), if any.

sort_ordernumber | null
created_by_idstring | null
created_atnumber
updated_atnumber

Errors

line_not_foundinvalid_inputunknown_fieldauthentication_requiredscope_insufficientcrm_action_deniedidempotency_key_reusedrate_limitedquota_exceeded

Example

curl -X PATCH "https://api.mb-suite.com/v1/phones/lines/{line_id}/inbound" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X PATCH "https://api.mb-suite.com/v1/phones/lines/{line_id}/inbound" \
  -H "Authorization: Bearer $MB_TEST_KEY"
POST/v1/phones/lines/{line_id}/receivers

Add a person who rings on a line's incoming calls

crm_phones.lines.add_receiver

WriteIdempotentSince 2026-11-01

Adds one person (user_id) to the people who ring when a line gets a call. The person must be a direct member of the organization on the CRM team (receiver_not_in_crm_team) with access to Phones (receiver_without_phones_access): outside that group the browser phone is never registered and the call would never ring for them. A line rings at most 10 people (limit_reached, with details.resource line_receivers). Idempotent: if the person already rings, nothing changes (added=false). To remove people or change the ring timeout, voicemail or recording use crm_phones.lines.configure_inbound. Requires edit access to Phones.

Scope
crm_phones:write
Permission
Edit in the module
MCP tool
crm_phones_lines_add_receiverOn the full surface; on the compact one, mb_execute_operation with id: "crm_phones.lines.add_receiver".

Declared cost: up to 5 reads and 1 writes per call (they count against the daily quota).

Parameters

line_idstringpathrequired

The phone line: an id from crm_phones.lines.list.

user_idstringbodyrequired

A member: a user_id from crm.team.list (with access to Phones).

Response

lineobject
addedboolean

Errors

line_not_foundinvalid_inputunknown_fieldauthentication_requiredscope_insufficientcrm_action_deniedidempotency_key_reusedrate_limitedquota_exceeded

Example

curl -X POST "https://api.mb-suite.com/v1/phones/lines/{line_id}/receivers" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "user_id": "USER_ID"
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X POST "https://api.mb-suite.com/v1/phones/lines/{line_id}/receivers" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "user_id": "USER_ID"
}'