> ## 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.

# SMS

> Session-authenticated SMS number, review-request, consent, and delivery status endpoints.

SMS endpoints are dashboard endpoints. They use the signed-in app session, not `X-NearIQ-Key`. SMS actions require a Growth plan or higher, available monthly SMS allowance, and proper customer consent before sending messages.

<Warning>
  Only message customers who have given consent. Keep opt-out handling available in every workflow that collects SMS contacts.
</Warning>

## GET /api/sms

Returns SMS configuration status and the active business SMS number.

<RequestExample>
  ```bash cURL theme={null}
  curl "https://app.neariq.io/api/sms" \
    -H "Cookie: <dashboard session cookie>"
  ```
</RequestExample>

```json theme={null}
{
  "configured": true,
  "business": {
    "id": "5d49faca-17f3-45f6-a0ef-60bd93754771",
    "name": "Aster Grove Fitness",
    "smsNumber": "+15551234567",
    "smsEnabled": true
  }
}
```

To search available numbers, use `action=search`.

```bash theme={null}
curl "https://app.neariq.io/api/sms?action=search&areaCode=512" \
  -H "Cookie: <dashboard session cookie>"
```

```json theme={null}
{
  "configured": true,
  "numbers": [
    {
      "number": "+15125550123",
      "friendlyName": "(512) 555-0123",
      "locality": "Austin",
      "region": "TX"
    }
  ]
}
```

## POST /api/sms

Runs one SMS action: provision a number, send a review request, or release the active number.

### Provision a number

```bash theme={null}
curl -X POST "https://app.neariq.io/api/sms" \
  -H "Content-Type: application/json" \
  -H "Cookie: <dashboard session cookie>" \
  -d '{ "action": "provision", "phoneNumber": "+15125550123" }'
```

```json theme={null}
{
  "ok": true,
  "number": "+15125550123",
  "sid": "PN123"
}
```

### Send a review request

```bash theme={null}
curl -X POST "https://app.neariq.io/api/sms" \
  -H "Content-Type: application/json" \
  -H "Cookie: <dashboard session cookie>" \
  -d '{
    "action": "send_review_request",
    "to": "+15557654321",
    "customerName": "Jane"
  }'
```

```json theme={null}
{
  "ok": true,
  "messageSid": "SM123",
  "status": "queued"
}
```

### Release a number

```bash theme={null}
curl -X POST "https://app.neariq.io/api/sms" \
  -H "Content-Type: application/json" \
  -H "Cookie: <dashboard session cookie>" \
  -d '{ "action": "release" }'
```

```json theme={null}
{
  "ok": true
}
```

## SMS consent

Consent contacts are managed through dashboard business endpoints. SMS consent rows track phone number, consent source, consent timestamp, and opt-out state so review requests, reminders, and conversations can respect customer preferences.

## Errors

| Status | Meaning                                                     |
| ------ | ----------------------------------------------------------- |
| `400`  | Missing action fields, no SMS number, or duplicate number   |
| `401`  | Missing dashboard session                                   |
| `403`  | Plan does not include SMS or monthly allowance is exhausted |
| `404`  | No active business found                                    |
| `409`  | Business already has an SMS number                          |
| `503`  | SMS is not configured                                       |