Programmatic Call Forwarding API: Manage Forwarding via REST
Control Call Forwarding Programmatically with the Simple Telecom Routing API
Key Call Forwarding API Features
- Add forwarding numbers to any service with a single POST request
- Set custom ring durations per forwarding number (default 180 seconds)
- Update forwarding numbers — change the number, label, or ring duration
- Remove forwarding numbers when no longer needed
- View complete forwarding configuration for any service
What Is Programmatic Call Forwarding?
Programmatic call forwarding is the ability to manage where your calls are directed through software — without logging into a web console or phone system. Instead of manually updating forwarding settings, you use API calls to add, remove, or modify forwarding numbers. This is invaluable for businesses that need to update forwarding dynamically based on time, staff availability, or operational requirements.
The Simple Telecom Routing API provides full CRUD (Create, Read, Update, Delete) control over your forwarding configuration. You can add new forwarding numbers, update existing ones, remove them, and view the complete configuration — all through RESTful HTTP endpoints. Each forwarding number can have a custom ring duration and display name, giving you fine-grained control over how calls are handled.
For Australian businesses with 1300 or 1800 numbers, programmatic call forwarding means you can route calls to any Australian phone number — mobile, landline, or VoIP — and change those destinations automatically as your business needs evolve. No hardware, no phone technicians, no complicated configuration.
The Forwarding API Endpoints
Four endpoints make up the call forwarding management system. The GET /api/services/{service_id}/routing endpoint retrieves the complete routing configuration for a service, including all forwarding numbers, their positions, display names, ring durations, and whether call recording is enabled. This is your starting point for understanding the current state before making changes.
To add a new forwarding number, use POST /api/services/{service_id}/routing/forwarding. The request body requires the phone_number in Australian format (with +61 or 0 prefix), and optionally accepts a display_name (max 100 characters) and duration (ring time in seconds, default 180). The number is added to the end of the forwarding sequence.
When you need to modify an existing forwarding entry, use PUT /api/services/{service_id}/routing/forwarding. Identify the 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. To remove a number, use DELETE /api/services/{service_id}/routing/forwarding with the phone number to remove.
Sequential Calling Patterns
One of the most powerful features of the forwarding API is the ability to create sequential calling patterns. A forwarding number’s duration field controls how many seconds the system will ring that number before moving to the next one. By adding the same phone number multiple times with different durations, you can create sophisticated call handling behaviours.
For example, you might add a mobile number with a 15-second duration for a quick first attempt, then add the same number again with a 180-second duration as a fallback. This means the call rings briefly, then tries other numbers in the sequence, and finally returns to the original number for a longer ring. This pattern ensures calls are distributed efficiently while still giving each destination a fair chance to be answered.
You can build complex sequences with multiple numbers at different durations. For a small business, a typical setup might be: ring the office phone for 15 seconds, then the mobile for 15 seconds, then the home office for 30 seconds, then back to the mobile for 180 seconds. This ensures calls follow a logical path through your available staff.
Security and Error Handling
The forwarding API enforces important safeguards. Most critically, you cannot remove the last remaining forwarding number from a service — every service must have at least one destination. This prevents accidental misconfiguration that would leave callers with no way to reach you. If you attempt to remove the last number, the API returns a last_forwarding_number error.
Phone numbers must be in Australian format. The API accepts landlines like 0298765432 or +61298765432 and mobiles like 0412345678 or +61412345678. International numbers are not supported. If you send an invalid phone number format, the API returns an invalid_phone_format error.
Common error responses include 401 Unauthorized for invalid or expired tokens, 403 Forbidden when a service belongs to a different account, 404 Not Found for invalid service IDs, and 400 Bad Request for various validation errors. All errors return a consistent JSON structure with status, code, and message fields.
Automating Forwarding for Business Workflows
Programmatic call forwarding enables automation that would be impractical with manual management. Here are some common business applications:
After-Hours Forwarding: Automatically switch forwarding to an after-hours destination at a specific time each day. Use a scheduled task to update forwarding at 5pm to a mobile number or voicemail service, then switch back at 9am. This eliminates the risk of forgetting to update forwarding manually.
Staff Availability-Based Routing: Connect the forwarding API to your staff scheduling system. When a staff member logs in, add their number to the forwarding sequence. When they log out, remove it. This ensures calls always go to available team members without manual intervention.
Campaign-Specific Forwarding: For marketing campaigns that require calls to go to specific teams or agents, update forwarding automatically when campaigns launch or end. This ensures the right people handle the right calls without manual routing changes.
Best Practices for Managing Forwarding via API
When managing call forwarding via the API, follow these best practices for reliable operation. First, always retrieve the current routing configuration before making changes. This gives you a complete picture of the current state and helps you avoid unintended changes. Use the GET routing endpoint to view the current configuration as your starting point.
Second, implement proper error handling in your integration. Handle the last_forwarding_number error by prompting users to add a new number before removing the last one. Validate phone number formats client-side before sending to the API. Implement retry logic with backoff for rate limiting scenarios.
Third, log all forwarding changes for audit purposes. Keep a record of when forwarding numbers were added, updated, or removed, and by which process or user. This creates an audit trail that can be invaluable for troubleshooting or investigating routing issues.
Frequently Asked Questions
Frequently Asked Questions About the Call Forwarding API
How quickly do forwarding changes take effect?
Forwarding changes are applied immediately. Once you receive a success response from the API, the new forwarding configuration is active for all incoming calls to that service.
Can I have multiple forwarding numbers?
Yes, you can add as many forwarding numbers as you need. They’re called in sequence based on their position, with each number ringing for its configured duration before moving to the next.
What happens if no one answers at any forwarding number?
If all forwarding numbers ring without being answered, the call is typically handled by voicemail or disconnected depending on your service configuration. Consider adding a voicemail destination as the last number in your sequence.
Can I forward calls to a VoIP number?
Yes, the API supports forwarding to any Australian phone number, including VoIP numbers. Just ensure the number is in the correct Australian format.
How do I find the service ID for my number?
Use the Services API (GET /api/services) to list all your active services. Each service entry includes the service_id you need for routing management.
Our Programmatic Call Forwarding API gives Australian businesses complete control over how calls are routed, making it easy to manage your 1300 number name and call distribution in real-time. Whether you’re curious about whether 1300 numbers are free in Australia or looking to integrate advanced call management with your marketing efforts, our REST API delivers the flexibility you need. It pairs perfectly with call tracking software for Google Ads, helping you measure campaign performance while maintaining a professional national presence. Need to explore more features? Search our full range of solutions to find what works best for your business.
