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
Log in for a JWT, or use an API key

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 credit balance (Service Provider Edition). It is signed RS256 and validated server-side, so never modify it.

You can use an API key instead of a JWT. Create one under Administration → API Keys and send it in the X-API-Key header. A key acts with the permissions of the user it belongs to. It’s rate-limited, so you’ll get a 429 if you go over the limit, and you can’t use a key to create other keys.

POST /authenticate
Content-Type: application/json

{ "username": "admin@example.com", "password": "<your password>" }

Authorization: Bearer <jwt>

# or, with an API key:
X-API-Key: <your key>

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>      # or X-API-Key: <your key>
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 (Service Provider Edition)

4.2 Users

4.3 Roles & permissions

4.4 Branding (Service Provider Edition) & system settings

📡 Routing & Trunks
Trunks (providers), routes and DIDs

📞 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_ext": "1001", "to_number": "+12015550123" }

# response
{ "status": "queued", "job_uuid": "..." }

Extension 1001 rings first. When it answers, ICTPBX places the call to to_number. The API answers straight away with a job_uuid. If from_ext isn’t registered right now, you’ll get a 409 instead.

📠 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 Accounts

There’s no Fax Accounts menu any more. A fax line is an extension with its Extension Type set to Fax, so you create it through /fpbx_extensions. The routes below work on the account records ICTCore keeps behind the scenes, such as DIDs.

📊 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@example.com","password":"<your password>"}' \
  | 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_ext":"1001","to_number":"+12015550123"}'

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.