# RingLogix CPaaS / NetSapiens API

White-label phone service provider (VoIPSimplicity backend). RingLogix white-labels **NetSapiens** as their CPaaS platform.

## Base URL & Docs

```
https://api.ringlogix.com/pbx/v1/
```

API docs: `https://apidocs.ringlogix.com/` (public, no login). 238 endpoints across 42 categories. Single POST endpoint with `?object=&action=` routing.

## Authentication — OAuth2

**Endpoint:** `POST .../oauth2/token/`

```bash
curl -X POST "https://api.ringlogix.com/pbx/v1/oauth2/token/" \
  -d "grant_type=password&client_id=$ID&client_secret=$SECRET&username=$USER&password=$PASS"
```

Success 200 returns: `access_token`, `refresh_token`, `domain`, `scope`, `token_type`.

## Critical distinctions (Jul 13, 2026)

### Reseller portal vs PBX domain vs email alias

| Layer | Example | Purpose |
|---|---|---|
| **Reseller portal login** | `itpropartner.simplelogin.net` | Manage customers, billing, support tickets |
| **PBX tenant domain** | `itpropartner.netsapiens.com` or similar | Where phone numbers, devices, subscribers live |
| **Email alias** | `gbrown@itpropartner.simplelogin.net` | SimpleLogin email forwarding — NOT a PBX domain |

The OAuth `username` parameter needs a **PBX subscriber login**, not the reseller portal login. The PBX domain is assigned by RingLogix and is usually a `netsapiens.com` subdomain. `itpropartner.simplelogin.net` is a SimpleLogin email alias — the API rejects it.

### OAuth scopes

| Scope | Access |
|---|---|
| Basic User | Single subscriber's own data |
| Office Manager | All subscribers in one domain |
| Reseller | **All domains under the account** |

One subscriber with Reseller scope can manage Forefront Wireless, VoIP Simplicity, and every customer domain through a single login.

## WebRTC

RingLogix (Jul 13, 2026): "Netsapiens doesn't offer a factory SDK, however it does support WebRTC so can use generic tools like **SIP.js** and **JsSIP**." No proprietary SDK.

## Auto-Provisioning Flow

1. Factory reset phone → DHCP discovery (Options 156/66/160/43)
2. MAC registration: `POST ?object=mac&action=create`
3. Device linking: `POST ?object=device&action=create`
4. Phone contacts NDP server → RingLogix pushes SIP config → phone auto-reboots

Provisioning server URL is set in RingLogix portal UI, NOT via API.

## Key endpoints

| Capability | Endpoint |
|---|---|
| List subscribers | `POST /?object=subscriber&action=read` |
| Count subscribers | `POST /?object=subscriber&action=count` |
| Create device | `POST /?object=device&action=create` (domain + MAC + model + user) |
| Read devices | `POST /?object=device&action=read` |
| Voicemail | `POST /?object=vmailnag&action=read/update/delete` |
| CDR | Export, schedule, purge available |

## Current state (Jul 13, 2026)

- Client ID `0-t1706-c284088-r284061` / Secret confirmed valid (OAuth endpoint returns 403, not 401)
- PBX subscriber `gbrown` rejected by API — likely not a PBX subscriber or wrong scope
- PBX domain unknown — `itpropartner.simplelogin.net` is NOT the PBX domain
- Support ticket open with RingLogix: asking for correct PBX domain, subscriber login, and Reseller scope assignment
