Call Routing API: Programmatic Call Management
Control Your Call Routing Programmatically with the Simple Telecom Routing API
Key Routing API Features
- View complete routing configuration for any service via GET endpoint
- Add forwarding numbers with custom ring durations and display names
- Update existing forwarding numbers — change number, label, or duration
- Remove forwarding numbers from service routing
- Enable or disable call recording per service
What Is the Call Routing API?
The Simple Telecom Call Routing API gives you full programmatic control over how calls are directed to your team. Instead of logging into the web console to update routing settings, you can manage everything through simple HTTP requests — perfect for businesses that need to change routing dynamically based on time of day, agent availability, or campaign requirements.
The API covers the complete lifecycle of call routing: you can view current configuration, add new forwarding numbers, update existing ones, remove them, and toggle call recording — all through RESTful endpoints. Each endpoint returns clear JSON responses with meaningful error messages, making integration straightforward for any development team.
Authentication uses Bearer tokens issued from your Simple Telecom console. All requests are rate-limited to ensure fair usage, and response headers tell you your current limit status. The base URL is https://api.simpletelecom.com/v1.
Viewing and Managing Forwarding Numbers
The GET /api/services/{service_id}/routing endpoint returns the complete routing configuration for a service, including all forwarding numbers and whether call recording is enabled. This is your starting point for understanding how calls are currently handled. Each forwarding number entry includes its position in the routing order, the phone number, an optional display name, and the ring duration in seconds.
To add a new forwarding number, use POST /api/services/{service_id}/routing/forwarding with the phone number (in Australian format with +61 or 0 prefix), an optional display name (max 100 characters), and a ring duration in seconds. The default ring duration is 180 seconds, but many businesses use 15 seconds for quick overflow routing. You can add the same phone number multiple times with different durations — this enables sequential calling patterns where the same number rings briefly, then moves to the next destination.
Updating and Removing Forwarding Numbers
When you need to change a forwarding number’s properties, the PUT /api/services/{service_id}/routing/forwarding endpoint lets you update the phone number, display name, or ring duration. You identify the forwarding entry by its current phone number, then provide the new values for any fields you want to change. At least one field must be updated per request.
Removing a forwarding number is equally straightforward: use DELETE /api/services/{service_id}/routing/forwarding with the phone number to remove. Note that you cannot remove the last remaining forwarding number — every service must have at least one destination. This prevents accidental misconfiguration that would leave callers with no way to reach you.
All routing endpoints return appropriate error responses for common issues: 403 Forbidden if the service doesn’t belong to your account, 404 Not Found if the service ID doesn’t exist, and 400 Bad Request with specific error codes like invalid_phone_format or last_forwarding_number.
Managing Call Recording via API
Call recording can be enabled or disabled per service using the PUT /api/services/{service_id}/routing/recording endpoint. Simply send a JSON body with {"enabled": true} or {"enabled": false}. This is particularly useful for businesses that need to comply with different recording policies across departments, or for marketing campaigns where recording should be enabled only during specific time periods.
When call recording is enabled, all incoming calls to that service are automatically recorded. Recordings are stored and accessible through your Simple Telecom console. This feature is essential for quality assurance, staff training, compliance with industry regulations, and resolving disputes about what was discussed during a call.
Combined with the CDR API, you can build a complete call management system: use CDR data for analytics and attribution, and use the Routing API to dynamically adjust how calls are handled based on those analytics.
Integrating Routing API with Your Systems
The Routing API is designed to integrate seamlessly with your existing technology stack. Here are some common integration patterns:
CRM Integration: When a deal stage changes in your CRM, automatically update call routing to the appropriate team member. For example, when a lead moves to ‘qualified’, route calls directly to the assigned sales representative.
Time-Based Routing Automation: Use a scheduling system to update routing at specific times. Automatically switch to after-hours routing at 5pm, route to a different team on weekends, or update during public holidays — all without manual intervention.
Marketing Campaign Integration: Create unique routing configurations for each campaign. When a new campaign launches, automatically set up routing for the campaign-specific number and adjust it as the campaign evolves.
Staff Availability Integration: Connect to your HR or scheduling system to automatically add or remove forwarding numbers based on who’s working, their shift times, and their role.
Error Handling and Best Practices
When working with the Routing API, understanding error handling is essential for building robust integrations. All errors return a consistent JSON structure with status, code, and message fields. Common error codes include unauthorized (401) for invalid tokens, unauthorized_service (403) when a service belongs to a different account, service_not_found (404) for invalid service IDs, and invalid_phone_format (400) for incorrectly formatted phone numbers.
Phone numbers must be in Australian format: landlines like 0298765432 or +61298765432, and mobiles like 0412345678 or +61412345678. The API only accepts Australian phone numbers.
For best results, always retrieve the current routing configuration before making changes, validate phone numbers before sending them to the API, and handle the last_forwarding_number error gracefully — prompt users to add a new number before removing the last one.
Frequently Asked Questions
Frequently Asked Questions About the Call Routing API
Can I set up sequential routing via the API?
Yes. Add the same phone number multiple times with different ring durations to create sequential calling patterns. For example, add a number with a 15-second duration for a quick first attempt, then again with 180 seconds as a fallback.
What happens if I remove all forwarding numbers?
The API prevents you from removing the last forwarding number. Every service must have at least one destination to ensure calls are always answered. You’ll receive a last_forwarding_number error if you try.
Can I route calls to international numbers?
No, the Routing API only supports Australian phone numbers — landlines in the format 0298765432 or +61298765432, and mobiles in the format 0412345678 or +61412345678.
How quickly do routing changes take effect?
Routing changes are applied immediately. Once you receive a success response from the API, the new routing configuration is active for incoming calls.
Can I test routing changes without affecting live calls?
We recommend using a development or test service for initial testing. The API doesn’t have a sandbox mode, so you should validate your integration thoroughly on a non-critical service before applying changes to production numbers.
Our Call Routing API gives Australian businesses complete control over how incoming calls are managed and distributed across their teams. Whether you’re using a 1300 number location strategy or managing calls through 1800 numbers across Australia, programmatic routing ensures calls reach the right department instantly. Pair this with call tracking metrics support to monitor performance in real-time, or integrate with a Hosted PBX system for seamless, scalable communication that grows with your business.
