# RingLogix CPaaS API — Complete Object Catalog

**Base URL:** `https://api.ringlogix.com/pbx/v1/`
**Auth:** OAuth2 (password grant + refresh token)
**Pattern:** All requests POST with `?object=X&action=Y`
**Scopes:** Basic User (own data), Office Manager (domain), Reseller (all domains)

## For Customer Portal

### Customers & Users
| Object | Actions | Use |
|---|---|---|
| subscriber | create, read, update, count, list | Customer accounts, user management |
| contact | create, read, update, delete, count | Personal contact directories |
| presence | list | Online/offline status per domain |

### Phones & Devices
| Object | Actions | Use |
|---|---|---|
| device | create, read, update, delete, count | Phone provisioning, read by MAC |
| devicemodel | read | List supported devices for auto-provisioning |
| phonenumber | read, update, count | DID management |
| MAC | create, read, update, delete, count | Provision by MAC address |

### Calls & Messaging
| Object | Actions | Use |
|---|---|---|
| call | create (make), read, answer, disconnect, transfer, hold, unhold, record | Full call control |
| callqueue | create, read, update, delete | Call center queues |
| agent | create, read, update, delete, change_status | Agent provisioning |
| queued | read, update | Manage queued calls |
| message | create (send), read, delete | SMS/MMS |
| messagesession | read, update, accept, delete | Chat conversations |
| smsnumber | count, read, update | SMS-capable numbers |

### Voicemail & Recordings
| Object | Actions | Use |
|---|---|---|
| recording | create, read, update, delete | Call recording management |
| vmailnag | create, read, update, delete, count | Voicemail reminders (phone/SMS/email) |

### Meetings
| Object | Actions | Use |
|---|---|---|
| meeting | create, read, update, delete, count, log_event | Video conferencing (SnapHD) |

### Routing & IVR
| Object | Actions | Use |
|---|---|---|
| answerrule | create, read, update, delete, count, reorder | Call routing/forwarding |
| dialplan | read | Dial plan configuration |
| dialrule | create, read, update, delete, count | Dial plan rules |
| audio | create, read, update, delete, count, upload, play | IVR prompts, hold music |
| timeframe | create, read, update | Business hours |
| timerange | create, update | Time windows within timeframes |
| upload | create, upload_chunk, config | File upload staging for MMS/media |

### Billing & CDRs
| Object | Actions | Use |
|---|---|---|
| CDR2 | read (by domain/user/group/id), count, report, update, optimize, purge | Call detail records |
| cdrexport | create, read, update, delete, download | CDR export jobs |
| cdrschedule | create, read, update, delete, count | Scheduled CDR exports |

### Admin & Org
| Object | Actions | Use |
|---|---|---|
| department | create, list | Org structure |
| site | list, count, read (with billing) | Physical locations |
| quota | read | Domain limits |
| dashboard | create, read, update, delete, count, list, toggle_favorite, toggle_visibility | Analytics dashboards |
| chart | create, read, update, delete, count, list | Dashboard widgets |
| subscription | create, read, delete | Webhook event subscriptions |
| call_request | read, add (wake-up), delete | Wake-up call requests |

### Analytics
| Object | Actions | Use |
|---|---|---|
| callcenterstats | read (agent_log, dnis_stats, queue_stats, user_stats), send_email_report | Call center reporting |
| callqueuestats | read | Queue-level analytics |
| trace | export | SIP trace export |

### Not Yet Available
- RingOS API (billing data, agent commissioning) — currently unavailable, contact Success Manager for roadmap.

## OAuth2 Flow

```python
# Get token
import requests
r = requests.post("https://api.ringlogix.com/pbx/v1/oauth2/token/", data={
    "grant_type": "password",
    "client_id": CLIENT_ID,
    "client_secret": CLIENT_SECRET,
    "username": PBX_USER,
    "password": PBX_PASS
})
token = r.json()["access_token"]

# Use in requests
headers = {"Authorization": f"Bearer {token}"}
r = requests.post(
    "https://api.ringlogix.com/pbx/v1/?object=subscriber&action=read",
    headers=headers,
    data={"domain": "customer-domain.voipsimplicity.com", "user": "101"}
)
```

## Data Presentation in Emails

When sending structured summaries (registration lists, inventory, status reports) via email:

1. **HTML tables whenever possible** — zebra striping, green ✓ / red ✗ for status. Build manually, never via send-shonuff.py.
2. **Normalize names** — proper case (`.title()`). Never raw database casing.
3. **Simplify labels** — raw values → human-readable: "NASA Registration w/ Upgraded Photo/Video Package - $2,332.00" → "Photo/Video"
4. **Preview before sending** — user wants to format-correct before it goes to the team.
5. **Plain-text fallback:** Use consistent ASCII formatting with `|` separators and `=` borders.
6. **Summary at bottom:** Totals + "OUTSTANDING" list for action items.

## Business Email Pattern (non-Sho'Nuff)

When sending from business addresses (contact@apex, info@voipsimplicity, etc.):
- Clean HTML tables with alternating row colors (#fff / #f9f9f9)
- Green checkmark: `<span style="background:#22c55e;color:#fff;border-radius:4px;">✓</span>`
- Red X mark: `<span style="color:#dc2626;font-weight:bold;">✗</span>`
- NO Sho'Nuff signature badge or red divider
- Plain professional sign-off
- SMTP via the appropriate relay (not Core's relay for Apex/SiteGround-hosted domains)