# RingLogix (NetSapiens/CPaaS) API Reference

White-label phone service provider (VoIPSimplicity backend). Docs at https://apidocs.ringlogix.com/ — public, no login required for browsing. Uses Redoc JS viewer.

## Base URL
```
https://api.ringlogix.com/pbx/v1/
```

## Authentication — OAuth2

**Endpoint:** `POST https://api.ringlogix.com/pbx/v1/oauth2/token/`

### Flow 1: Password grant (initial token)

```
POST /pbx/v1/oauth2/token/
Content-Type: application/x-www-form-urlencoded

grant_type=password
client_id=<from RingLogix>
client_secret=<from RingLogix>
username=<subscriber_login>
password=<subscriber_password>
```

### Flow 2: Refresh token

```
POST /pbx/v1/oauth2/token/
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
client_id=<from RingLogix>
client_secret=<from RingLogix>
refresh_token=<from prior auth>
```

### Success 200 Response

| Field | Type | Description |
|---|---|---|
| `access_token` | String | Bearer token |
| `expires_in` | Number | Seconds until expiry |
| `refresh_token` | String | For getting a new token |
| `domain` | String | Domain of the user |
| `scope` | String | Scope of access |
| `token_type` | String | Always "Bearer" |
| `legacy` | Boolean | In legacy API window? |
| `legacy_expires_days` | Number | Days remaining in legacy window |
| `recover` | Boolean | Was recovery email dispatched? |

**Important:** Client ID/Secret are obtained from RingLogix support — they are **separate** from PBX user credentials.

---

## Endpoint Catalog (42 sections, 238 endpoints)

All use POST. Routing via query string `?object=<object>&action=<action>`.

### Auth & Users

| Endpoint | Permission | Key Params |
|---|---|---|
| `?object=subscriber&action=count` | Reseller | `domain` (required) |
| `?object=subscriber&action=read` | Reseller | `domain`, `user`, `login`, `email`, `first_name`, `last_name`, `fields` |
| `?object=subscriber&action=list` | Basic User | `domain` |

### Device Provisioning

**`POST ?object=device&action=create`** — Permission: Reseller

| Param | Required | Description |
|---|---|---|
| `domain` | Yes | VoIPSimplicity domain |
| `device` | Yes | Name of the device |
| `user` | Yes | Owner (valid user extension) |
| `mac` | Yes | MAC address — hex only, 12 chars, no `:` or `-` |
| `model` | Yes | Phone model (query via Device/Model API) |

Also available: `count`, `read`, `update`, `delete` via the same object/action pattern.

### CDRs

| Endpoint | Description |
|---|---|
| `?object=cdr&action=read_by_domain` | Read CDRs by domain |
| `?object=cdr&action=read_by_user` | Read CDRs by user |
| `?object=cdr&action=read_by_group` | Read CDRs by group |
| `?object=cdr&action=report_by_domain` | Report CDRs by domain |
| `?object=cdr&action=read_by_id` | Read CDR by ID |

Also: CDR Export (create/read/download), CDR Schedule (create recurring exports), optimize/purge old CDRs.

### Call Control

| Section | Endpoints |
|---|---|
| Call | Count/Read/Report active calls, Answer, Disconnect, Make, Transfer, Park, Hold, Record, Playback |
| Call Queue | Create/Read/Update/Delete queues, Create queued calls |
| Call Queue Stats | Read queue stats |
| Call Center Stats | Agent log, DNIS stats, Queue stats, User stats |

### Phone Numbers & SMS

| Endpoint | Description |
|---|---|
| `?object=phone_number&action=count` | Count numbers in a dial plan |
| `?object=phone_number&action=read` | Read phone numbers |
| `?object=phone_number&action=update` | Update a phone number |
| `?object=sms_number&action=count` | Count SMS-capable numbers |
| `?object=sms_number&action=read` | Read SMS numbers |
| `?object=sms_number&action=update` | Update SMS number |

### Agents & Teams

| Section | Endpoints |
|---|---|
| Agent | Create/Count/Read/Update/Delete agents in a callqueue, Change status |
| Agent Log | Create/Read agent logs |
| Contact | Create/Count/Read/Update/Delete contacts |
| Department | Create/List departments |
| Presence | List presence in a domain |

### MAC Provisioning Endpoints

All POST to `https://api.ringlogix.com/pbx/v1/?object=mac&action=<action>`.

**Create:** `?object=mac&action=create` — Permission: OMP (Office Manager / Reseller / Super User)
| Param | Required | Description |
|---|---|---|
| `mac` | Yes | MAC hex only, 12 chars, no `-` `:` `.` |
| `domain` | Yes | Domain of new device |
| `model` | Yes | Phone model (query via Device_Model) |
| `transport` | No | NDP transport type |
| `server`, `last_pull`, `date_created` | No | Metadata |
| `device1..device8` | No | Device field references |
| `territory`, `notes` | No | Organization |
| `line1_ext..line2_ext` | No | Extension lines |
| `line1_enable..line8_enable` | No | Per-line enable flags |
| `line1_share..line8_share` | No | Line sharing |
| `overrides`, `dir_inc`, `presence` | No | NDP overrides |

Note: "Before using this module, the device should have already been instantiated."

**Read:** `?object=mac&action=read` — Permission: Reseller
| Param | Required | Description |
|---|---|---|
| `mac` | Yes | MAC to look up (hex, colons removed) |
| `extension` | Yes | Numerical string, searches lines with this extension |
| `checkExistance` | Yes | Boolean — check if MAC exists |

Response: mac, server, territory, dir_inc, presence, domain, model, device1-8, notes, line1-8_share, overrides, phone_ext, transport, fxs, sla, sidecar, resync, directory_support, user_agent, contact, registration_expires_time, registration_time

**Update/Delete/Count:** Same pattern via `?object=mac&action=update|delete|count`. Delete requires `mac` + `domain`. Count requires `domain` (optional: `territory`, `mac`, `mac_LIKE`, `model`).

**Device Model Query:** `?object=devicemodel&action=read` — Permission: Reseller — optional: `brand`, `model`, `portal_view`, `include_ndp_defs`, `ndp_syntax`

---

### Auto-Provisioning Flow (any phone, any source)

Phones from any vendor (retail, used, previous provider) work identically — MAC registration is the only per-phone step. The provisioning server URL is configured in the RingLogix portal UI, NOT via REST API.

1. **Factory reset** (used phones only) — wipe old provider config
2. **DHCP discovery** — phone boots, router serves DHCP options (156/66/160/43) pointing to provisioning server (configured once on your network gear)
3. **MAC registration** — `POST ?object=mac&action=create` with MAC + model
4. **Device linking** — `POST ?object=device&action=create` links MAC to subscriber extension
5. **Phone contacts NDP server** — RingLogix provisioning server matches MAC
6. **Config push** — Server pushes SIP credentials, extension, features. Phone auto-reboots configured
7. **Verify** — `POST ?object=subscriber&action=read` checks account_status: active

DHCP Options (set once per network):
| Option | For | What it sets |
|---|---|---|
| 156 | Yealink / Poly | Provisioning server URL |
| 66 | Generic SIP | TFTP server address |
| 160 | Grandstream | HTTP provisioning URL |
| 43 | Cisco | Cisco provisioning |

---

## Common Header Pattern

All API calls after auth:
```
Authorization: Bearer <access_token>
```

## Key Observations

- **Not RESTful** — single base URL with `?object=&action=` routing
- **All POST** — parameters in form body
- **Reseller permission** required for provisioning operations
- **Basic User permission** sufficient for `subscriber&action=list`
- **Client ID/Secret** from RingLogix support (separate from PBX creds)
- **Postman collection** available from the docs site for testing

## Automation Opportunities

1. **Auto-provisioning**: Customer order → create subscriber → register MAC → link device → phone auto-provisioned on boot
2. **MAC-based provisioning**: Customer plugs in any phone — register MAC via API, phone picks up config from DHCP + NDP
3. **Second-hand phone handling**: Factory reset + MAC registration + device link = same flow as new phones
4. **CDR export automation**: Scheduled CDR export for billing
5. **DID management**: Phone number inventory, assignment, porting
6. **Customer lookup**: Query subscriber details by name/extension/domain
7. **DHCP config**: Option 156/66/160/43 set on customer's router once (not per-phone)