ICTPBX REST API Reference

Developer Reference

ICTPBX REST API

A section-wise reference for the ICTCore REST API that powers ICTPBX. Every screen in the portal is backed by these endpoints, and the same API is open for integrations, automation, and custom clients.

🔑 Authentication⚙️ Conventions🛠️ Administration📡 Routing📞 PBX📠 Fax📊 Reporting💳 Billing

🔑 Authentication
Obtain and use a Bearer JWT

Authenticate once to obtain a signed JWT, then send it as a Bearer token on every subsequent request. The token payload carries the user identity, tenant, permissions, and (Enterprise) credit balance. It is signed RS256 and validated server-side, so never modify it.

POST /authenticate
Content-Type: application/json

{ "username": "admin@ictcore.org", "password": "helloAdmin" }

Authorization: Bearer <jwt>

Sessions & password

Multi-factor (TOTP)

⚙️ Conventions
Shapes, identifiers, headers, errors, scoping

3.1 Standard REST shape

Most resources follow the same pattern (shown here for tenants):

3.2 Identifiers

Core resources (tenant, user, provider, route, account, document…) use numeric IDs. PBX resources (extensions, devices, ring groups, IVR menus, voicemail, conferences, etc.) use UUIDs ($..._uuid).

3.3 Headers

Authorization: Bearer <jwt>
Content-Type: application/json
Accept: application/json

3.4 Error format

Errors return an HTTP status and a JSON envelope:

{ "error": { "code": 404, "message": "Document media not found" } }

Common codes: 401 invalid/expired token, 403 not permitted (wrong role/permission), 404 not found, 409 conflict (e.g. extension already in use), 423/429 login lockout.

3.5 Permission scoping

• Admin sees and manages all tenants.
• Tenant admin is scoped to their own tenant; list endpoints auto-filter by tenant.
• End users are limited to their own objects (My Account, own fax, own quota).
• PBX write operations (create/update/delete) require an admin or tenant-admin role.

3.6 CSV export / import

Many list resources offer companion CSV routes, e.g. GET /cdr/csv, GET /routes/csv, GET /groups/$group_id/csv, POST /contact_dncs/import/csv.

🛠️ Administration
Tenants, users, roles, branding

4.1 Tenants (Enterprise)

4.2 Users

4.3 Roles & permissions

4.4 Branding (Enterprise) & system settings

📡 Routing & Trunks
Providers, routes, DIDs, gateways

📞 PBX
Extensions, devices, call handling, realtime

6.1 Extensions

6.2 Devices & auto-provisioning

6.3 Call-handling modules

6.4 Realtime monitoring & call control

POST /call/originate
{ "from": "1001", "to": "1002" }

📠 Fax & Messaging
Send, campaigns, documents, contacts, accounts

7.1 Sending faxes (programs → transmissions)

7.2 Campaigns (bulk fax)

7.3 Documents, media & received faxes

7.4 Contacts, groups & DNC

7.5 Recordings & templates (the /messages namespace)

7.6 Fax accounts

📊 CDR & Reporting
Call records, spools, statistics

💳 Billing
Quota, packages, subscriptions, payments (Enterprise)

🗂️ Reference Data
Countries, regions, timezones, services

💻 Worked Examples
Copy-paste curl recipes

Log in and store the token

TOKEN=$(curl -s -X POST https://demo.ictpbx.com/api/authenticate \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin@ictcore.org","password":"helloAdmin"}' \
  | sed -E 's/.*"token":"([^"]+)".*/\1/')

List resources

curl -s https://demo.ictpbx.com/api/tenants \
  -H "Authorization: Bearer $TOKEN" -H 'Accept: application/json'

Create an extension

curl -s -X POST https://demo.ictpbx.com/api/fpbx_extensions \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"extension":"1005","password":"S3cret!","display_name":"Reception"}'

Update a tenant’s fraud limit

curl -s -X PUT https://demo.ictpbx.com/api/tenants/85 \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"max_concurrent_calls":10,"credit_alert_threshold":5}'

Click-to-Call

curl -s -X POST https://demo.ictpbx.com/api/call/originate \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"from":"1001","to":"1002"}'

Delete a device

curl -s -X DELETE https://demo.ictpbx.com/api/devices/<device_uuid> \
  -H "Authorization: Bearer $TOKEN"

📦 Edition Notes
Community vs Enterprise

• Community Edition does not expose the Billing section. Calls to those endpoints are gated and return empty / forbidden results.
• CE is single-tenant: tenant-management endpoints exist but the system operates with one organisation.
• All other sections (Authentication, Administration basics, Routing, PBX, Fax, CDR, Reference) are identical across editions.