Manage Forwarding

Overview

Three endpoints let you manage the forwarding destinations on a service. Together with GET /api/services/{id}/routing they give you full programmatic control over who answers calls and in what order.

Base path for all of them:

https://api.simpletelecom.com.au/v1/api/services/{service_id}/routing/forwarding

Phone number format

Australian numbers only, in either form:

• Landline: 0298765432 or +61298765432
• Mobile: 0412345678 or +61412345678

An invalid format returns 400 invalid_phone_format.

---

Add a forwarding number — POST

curl -X POST "https://api.simpletelecom.com.au/v1/api/services/123/routing/forwarding" \
  -H "Authorization: Bearer st_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "0412345678",
    "display_name": "Reception",
    "duration": 15
  }'

| Body field | Type | Required | Description | |---|---|---|---| | phone_number | string | Yes | Destination in Australian format | | display_name | string | No | Max 100 characters | | duration | integer | No | Ring duration in seconds (default 180; 15 is common for quick overflow) |

Key behaviour: the same number can be added more than once with different durations to create sequential ringing — the system tries one destination for its duration, then moves to the next position.

A successful response returns a message plus the full updated routing configuration.

{
  "message": "Forwarding number added.",
  "routing": {
    "service_id": 123,
    "forwarding_numbers": [
      { "position": 1, "phone_number": "0412345678", "display_name": "Reception", "duration": 15 },
      { "position": 2, "phone_number": "0298765432", "display_name": "Backup", "duration": 180 }
    ]
  }
}

---

Update a forwarding number — PUT

To change an existing destination you identify it by its current number, then supply at least one field to update.

curl -X PUT "https://api.simpletelecom.com.au/v1/api/services/123/routing/forwarding" \
  -H "Authorization: Bearer st_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "current_phone_number": "0412345678",
    "display_name": "Head Office",
    "duration": 30
  }'

| Body field | Type | Required | Description | |---|---|---|---| | current_phone_number | string | Yes | The existing number to identify the record by | | phone_number | string | No | If provided, the new number to replace it with | | display_name | string | No | New label | | duration | integer | No | New ring duration |

Provide the identifier plus at least one of the other fields.

---

Remove a forwarding number — DELETE

curl -X DELETE "https://api.simpletelecom.com.au/v1/api/services/123/routing/forwarding" \
  -H "Authorization: Bearer st_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "0298765432" }'

| Body field | Type | Required | Description | |---|---|---|---| | phone_number | string | Yes | The destination to remove |

You cannot remove the last forwarding number. Every service must keep at least one destination. Attempting to remove the final number returns 400 last_forwarding_number. Always check the current routing first (read routing) so you don't hit this.

---

A real flow: after-hours routing switch

The classic use case is switching a number to an after-hours destination when you're closed, then back when you reopen.

JavaScript (fetch)

const token = "st_your_token_here";
const base = "https://api.simpletelecom.com.au/v1";
const serviceId = 123;

async function setAfterHours(number) {
  // Find the current day destination to update in place.
  const current = await fetch(`${base}/api/services/${serviceId}/routing`,
    { headers: { Authorization: `Bearer ${token}` } }).then(r => r.json());

  for (const fwd of current.forwarding_numbers) {
    await fetch(`${base}/api/services/${serviceId}/routing/forwarding`, {
      method: "PUT",
      headers: {
        Authorization: `Bearer ${token}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        current_phone_number: fwd.phone_number,
        phone_number: number,
        display_name: "After Hours",
      }),
    });
  }
}

// Switch to the on-call mobile at 5pm.
await setAfterHours("0412000111");

Use cases

• After-hours / public-holiday routing — redirect to an on-call mobile or answering service without touching the console.
• Disaster failover — programmatically repoint a number to a backup line if your main site is down.
• Sequential ring groups — add two numbers with short durations (15) so calls roll quickly from one person to the next.
• Self-serve portals — let your own clients change their own forwarding numbers through your app.

Related

• Call routing — read the current configuration first.
• Call recording — pair routing with compliance recording.
• Error handling — invalid_phone_format and last_forwarding_number errors.