---
title: phone.useNumber | Doing Work API
description: Use one number from the shop's Twilio account for the shop's texts and calls. Doing Work saves where it pointed before and puts that back on disconnect. Ca
url: https://doingwork.work/docs/reference/phone-usenumber/
---

# phone.useNumber

Use one number from the shop's Twilio account for the shop's texts and calls. Doing Work saves where it pointed before and puts that back on disconnect. Calls ring forward_to (with the shop number as caller ID) and go to voicemail by email after ring_seconds. If Doing Work is down, Twilio rings forward_to directly. Owner only.

|  |  |
|---|---|
| Who | Agents can call this |
| REST | `POST /v1/phone/use-number` |
| MCP tool | `phone_useNumber` |
| Writes | yes, send an Idempotency-Key |
| Area | [Shop](https://doingwork.work/docs/reference/#shop) |

## When to use it

Use one number from the shop's Twilio account for the shop's texts and calls. Doing Work saves where it pointed before and puts that back on disconnect.

## What to tell the owner

Say what you did in plain words and what happens next.

## Input

| Field | Type | Required |
|---|---|---|
| `shop_id` | string (uuid) | yes |
| `phone` | string | yes |
| `forward_to` | string | yes |
| `ring_seconds` | integer | no |
| `voicemail_email` | string (email) | no |

## Example

```http
POST https://doingwork.work/v1/phone/use-number
content-type: application/json
Idempotency-Key: 3f1c...

{
  "shop_id": "00000000-0000-4000-8000-000000000000",
  "phone": "...",
  "forward_to": "..."
}
```

## Output

JSON. The response shape isn't published yet; read the fields you need and ignore the rest. Errors are `{code, message, status}`.

## Errors

| Code | Status | What to do |
|---|---|---|
| `invalid_input`, `invalid_token`, `rate_limited` |  | Can happen on any call. See [errors](https://doingwork.work/docs/errors/). |