External API Integration Guide

This guide provides technical reference and documentation for integrating external platforms (like CRMs, ERPs, billing systems, and custom tools) with the Ring2All Platform API.

Ring2All exposes a secure REST API allowing you to manage extensions, hot desking, conferences, queues, agents, trunks, monitor active calls, download Call Detail Records (CDRs), and send SMS messages.

🔐 Authentication

All API requests must be sent over HTTPS. The Ring2All API supports two authentication mechanisms:

1. API Key (Recommended for Machine-to-Machine integrations)

For backend integrations, authentication via the X-API-Key header is the preferred method as keys do not expire unless manually revoked.

Include the API Key in the headers of every request:

Http

X-API-Key: ak_your_api_key_here

Note: The API key automatically scopes the request to the correct tenant context.

2. JWT Bearer (For session/user-specific calls)

To authenticate on behalf of a specific user:

Call the login endpoint to fetch a token:

POST /api/auth/login

Include the token in the Authorization header:

Http

   Authorization: Bearer <your_jwt_token_here>

📈 Base URL and Response Format

All requests target the following base structure:

https:///api

Success Response Format

Json

{
  "success": true,
  "data": { ... },
  "meta": {
    "page": 1,
    "limit": 25,
    "total": 100
  }
}

Error Response Format

Json

{
  "success": false,
  "error": "ERROR_CODE",
  "message": "Human readable error description",
  "details": { ... }
}

📁 Creation & Provisioning Endpoints Reference

Below are the HTTP specifications for creating items across the main Ring2All modules. Each creation endpoint has corresponding GET (list/retrieve), PUT (update), and DELETE routes.

1. PBX Extensions

`POST /telephony/extensions`

Provision a new SIP or virtual extension.

Request Body Schema:

Json

  {
    "extension": "1005",
    "enabled": true,
    "type": "user",
    "maxCalls": 5,
    "portalEnabled": true,
    "portalUser": "user1005",
    "portalPassword": "SecurePortalPassword123!",
    "voicemailEnabled": true,
    "devices": [
      {
        "username": "1005",
        "password": "SecureSipPassword456!",
        "type": "softphone",
        "enabled": true,
        "description": "Primary Softphone"
      }
    ],
    "voicemail": {
      "password": "1005",
      "email": "user1005@acme.com",
      "notificationEnabled": true,
      "attachFile": true,
      "deleteAfterEmail": false
    },
    "settings": [
      { "name": "effective_caller_id_name", "value": "Jane Smith" },
      { "name": "effective_caller_id_number", "value": "1005" },
      { "name": "outbound_caller_id_name", "value": "ACME Corp" },
      { "name": "outbound_caller_id_number", "value": "+15551001005" }
    ]
  }

2. Hot Desking

`POST /telephony/hot-desking`

Request Body Schema:

Json

  {
    "name": "Lobby Phone",
    "macAddress": "00:1A:2B:3C:4D:5E",
    "dialplan": "default",
    "enabled": true,
    "description": "Lobby registration endpoint"
  }

3. Call Center (Queues & Agents)

`POST /telephony/queues`

Create an inbound call distribution queue.

Request Body Schema:

Json

  {
    "name": "Customer Support Queue",
    "extension": "9005",
    "strategy": "longest-idle-agent",
    "maxWaitTime": 300,
    "recordCalls": true,
    "enabled": true,
    "tiers": [
      { "agentId": 1, "level": 1, "position": 1 }
    ]
  }

Available Strategies: ring-all, longest-idle-agent, round-robin, top-down, random.

`POST /telephony/agents`

Request Body Schema:

Json

  {
    "extension": "1005",
    "status": "Available",
    "ready": true,
    "enabled": true
  }

4. PBX Applications

`POST /telephony/ring-groups`

Create a ring group to ring multiple extensions simultaneously or in sequence.

Request Body Schema:

Json

  {
    "name": "Sales Team",
    "extension": "6001",
    "strategy": "simultaneous",
    "ringTime": 30,
    "enabled": true,
    "members": [
      { "extensionId": 1, "delay": 0 },
      { "extensionId": 2, "delay": 10 }
    ]
  }

`POST /telephony/ivrs`

Provision an Interactive Voice Response (IVR) Auto-Attendant menu.

Request Body Schema:

Json

  {
    "name": "Main Menu",
    "extension": "5000",
    "greetingType": "tts",
    "greetingMessage": "Welcome. Press 1 for Sales, or 2 for Support.",
    "timeout": 5,
    "enabled": true,
    "options": [
      { "digit": "1", "destinationType": "ring_group", "destination": "6001" },
      { "digit": "2", "destinationType": "queue", "destination": "9005" }
    ]
  }

`POST /telephony/conferences`

Create an audio conference bridge.

Request Body Schema:

Json

  {
    "name": "Board Meeting",
    "extension": "8500",
    "moderatorPin": "4321",
    "participantPin": "8765",
    "maxMembers": 25,
    "recordEnabled": true,
    "enabled": true
  }

`POST /telephony/announcements`

Create a system announcement/greeting playing pre-recorded audio or Text-to-Speech.

Request Body Schema:

Json

  {
    "name": "Holiday Welcome Greeting",
    "type": "tts",
    "message": "Thank you for calling. Our offices are currently closed for the holiday.",
    "enabled": true
  }

5. Calls Routing & Trunks

`POST /telephony/gateways`

Provision an external SIP gateway/trunk connecting to a carrier.

Request Body Schema:

Json

  {
    "name": "SIP Carrier",
    "proxy": "sip.carrier.com",
    "username": "carrier_username",
    "password": "carrier_secure_password",
    "register": true,
    "codecString": "PCMU,PCMA,G729",
    "sipProfileId": 1,
    "enabled": true
  }

`POST /telephony/inbound-routes`

Map an incoming DID number from a gateway to a local PBX destination.

Request Body Schema:

Json

  {
    "name": "Main Office Line",
    "didNumber": "+15551234567",
    "destinationType": "ivr",
    "destination": "5000",
    "enabled": true
  }

`POST /telephony/outbound-routes`

Define pattern-matching rules for outbound calls routing to SIP carriers.

Request Body Schema:

Json

  {
    "name": "US Local Calls",
    "pattern": "^9([2-9]\\d{6})$",
    "stripDigits": 1,
    "gateways": [
      { "gatewayId": 1, "priority": 1 }
    ],
    "enabled": true
  }

6. SMS Messaging

`POST /sms/messages/send`

Send an outbound SMS message through a carrier.

Request Body Schema:

Json

  {
    "from": "+15559876543",
    "to": "+15551234567",
    "message": "Hello from Ring2All!"
  }

7. AI Agents

`POST /telephony/ai-agents`

Configure an AI agent to handle voice interactions or text chatbots dynamically.

Request Body Schema:

Json

  {
    "name": "AI Front Desk Agent",
    "prompt": "You are a receptionist. Direct the call after greeting.",
    "providerId": 1,
    "voice": "alloy",
    "temperature": 0.7,
    "enabled": true
  }

8. Users & Role Profiles

`POST /api/users`

Create a new administrator or portal user account.

Request Body Schema:

Json

  {
    "email": "user@acme.com",
    "password": "TemporaryPassword123!",
    "fullName": "Jane Doe",
    "roleId": 2,
    "tenantId": 1,
    "isActive": true
  }

`POST /api/role-profiles`

Define a role-based access control profile.

Request Body Schema:

Json

  {
    "name": "PBX Manager",
    "description": "Full access to telephony and reporting features",
    "permissions": [
      { "moduleSlug": "extensions", "level": "write" },
      { "moduleSlug": "cdr", "level": "read" }
    ]
  }

🚀 Postman Resources

To help you get started quickly, download the preconfigured Postman collection and environment matching this External API integration guide.

To use these files in Postman:

Download both JSON files to your local machine.
Open Postman and click on the Import button in the top-left corner.
Select the downloaded JSON files to import them.
Set the active environment to Ring2All External API Environment and update the base_url and api_key variables with your credentials.