Salesforce Voice with Telephony Providers Implementation Guide
jReserve a Routable Number
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.
|
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 |
| context | object | The voice-call context associated with this reservation. See context. | Yes |
context
| Property Name | Type | Description | Required |
|---|---|---|---|
| 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. If omitted, context chaining with the parent voice call doesn't happen. | No |
| 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. Idempotency support takes effect only when this value is supplied. | No |
| partnerCallId | string | Vendor call key or UUID for the originating call leg. | No |
| additionalParams | object<string,string> | Free-form key/value parameters reserved for future use (phase 2). | No |
| originalFromNumber | string | Optional E.164 caller number before a partner rewrites fromNumber in number mode. For example, +14155551111. | No |
Example
Request:
1POST /telephony/v1/voiceCalls/reserveRoutableNumber
2
3{
4 "countryCode": "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}