hermes-skills/skills/devops/hermes-browser-setup/references/ringlogix-api.md

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)