Sip Routing - Test Routes With Number

Service:: Communication

API Version:: 2024-11-15-preview

Gets the list of routes matching the target phone number, ordered by priority.

POST {endpoint}/sip:testRoutesWithNumber?targetPhoneNumber={targetPhoneNumber}&api-version=2024-11-15-preview

URI Parameters

Name	In	Required	Type	Description
endpoint	path	True	string	The communication resource, for example https://resourcename.communication.azure.com
api-version	query	True	string	Version of API to invoke
targetPhoneNumber	query	True	string	Phone number to test routing patterns against

Request Body

Name	Type	Description
domains	<string, Domain>	Validated Domains. Map key is domain.
routes	TrunkRoute[]	Trunk routes for routing calls.
trunks	<string, Trunk>	SIP trunks for routing calls. Map key is trunk's FQDN (1-249 characters).

Responses

Name	Type	Description
200 OK	RoutesForNumber	A list of matching routes
Other Status Codes	CommunicationErrorResponse	Failure

Security

azure_auth

Azure Active Directory OAuth2 Flow

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name	Description
user_impersonation	impersonate your user account

access_key

An authentication string containing a signature generated using HMAC-SHA256 scheme.

Type: apiKey
In: header

Examples

Validate target phone number routing

Sample request

HTTP

POST https://resourcename.communication.azure.com/sip:testRoutesWithNumber?targetPhoneNumber=+14251234567&api-version=2024-11-15-preview

{
  "domains": {
    "contoso.com": {
      "enabled": true
    }
  },
  "trunks": {
    "seattle.contoso.com": {
      "sipSignalingPort": 5011,
      "enabled": true,
      "directTransfer": false,
      "privacyHeader": "none",
      "ipAddressVersion": "ipv4"
    },
    "us1.contoso.com": {
      "sipSignalingPort": 5012,
      "enabled": true,
      "directTransfer": false,
      "privacyHeader": "none",
      "ipAddressVersion": "ipv4"
    },
    "us2.contoso.com": {
      "sipSignalingPort": 5013,
      "enabled": true,
      "directTransfer": false,
      "privacyHeader": "none",
      "ipAddressVersion": "ipv4"
    },
    "russia.contoso.com": {
      "sipSignalingPort": 5014,
      "enabled": true,
      "directTransfer": false,
      "privacyHeader": "none",
      "ipAddressVersion": "ipv4"
    },
    "global.contoso.com": {
      "sipSignalingPort": 5015,
      "enabled": true,
      "directTransfer": false,
      "privacyHeader": "none",
      "ipAddressVersion": "ipv4"
    }
  },
  "routes": [
    {
      "name": "Seattle",
      "description": "Seattle route",
      "numberPattern": "^\\+1(425|206)\\d{7}$",
      "trunks": [
        "seattle.contoso.com"
      ]
    },
    {
      "name": "US",
      "description": "US route",
      "numberPattern": "^\\+1\\d{10}$",
      "trunks": [
        "us1.contoso.com",
        "us2.contoso.com"
      ]
    },
    {
      "name": "Russia",
      "description": "Russian route",
      "numberPattern": "^\\+7\\d+$",
      "trunks": [
        "russia.contoso.com"
      ]
    },
    {
      "name": "Global",
      "description": "Fallback route",
      "numberPattern": "^\\+\\d+$",
      "trunks": [
        "global.contoso.com"
      ],
      "callerIdOverride": "+1234567890"
    }
  ]
}

Sample response

Status code:: 200

{
  "matchingRoutes": [
    {
      "description": "Seattle route",
      "name": "Seattle",
      "numberPattern": "^\\+1(425|206)\\d{7}$",
      "trunks": [
        "seattle.contoso.com"
      ]
    },
    {
      "description": "US route",
      "name": "US",
      "numberPattern": "^\\+1\\d{10}$",
      "trunks": [
        "us1.contoso.com",
        "us2.contoso.com"
      ]
    },
    {
      "description": "Fallback route",
      "name": "Global",
      "numberPattern": "^\\+\\d+$",
      "trunks": [
        "global.contoso.com"
      ],
      "callerIdOverride": "+1234567890"
    }
  ]
}

Definitions

Name	Description
CommunicationError	The Communication Services error.
CommunicationErrorResponse	The Communication Services error.
Domain	Represents Domain object as response of validation api. Map key is domain.
Health	Represents health state of a SIP trunk for routing calls.
inactiveStatusReason	The reason overall status of Trunk is inactive.
IpAddressVersion	IP address version.
OverallHealth	The overall health status of Trunk.
overallHealthStatus	The overall health status of Trunk.
Ping	The status of SIP OPTIONS message sent by Trunk.
pingStatus	The status of SIP OPTIONS message sent by Trunk.
PrivacyHeader	SIP privacy header value, `id` - Privacy requested for Third-Party Asserted Identity (rfc3325), `none` - No operation is performed by privacy service (rfc3323)
RoutesForNumber	Represents number routing validation details.
SipConfiguration	Represents a SIP configuration. When a call is being routed the routes are applied in the same order as in the routes list. A route is matched by its number pattern. Call is then directed into route's first available trunk, based on the order in the route's trunks list. The configuration can be expanded with additional data.
Tls	The status of the TLS connections of the Trunk.
tlsStatus	The status of the TLS connections of the Trunk.
Trunk	Represents a SIP trunk for routing calls. See RFC 4904. Can be expanded with additional data.
TrunkRoute	Represents a trunk route for routing calls.

CommunicationError

Object

The Communication Services error.

Name	Type	Description
code	string	The error code.
details	CommunicationError[]	Further details about specific errors that led to this error.
innererror	CommunicationError	The inner error if any.
message	string	The error message.
target	string	The error target.

CommunicationErrorResponse

Object

The Communication Services error.

Name	Type	Description
error	CommunicationError	The Communication Services error.

Domain

Object

Represents Domain object as response of validation api. Map key is domain.

Name	Type	Description
enabled	boolean	Enabled flag

Health

Object

Represents health state of a SIP trunk for routing calls.

Name	Type	Description
overall	OverallHealth	The overall health status of Trunk.
ping	Ping	The status of SIP OPTIONS message sent by Trunk.
tls	Tls	The status of the TLS connections of the Trunk.

inactiveStatusReason

Enumeration

The reason overall status of Trunk is inactive.

Value	Description
noRecentCalls	Indicates no recent calls.
noRecentPings	Indicates ping status is expired.
noRecentCallsAndPings	Indicates no recent calls and ping status is expired.

IpAddressVersion

Enumeration

IP address version.

Value	Description
ipv4
ipv6

OverallHealth

Object

The overall health status of Trunk.

Name	Type	Description
reason	inactiveStatusReason	The reason overall status of Trunk is inactive.
status	overallHealthStatus	The overall health status of Trunk.

overallHealthStatus

Enumeration

The overall health status of Trunk.

Value	Description
unknown	Indicates an unknown health status.
active	Indicates the Trunk is active.
inactive	Indicates the Trunk is inactive.

Ping

Object

The status of SIP OPTIONS message sent by Trunk.

Name	Type	Description
status	pingStatus	The status of SIP OPTIONS message sent by Trunk.

pingStatus

Enumeration

The status of SIP OPTIONS message sent by Trunk.

Value	Description
unknown	Indicates an unknown status.
ok	Indicates the status is okay.
expired	Indicates the status is expired.
error	Indicates the status is at an error level.

PrivacyHeader

Enumeration

SIP privacy header value, id - Privacy requested for Third-Party Asserted Identity (rfc3325), none - No operation is performed by privacy service (rfc3323)

Value	Description
id
none

RoutesForNumber

Object

Represents number routing validation details.

Name	Type	Description
matchingRoutes	TrunkRoute[]	The list of routes whose number patterns are matched by the target number. The routes are displayed and apply in the same order as in SipConfiguration.

SipConfiguration

Object

Represents a SIP configuration. When a call is being routed the routes are applied in the same order as in the routes list. A route is matched by its number pattern. Call is then directed into route's first available trunk, based on the order in the route's trunks list. The configuration can be expanded with additional data.

Name	Type	Description
domains	<string, Domain>	Validated Domains. Map key is domain.
routes	TrunkRoute[]	Trunk routes for routing calls.
trunks	<string, Trunk>	SIP trunks for routing calls. Map key is trunk's FQDN (1-249 characters).

Tls

Object

The status of the TLS connections of the Trunk.

Name	Type	Description
status	tlsStatus	The status of the TLS connections of the Trunk.

tlsStatus

Enumeration

The status of the TLS connections of the Trunk.

Value	Description
unknown	Indicates an unknown status.
ok	Indicates the status is okay.
certExpiring	Indicates the Trunk certificate is expiring.
certExpired	Indicates the Trunk certificate is expired.

Trunk

Object

Represents a SIP trunk for routing calls. See RFC 4904. Can be expanded with additional data.

Name	Type	Description
directTransfer	boolean	When enabled, removes Azure Communication Services from the signaling path on call transfer and sets the SIP Refer-To header to the trunk's FQDN. By default false.
enabled	boolean	Enabled flag
health	Health	Represents health state of a SIP trunk for routing calls.
ipAddressVersion	IpAddressVersion	IP address version used by the trunk. Default value is ipv4.
privacyHeader	PrivacyHeader	SIP Privacy header. Default value is id.
sipSignalingPort	integer (int32)	Gets or sets SIP signaling port of the trunk.

TrunkRoute

Object

Represents a trunk route for routing calls.

Name	Type	Description
callerIdOverride	string	Gets or sets caller ID override. This value will override caller ID of outgoing call specified at runtime.
description	string maxLength: 1024	Gets or sets description of the route.
name	string maxLength: 256	Gets or sets name of the route.
numberPattern	string maxLength: 1024	Gets or sets regex number pattern for routing calls. .NET regex format is supported. The regex should match only digits with an optional '+' prefix without spaces. I.e. "^+[1-9][0-9]{3,23}$".
trunks	string[]	Gets or sets list of SIP trunks for routing calls. Trunks are represented as FQDN.

Compartilhar via

Sip Routing - Test Routes With Number

URI Parameters

Request Body

Responses

Security

azure_auth

Scopes

access_key

Examples

Validate target phone number routing

Sample request

Sample response

Definitions

CommunicationError

CommunicationErrorResponse

Domain

Health

inactiveStatusReason

IpAddressVersion

OverallHealth

overallHealthStatus

Ping

pingStatus

PrivacyHeader

RoutesForNumber

SipConfiguration

Tls

tlsStatus

Trunk

TrunkRoute