Integrate with Dialpad

Call Routing via APIs


Early Beta

The below feature is in an early beta and could potentially have bugs. Please reach out to us at [email protected] should you encounter any issues


Suppose you have a Sales representative that's been engaged in conversations with a prospect for the past month for a giant deal. Wouldn't it be great if when the prospect calls back on the company mainline, the call goes directly to the representative instead of sending them through an IVR? Along with showing the prospect that they're being given extra attention, it would also help the sales continue conversations with ease.

Dialpad's Routing APIs allow you to do just that! With these APIs, you can have total control over where each inbound call is routed, whether it's though our standard routing mechanisms in a Department or Call Centre, or whether it's sent through directly to a User. This document describes the basics of call routers, the steps needed to setup these call routers and the expected responses.

How Call Routing Works

The above diagram illustrates the working of a call router. Once a router is setup, call information is published to a specified URL. The third party then uses that data to generate routing information for that call. The call is then routed to the appropriate user or department or call centre. In the above example, the call was routed to a user. However, the system is flexible to route calls to a department or call centre depending on the call.

Creating the Call Router

To create a call router, invoke the POST callrouters method.








Specify a name for the call router


string (URL)


The URL that should be consulted to route calls




A JWT secret to be used




The office to which the call router belongs




The fallback target to be used in case of client server unavailability




The type associated with the default_target_id (i.e. office, department, callcenter, or user)




Set to true as default. If set as false, the call router will act as pass through to the office mainline


import requests

url = "https://dialpad.com/api/v2/callrouters"

payload = '''{
  "default_target_id": "123456",
  "default_target_type": "callcenter",
  "name": "Hello Router",
  "office_id": "223456",
  "routing_url": "https://yourroutingservice.com/routecall",

headers = {
  'accept': "application/json",
  'content-type': "application/json"

response = requests.request("POST", url, data=payload, headers=headers)

Upon successful creation of the call router, the following response is sent

  “id”: “generated id”,
  “name”: “name”,
  “routing_url”: “routing_url”,
  “office_id”: “office_id”,
  “default_target_id”: “12341234”,
  “default_target_type”: “callcenter”,
  “enabled”: true,
  “phone_numbers”: [“e164 number”, ...],
  “signature”: {
    “type”: “jwt”,
    “algo”: “HS256”,
    “secret”: “secret”

To set a phone number for the call router, invoke the POST callrouters/id/assign_number method. This number should be provided to your customers.

import requests

url = "https://dialpad.com/api/v2/callrouters/323456/assign_number"

headers = {
  'accept': "application/json",
  'content-type': "application/json"

response = requests.request("POST", url, headers=headers)

Providing Routing Information to the Call Router

Once a call comes into the number assigned to the call router, a JWT will be POST-ed to the routing_url . The JSON content of the JWT will be of the form:

  “date_started”: <ms_since_epoch>,
  “call_id”: <call_id>,
  “external_number”: “<e164 number>”,
  “internal_number”: “<e164 number>”,
  “contact_id”: <contact_id>,
  “contact_type”: <contact_type>,

The external_number will contain the number of the caller.

Using this information along with any other relevant details, the URL should respond with the following JSON containing routing information

  “target_id”: <the target id>,
  “target_type”: “office|callcenter|user|department”

The call router would then route the call to the relevant target.

Note that if the endpoint takes more than 5 seconds to respond or if there are more than 10 failures in an hour, then the call router will be automatically disabled, and an email will be sent to the office admin. In order to rejuvenate the call router , it must be re-enabled via the PATCH callrouters/id method.

Deleting Call Routers

Call routers can be deleted by calling the DELETE callrouters/id method. Note that deletion takes effect immediately and would place the number assigned to the call router in reserve.

Error Handling

If a response from the routing_url is invalid or a response is not received within 5 seconds, calls will be routed to the default_target and an internal routing error count will be incremented. If the error rate exceeds 10 per hour, the router will automatically set the enabled property to false, and calls will be routed directly to the default_target without making any requests to the routing_url.

In this situation, the first step will be to investigate and correct the underlying issue in your routing endpoint.

Uniform Errors

In many cases the issue will have a consistent source, and the error may be completely resolved once the issue is addressed. In this situation, the call router can simply be re-enabled the call router by setting the enabled property to true via the PATCH endpoint.

Inconsistent Errors

In some situations (such as performance issues that occasionally result in request latency greater than 5-seconds), your routing endpoint may still have occasional routing errors after applying a fix. In this situation, it may be desirable to re-enable the router in addition to resetting the internal error count. To accomplish this, you can make a PATCH request that includes "reset_error_count": true, "enabled": true.

Additional Notes

  • Call routers can be assigned multiple numbers.

Using multiple numbers may be useful for assessing the efficacy of an ad campaign or providing separate numbers for support and sales. Your routing endpoint can use this information to make routing decisions, since the internal_number will indicate which number the caller dialed.

  • Call routers can be configured to send JWT payloads for additional security.

In order to verify that a routing request is genuine, you can set the secret property on the call router by using the POST or PATCH endpoints. If a call router is given a secret, then it will use that secret to send a signed JWT payload to your endpoint, rather than a raw JSON payload.

Updated 7 days ago

Call Routing via APIs

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.