Skip to main content
Version: /v2

Create Routing Rule - API

Creates a routing rule and attaches it to the supplied phone numbers. A routing rule defines how SIP calls for those numbers are dispatched — either into a VideoSDK room (static or dynamic) and/or to an AI agent.

Header field rules:

  • headers is only allowed on outbound rules — these custom SIP headers are attached to outgoing INVITEs.
  • headersToAttributes is only allowed on inbound rules — it maps incoming SIP headers to participant attributes.
  • Sending the wrong one for the rule's type returns 400.

Validations:

  • name is required.
  • type must be one of inbound, outbound.
  • phoneNumbers must be an array of numbers that already exist on your account (provisioned via the Phone Numbers API).
  • Inbound rules cannot reuse numbers already attached to another inbound rule (returns 400).
  • apiKey, if provided, must be a valid API key.

Responses:

  • 201 success — returns the created routing rule.
  • 400 validation failure.
  • 500 internal server error.

HTTP method and endpoint

POST

|

https://api.videosdk.live/v2/sip/routing-rule
Headers Parameters
REQUIRED

values: YOUR_TOKEN_WITHOUT_ANY_PREFIX

This will be a JWT token generate using VideoSDK ApiKey and Secret.

Note that the token will not include any prefix such as "Basic " or "Bearer ". Just pass a token as value.

You can generate a new token by refering this Guide: Generate Auth token

REQUIRED

values: application/json

This is usefull for json body parameters, so that VideoSDK servers can understand that the incoming body parameter will be a JSON string.

Body Parameters
REQUIRED
A descriptive name for the routing rule.
REQUIRED
Rule direction. One of inbound, outbound. Cannot be changed after creation.
REQUIRED
Array of e164 phone numbers to attach this rule to. The numbers must already exist on the user.
OPTIONAL
Optional API key associated with the rule. Must be a valid API key — returns 400 Invalid API Key otherwise.
OPTIONAL
ID of the agent to dispatch the call to.
OPTIONAL
Key-value metadata forwarded to the agent (e.g. { team: 'support' }).
OPTIONAL

Room dispatch config.

  • type: static | dynamic.
  • prefix: prefix used when creating dynamic rooms (e.g. blank).
  • id: room ID, used when type = static.
  • pin: optional room PIN.
OPTIONAL
Controls which SIP headers are surfaced. One of ALL, SIP_X_HEADERS, NONE.
OPTIONAL
Inbound rules only. Map of incoming SIP header → participant attribute name. Returns 400 on outbound rules.
OPTIONAL
Outbound rules only. Custom SIP headers attached to outgoing INVITEs. Returns 400 on inbound rules.
OPTIONAL
Optional allowlist of caller numbers. Empty array means no restriction.
OPTIONAL
Optional allowlist of caller IP addresses. Empty array means no restriction.
OPTIONAL
Free-form tag array for this rule.
OPTIONAL
Whether calls dispatched by this rule should be recorded.
OPTIONAL
Whether DTMF event capture is enabled for the call.
OPTIONAL
Whether noise cancellation is enabled on the call audio.
OPTIONAL
If true, the caller's phone number is hidden when dispatching the call.
Response Parameters
Unique identifier of the routing rule.
Name of the routing rule.
Rule direction — inbound or outbound.
Phone numbers attached to this rule.
Room dispatch object — { type, prefix, id, pin }. Top-level (no dispatch wrapper).
ID of the dispatched agent, or null.
Metadata object forwarded to the agent.
Resolved API key string, if apiKey was supplied at create time.
Which SIP headers are surfaced — ALL, SIP_X_HEADERS, or NONE.
Present on inbound rules only — SIP header → attribute map.
Present on outbound rules only — custom SIP headers attached to outgoing INVITEs.
Allowlist of caller numbers.
Allowlist of caller IP addresses.
Tags applied to the rule.
Whether calls are recorded.
Whether DTMF events are captured.
Whether noise cancellation is enabled.
Whether the caller's number is hidden when dispatching.
Creation timestamp (ISO 8601).
Last-update timestamp (ISO 8601).
POST
|
https://api.videosdk.live/v2/sip/routing-rule
NodeJS
import fetch from 'node-fetch';
const options = {
	method: "POST",
	headers: {
		"Authorization": "$YOUR_TOKEN",
		"Content-Type": "application/json",
	},
	body: JSON.stringify({
	"name": "Inbound support rule",
	"type": "inbound",
	"phoneNumbers": [
		"+14155551234"
	],
	"apiKey": "$YOUR_API_KEY",
	"agentId": "$YOUR_AGENT_ID",
	"agentMetadata": {
		"team": "support"
	},
	"room": {
		"type": "dynamic",
		"prefix": "blank"
	},
	"includeHeaders": "SIP_X_HEADERS",
	"headersToAttributes": {
		"X-Caller-Id": "callerId"
	},
	"headers": {
		"X-Customer-Id": "cust_42"
	},
	"allowedNumbers": [],
	"allowedIpAddresses": [],
	"tags": [
		"support",
		"v2"
	],
	"recording": false,
	"dtmf": false,
	"noiseCancellation": false,
	"hidePhoneNumber": true
}),
};
const url= `https://api.videosdk.live/v2/sip/routing-rule`;
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
RESPONSE
{
  "id": "rr_abc123",
  "name": "Inbound support rule",
  "type": "inbound",
  "numbers": [
    "+14155551234"
  ],
  "room": {
    "type": "dynamic",
    "prefix": "blank",
    "id": null,
    "pin": null
  },
  "agentId": "agent_xyz",
  "agentMetadata": {
    "team": "support"
  },
  "hidePhoneNumber": true,
  "tags": [
    "support",
    "v2"
  ],
  "apiKey": "ak_resolved",
  "recording": false,
  "dtmf": false,
  "noiseCancellation": false,
  "allowedNumbers": [],
  "allowedIpAddresses": [],
  "includeHeaders": "SIP_X_HEADERS",
  "headersToAttributes": {
    "X-Caller-Id": "callerId"
  },
  "createdAt": "2026-05-11T10:00:00.000Z",
  "updatedAt": "2026-05-11T10:00:00.000Z"
}

Got a Question? Ask us on discord

Last updated on by Pankaj Patel
Previous
Fetch all Routing Rule
Next