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

# Voice and Phone Numbers

> Business phone numbers, call forwarding, call logs, voicemail, and provider webhooks.

These are dashboard-session endpoints for NearIQ business communication features. They use the signed-in app session, active business scoping, and plan limits. Provider webhooks are server-to-server endpoints and validate the provider signature.

<Warning>
  Call recording and voicemail storage may require consent notices depending on the caller location. Keep customer-facing disclosure and retention settings aligned with your legal requirements.
</Warning>

## Phone Numbers

`GET /api/phone-numbers` lists active business phone numbers. Add `search=1` with `country`, `type`, `areaCode`, `contains`, `locality`, `region`, `smsEnabled`, `voiceEnabled`, `mmsEnabled`, and `limit` (up to 50) to search available numbers.

`POST /api/phone-numbers` provisions a number and configures SMS plus voice webhooks.

`PATCH /api/phone-numbers` updates a provisioned number label or promotes it to the primary outbound sender.

`DELETE /api/phone-numbers?id=<uuid>` releases a number and soft-disables it in NearIQ.

```json theme={null}
{
  "phoneNumber": "+15551234567",
  "type": "local",
  "friendlyName": "Austin front desk",
  "setPrimary": true
}
```

```json theme={null}
{
  "id": "00000000-0000-4000-8000-000000000000",
  "friendlyName": "Austin front desk",
  "setPrimary": true
}
```

## Call Forwarding

`GET /api/call-forwarding` lists forwarding rules for the active business.

`POST /api/call-forwarding` creates a rule. `PUT /api/call-forwarding` updates a rule. `DELETE /api/call-forwarding?id=<uuid>` deletes a rule.

```json theme={null}
{
  "phoneNumberId": "00000000-0000-4000-8000-000000000000",
  "forwardTo": "+15557654321",
  "label": "Manager",
  "ringTimeoutSeconds": 25,
  "priority": 0,
  "enabled": true,
  "schedule": {
    "days": ["mon", "tue", "wed", "thu", "fri"],
    "startHour": 9,
    "endHour": 17
  }
}
```

## Call Logs

`GET /api/call-logs` returns recent calls for the active business. Optional filters: `direction`, `status`, `from`, `to`, and `limit`.

Rows include `recordingPlaybackUrl` when an authenticated recording proxy is available.

## Voicemails

`GET /api/voicemails` returns voicemail rows with transcription text when available and an authenticated `recordingPlaybackUrl`.

`PATCH /api/voicemails` marks a voicemail read or unread.

`DELETE /api/voicemails?id=<uuid>` deletes a voicemail row.

```json theme={null}
{
  "id": "00000000-0000-4000-8000-000000000000",
  "isRead": true
}
```

## Voice Webhooks

`POST /api/voice/incoming` receives inbound calls, logs the call, dials active forwarding rules, and falls back to voicemail recording when no forwarding rule is available.

`POST /api/voice/status` receives call status callbacks and updates `call_logs`, including voice minute usage for completed calls.

`POST /api/voice/recording` receives recording callbacks and stores call recording or voicemail metadata.

`GET /api/voice/recording?callLogId=<uuid>` or `GET /api/voice/recording?voicemailId=<uuid>` proxies recording playback for authenticated users without exposing provider recording URLs.

## Errors

| Status | Meaning                                                        |
| ------ | -------------------------------------------------------------- |
| `400`  | Invalid phone number, rule, query, or request body             |
| `401`  | Missing dashboard session                                      |
| `403`  | Plan does not include the requested communication feature      |
| `404`  | Business, phone number, call log, rule, or voicemail not found |
| `502`  | Phone provider request failed                                  |
| `503`  | Phone provider is not configured                               |