# Buy a phone number

Provision one number the search offered onto the workspace's carrier account and record it as a line the workspace holds. It then becomes selectable as the sending number. This costs the workspace money every month.

Access class: `workspace:admin`.

## Endpoint

`POST /v1/comms/numbers`

## Request body

Content type: `application/json`.

```json
{
  "body": {
    "phone": "string"
  },
  "params": {},
  "query": {}
}
```

## Responses

### 201

the action's answer

Content type: `application/json`.

```json
{
  "number": {
    "boughtAt": "string",
    "e164": "string",
    "id": "",
    "label": "string",
    "managed": true,
    "mmsCapable": true,
    "provider": "string",
    "providerSid": "string",
    "releasedAt": "string",
    "sender": true,
    "smsCapable": true,
    "status": "string",
    "voiceCapable": true
  }
}
```

### default

a refusal: `{"error": "<what a person needs to read>"}`. 401 no credential, 402 the plan does not include this, 403 the seat does not, 404 the thing does not exist or is not yours to see.

Content type: `application/json`.

```json
{
  "error": "string"
}
```