> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notifique.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Manage workspace phone numbers via API, query, search available, and configure inbound voice.

## In short

* **Purchasing** a number is in the **dashboard**; the API lists, queries available, and configures **inbound voice**.
* Scopes: `phone_numbers:read` (query) and `phone_numbers:update` (configure). Details in **[API Key scopes](/en/phone-numbers-api/como-funciona/escopos-da-api-key)**.
* Use `id` or `phoneE164` as origin on calls, see **[Voice API Quick Start](/en/voice-api/como-funciona/quick-start)**.

For those **integrating** number management (CRM, telephony). Purchase and payment stay in the dashboard.

***

## Before you start

* **Active number** purchased under **Settings → Phone numbers**.
* **API Key** with required scopes. See [Scopes](/en/phone-numbers-api/como-funciona/escopos-da-api-key).
* Authentication: `Authorization: Bearer sk_live_...` or `x-api-key`.
* **Base URL** (e.g. `https://api.notifique.dev`).

***

## The path in three steps

1. **Purchase** in the dashboard (search, reserve, payment).
2. **List** numbers and copy **`id`** or **`phoneE164`**.
3. **Configure** what happens when someone **calls** (forward, TTS, webhook…).

***

## 1. Purchase a number (dashboard)

**Settings → Phone numbers:**

1. Search by country, area code, or pattern.
2. Select and pay (recurring monthly fee).
3. Activation → webhook **`phone_number.activated`** (if configured).

The API searches **available** numbers; **purchase** is via dashboard.

***

## 2. Search available numbers

Lists options before sending the user to dashboard checkout.

**Request**

```http theme={null}
GET /v1/phone-numbers/available?countryCode=BR&areaCode=11
Authorization: Bearer sk_live_xxxxx
```

Optional parameters:

| Parameter         | Description                    |
| ----------------- | ------------------------------ |
| `countryCode`     | ISO (default `US`)             |
| `phoneNumberType` | e.g. `local`, `mobile`         |
| `areaCode`        | Area code                      |
| `contains`        | Digits the number must contain |

**Response (200), example**

```json theme={null}
{
  "success": true,
  "data": [
    {
      "phoneE164": "+5511987654321",
      "countryCode": "BR",
      "phoneNumberType": "local",
      "features": ["voice", "sms"],
      "region": "SP",
      "locality": "São Paulo",
      "monthlyPriceBrlCents": 2990
    }
  ]
}
```

***

## 3. List workspace numbers

**Request**

```http theme={null}
GET /v1/phone-numbers
Authorization: Bearer sk_live_xxxxx
```

Returns **non-released** numbers (`RELEASED` does not appear).

**Response (200), example**

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "clxx_phone_1",
      "workspaceId": "clxx_ws",
      "phoneE164": "+5511987654321",
      "countryCode": "BR",
      "phoneNumberType": "local",
      "features": ["voice", "sms"],
      "status": "ACTIVE",
      "monthlyPriceBrlCents": 2990,
      "renewsAt": "2026-07-11T00:00:00.000Z",
      "label": "Atendimento SP",
      "inboundVoiceAction": "WEBHOOK_CONTROL",
      "forwardToE164": null,
      "inboundTtsText": null,
      "inboundTtsVoice": null,
      "recordingEnabled": false,
      "createdAt": "2026-06-11T12:00:00.000Z",
      "updatedAt": "2026-06-11T12:00:00.000Z"
    }
  ]
}
```

***

## 4. Get a number

**Request**

```http theme={null}
GET /v1/phone-numbers/clxx_phone_1
Authorization: Bearer sk_live_xxxxx
```

***

## 5. Configure inbound voice

Defines what happens when someone **calls**, like choosing whether the call goes to reception, voicemail, or your system.

**Request**

```http theme={null}
PATCH /v1/phone-numbers/clxx_phone_1
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx
```

```json theme={null}
{
  "label": "Suporte comercial",
  "inboundVoiceAction": "FORWARD",
  "forwardToE164": "+5511999887766",
  "recordingEnabled": true
}
```

### `inboundVoiceAction` values

| Value             | Behavior                                           |
| ----------------- | -------------------------------------------------- |
| `WEBHOOK_CONTROL` | Your app controls via Voice API webhooks (default) |
| `FORWARD`         | Forwards to `forwardToE164`                        |
| `TTS_HANGUP`      | Speaks `inboundTtsText` and hangs up               |
| `REJECT`          | Rejects                                            |
| `VOICEMAIL`       | Records message                                    |

TTS: `inboundTtsText` + optional `inboundTtsVoice` (`female-natural`, `male-natural`, etc.).

***

## 6. Lifecycle webhooks

Events: **`phone_number.activated`**, **`phone_number.past_due`**, **`phone_number.suspended`**, **`phone_number.released`**.

Details: [**Webhook events**](/en/voice-api/como-funciona/eventos-do-webhooks).

***

## Quick summary

| Goal              | Path                                          |
| ----------------- | --------------------------------------------- |
| Search available  | `GET /v1/phone-numbers/available`             |
| List purchased    | `GET /v1/phone-numbers`                       |
| Detail            | `GET /v1/phone-numbers/:id`                   |
| Configure inbound | `PATCH /v1/phone-numbers/:id`                 |
| Call origin       | `id` or `phoneE164` in `POST /v1/voice/calls` |

***

## Next steps

* **[API Key scopes](/en/phone-numbers-api/como-funciona/escopos-da-api-key)**
* **[Voice API, Quick Start](/en/voice-api/como-funciona/quick-start)**
* **[Webhook events](/en/voice-api/como-funciona/eventos-do-webhooks)**
* **[API Keys](/en/guides/api-key/index)**