Step-by-Step API Integration Tutorial

Welcome to the Ring2All External API Quickstart Tutorial!

This step-by-step guide is designed to help you integrate your external applications (like custom CRMs, support ticket systems, or automation bots) with the Ring2All PBX platform in under 15 minutes.

We will walk you through setting up credentials, importing our Postman files, and making your first REST API requests to manage extensions, send SMS, fetch call records, and monitor active lines.

📋 Prerequisites

Before starting, ensure you have:

1. Access to the Ring2All Administrator Portal.
2. A working installation of Postman (desktop or web app).
3. The PBX domain name or IP address (e.g. https://pbx.yourdomain.com).

🔑 Step 1: Generate your API Key

To query the API from an external application safely, we use an Application API Key. Unlike user login sessions (which use short-lived JWT tokens), API Keys remain active until you explicitly delete or deactivate them.

1. Log into the Ring2All Administrator Portal.
2. Navigate to Admin ➔ Administration ➔ Application Keys.
3. Click the Create API Key button in the top-right corner.
4. Provide a friendly identifier (e.g., CRM-Integration) and choose the active status.
5. Click Save.
6. Important: Copy the generated key token (it starts with ak_). Store it securely; you will not be able to view it again after leaving the screen.

🚀 Step 2: Configure your Postman Workspace

We provide a pre-packaged Postman Collection and Environment template containing all available PBX endpoints.

1. Download the Assets:

- 📥 Postman Environment JSON

1. Import into Postman:

- Drag and drop both JSON files, then click Import.

1. Configure Environment Variables:

- Set the variables in the Current Value column:

base_url: https://pbx.yourdomain.com/api (replace with your server's domain/IP)

api_key: ak_your_copied_api_key

tenant_slug: your-tenant-slug

   {
     "success": true,
     "data": [
       {
         "id": 1,
         "extension": "1001",
         "enabled": true,
         "type": "user"
       }
     ],
     "meta": { "page": 1, "limit": 25, "total": 1 }
   }
   

Troubleshooting: If you receive a 401 Unauthorized or INVALID_API_KEY, double check that the api_key environment variable is correctly set and that the active environment is selected in the top-right corner.

   {
     "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": "Jane Smith Desk Phone"
       }
     ],
     "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" }
     ]
   }
   

to: The customer's mobile phone number (in E.164 international format).

message: The message text.

   {
     "from": "+15559876543",
     "to": "+15551234567",
     "message": "Hello! Your appointment is scheduled for tomorrow at 10:00 AM."
   }
   

1. Click Send. You will receive confirmation that the message has been queued by the PBX SMS service:

   {
     "success": true,
     "messageId": "msg_890abcde",
     "status": "queued",
     "segments": 1,
     "encoding": "GSM7"
   }
   

📊 Step 6: Synchronize Call Logs (CDRs)

To log customer phone calls directly under contact cards inside your CRM, you need to query the Call Detail Records (CDRs).

1. Go to the Call Detail Records (CDRs) folder in Postman.
2. Select List CDRs (GET).
3. Notice the query parameters preconfigured in the URL to fetch today's logs:

- endDate: 2026-06-19T23:59:59.000Z

1. Click Send.
2. The response details every call completed during the range, including:

- destinationNumber: The number dialed.

- duration: Total call duration (seconds).

- billsec: Active audio conversation seconds.

- hangupCause: Cause code (e.g., NORMAL_CLEARING for normal hangup).

- recordingFile: Path of the recording file.

1. To fetch the recording audio file (.wav format) for archiving or playback in your CRM, use the Download Recording request with the {{cdr_id}} variable.

📡 Step 7: Screen-Pop Popups - Active Calls Monitoring

To show customer account cards to call center agents immediately when their phone rings, you need to monitor live, active calls.

1. Go to the Active Calls Monitoring folder in Postman.
2. Select List Active Calls (GET).
3. Click Send.
4. If a call is currently routing or talking on the system, you will see it in real-time:

   {
     "success": true,
     "data": [
       {
         "uuid": "f7f7f7f7-f8f8-f9f9-f0f0-f1f1f1f1f1f1",
         "direction": "inbound",
         "callerIdName": "Jane Customer",
         "callerIdNumber": "+15551234567",
         "destination": "1005",
         "state": "RINGING",
         "duration": 5
      }
     ]
   }
   

1. Your CRM integration script can poll this endpoint or connect to the /ws/realtime WebSocket endpoint to look up the callerIdNumber against the customer database and instantly open the customer profile (Screen-Pop) on agent Jane Smith's browser window when destination === "1005".

💡 Next Steps

Now that you understand how the API functions:

Review the External API Integration Guide for advanced schemas, error codes, and webhook configurations.