Reserve a Routable Number | Salesforce Voice with Telephony Providers Implementation Guide

Use this API to reserve a PSTN number from the Agentforce Voice number pool. The partner telephony system calls this API to obtain a dynamic routing number before transferring the PSTN call to Salesforce. The returned routableNumber is valid for a limited time and is used as the PSTN transfer destination. Salesforce uses the PSTN number along with the caller's fromNumber to resolve the voice session context when the call arrives. The allocated number is valid for a maximum of 180 seconds. This API is available only to organizations provisioned for Agentforce Voice with the number-pool feature enabled.

URI

https://{MyDomain}.my.salesforce-scrt.com/telephony/v1/voiceCalls/reserveRoutableNumber

Where {MyDomain} is a value configured as part of Salesforce setup.

HTTP Method

POST

Headers

Authorization: Bearer <token>: String. Standard header. The authorization token, where <token> is the JSON Web Token (JWT). Required.
Content-Type: <format>: String. Standard header. The format of the request body. Valid formats include JSON and XML. For example, application/json or application/xml. Required.
Telephony-Provider-Name: <telephony provider name>: String. Custom header. The name of the telephony provider that calls this API. For example, Amazon Connect.

Parameters

Property Name	Type	Description	Required
`countryCode`	string	The ISO 3166-1 alpha-2 country code for number pool selection. If your country isn't listed, specify the closest supported country and minimize call latency. Belgium (BE) Denmark (DK) Finland (FI) France (FR) Germany (DE) Netherlands (NL) Poland (PL) Spain (ES) Sweden (SE) Switzerland (CH) United Kingdom (GB)	Yes
`fromNumber`	string	The caller's phone number in E.164 format. For example, `+14155551234`. This number is used for validation during call lookup.	Yes
`scrt2Domain`	string	The SCRT2 domain URL for the Salesforce organization. For example, `https://example.my.salesforce-scrt.com`.	Yes
`toNumber`	string	The virtual phone number in E.164 format that you configure in Salesforce.	Yes
`callId`	string	The ID of the initial voice call record (VC1) that’s created when the inbound call to the partner contact center.	Yes
`transactionId`	string	A UUID that uniquely identifies this reserveRoutableNumber request. If provided, Salesforce uses this value to support idempotent retry behavior. If the partner contact center retries the request due to a timeout or transient error, passing the same transactionId ensures that a duplicate phone number lease isn’t created.	Yes

Example

Request:

1POST /telephony/v1/voiceCalls/reserveRoutableNumber
2
3{
4  "country": "US",
5  "fromNumber": "+14155551234",
6  "context": {
7    "scrt2Domain": "https://example.my.salesforce-scrt.com",
8    "toNumber": "+15551234567",
9    "callId": "0LQxx0000004ABcGAM",
10    "transactionId": "8f3c9e2a-1b4d-4e7f-9a0c-2d6e1f3b5a8c"
11  }
12}

Response:

1{
2  "status": "success",
3  "mode": "number",
4  "handle": {
5    "routableNumber": "+14155559876",
6    "uid": "lease:did:+14155559876:1716234311",
7    "expiresAt": "2026-05-22T18:45:11Z"
8  }
9}