Phone numbers API

List the numbers you own and change how they are configured.

Method	Path	Scope
GET	/phone-numbers	phone-numbers:read
GET	/phone-numbers/{id}	phone-numbers:read
PATCH	/phone-numbers/{id}	phone-numbers:write

List your numbers

curl https://app.limecall.com/api/v1/phone-numbers \
  -H "Authorization: Bearer sk_live_..."

Pass ?userId=... to return only the numbers assigned to one user.

Each number reports its capabilities. Check these before sending — not every number can text, and a from on a voice-only number fails at send time rather than at configuration time.

Update a number

Three fields are accepted. Sending none of them returns 400.

Field	Rules
forwardingNumber	E.164 only — + then 7–15 digits, e.g. [phone]. Anything else returns 400. null turns forwarding off.
voicemailEnabled	Boolean. A non-boolean returns 400.
friendlyName	String, trimmed, truncated to 120 characters. null clears it.

curl -X PATCH https://app.limecall.com/api/v1/phone-numbers/77 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"forwardingNumber":"[phone]","friendlyName":"Google Ads — Leeds"}'

Returns the updated number.

What setting a forwarding number does

Setting forwardingNumber routes the line to an external number, and clears any team or team-member destination on it. One line cannot hold three contradictory targets, so the other two are removed rather than left stale.

What clearing it does not do

Sending "forwardingNumber": null stops forwarding to that number. It does not hand the line to your AI receptionist — that is a much bigger change than the request asked for, and it is deliberately not implied.

If you want the AI to answer the line, set that destination explicitly in the dashboard. See Call forwarding & routing.

A legacy alias

callForwarding is still accepted, as a string, as { target, enabled }, or as null, and lands on the same columns. Prefer forwardingNumber in new code.

What this endpoint will not do

Buying and porting are not in the API. Both involve payment and, in most countries, regulatory documents, so they are dashboard-only. See Buy a number and Bring your number.

Releasing a number is likewise dashboard-only — it is irreversible and deliberately not one API call away.