comms.list_phone_numbers

List the shop's phone numbers — which one calls, which one messages

Read-onlyRead budget

REST

Shipping

POST /api/v1/comms/list_phone_numbers

MCP tool

Live

comms.list_phone_numbers

Exposed on: REST API · Shop MCP server · Claude connector · Dash (in-app copilot) · Zapier. Part of the Comms domain.

Operating contract

Every number this shop still holds, its own primary line first. Released numbers are not returned, and an abandoned purchase that never reached the carrier is filtered out on the read rather than shown as a line the shop can use.

is_primary IS THE ONE THAT MATTERS. It is the number automations, click-to-call and every outbound text use when nothing names a line, so it is the number a customer sees. is_sending says whether the line's status actually permits a send — a suspended line (billing lapsed) is still held and still listed and cannot send a thing.

status is the line's own state, not a capability list: active can send, pending is a reservation that was never bought, suspended is on hold, released is gone and never appears here. Only active sends, and that is deliberate — letting a reservation send meant every text failed at the carrier with nothing on our side to explain it.

The shop's TEXTING identity can also be a messaging service rather than a single line, in which case messaging_service is set and the individual numbers below it still list normally.

TRUNCATION: total is how many numbers the shop holds and omitted how many are not in this response. A shop holds a handful, so omitted is almost always 0 — but read it, because a multi-location shop with a line per bay is the case where it is not.

Who may call it

Permission: inbox.accessThe caller must hold Inbox at the ACT level. A read-only dashboard grant on the same section is refused.
Plan: Every planNo plan gate. Available on every Service VIN plan.
Retries: naturalNaturally idempotent — running it twice leaves the same world as running it once. A retrying integration needs no key.
Rate class: readCounted against the read budget — the widest of the four.

Partial answers

omitted is how many matching records are not in the response, and 0 is a real answer meaning you have all of them. There is no cursor here — narrow the filter instead.

Do not summarise from a truncated response

When `omitted` is not 0 this shop holds more numbers than were returned. Raise `limit` (up to 100) — the list is short and does not page.

Input

Field	Type	Description
limit	integer1–100	How many numbers to return, 1-100. Defaults to 50. Default: `50`

Output

Field	Type	Description
items	object[]	—
items[].id	string	—
items[].number	string	—
items[].name	string \| null	—
items[].provider	string	—
items[].status	string	—
items[].country	string \| null	—
items[].is_primary	boolean	—
items[].is_sending	boolean	—
items[].purchased_at	string \| null	—
messaging_service	string \| null	—
total	number	—
omitted	number	—

Examples

Built from this capability's own schema — required fields and the ones carrying a default, and nothing invented. Paste one and it validates.

curl

export SERVICEVIN_API_KEY=svk_live_…

curl -X POST https://www.servicevin.com/api/v1/comms/list_phone_numbers \
  -H "Authorization: Bearer $SERVICEVIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit":50}'

TypeScript (fetch)

const res = await fetch("https://www.servicevin.com/api/v1/comms/list_phone_numbers", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SERVICEVIN_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "limit": 50
  }),
});

// Success and failure are both envelopes. Switch on error.code, never
// on error.message — the codes are stable, the messages are for people.
const payload = await res.json();
if (!res.ok) throw new Error(payload.error.code);
const data = payload.data;

Python (requests)

import os, requests

res = requests.post(
    "https://www.servicevin.com/api/v1/comms/list_phone_numbers",
    headers={"Authorization": f"Bearer {os.environ['SERVICEVIN_API_KEY']}"},
    json={
    "limit": 50
},
    timeout=30,
)
payload = res.json()
if not res.ok:
    raise RuntimeError(payload["error"]["code"])
data = payload["data"]

MCP tools/call — https://www.servicevin.com/api/mcp

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "comms.list_phone_numbers",
    "arguments": {
      "limit": 50
    }
  }
}

Refusals

The four gates run in this order on every surface, and the order is not arbitrary — see Authentication.

Status	Code	When
404	`not_found`	The id is unknown, or the feature is not enabled for this account. Deliberately the same answer for both.
403	`forbidden`	This login does not hold inbox.access.
422	`validation_error`	An argument was wrong. The message names the field.
429	`rate_limited`	Too many read calls. Back off and retry.
500	`internal_error`	Something failed on our side. Nothing was changed.

Operating contract#

Who may call it#

Partial answers#

Input#

Output#

Examples#

Refusals#