Reserve a Routable Number

Reserves a routable phone number for dynamic PSTN call forwarding to Agentforce Voice.

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. Australia (AU) Belgium (BE) Cyprus (CY) Czechia (CZ) Denmark (DK) Finland (FI) France (FR) Germany (DE) Ireland (IE) Israel (IL) Italy (IT) Lithuania (LT) Luxembourg (LU) Mexico (MX) Netherlands (NL) New Zealand (NZ) Norway (NO) Poland (PL) Slovakia (SK) Slovenia (SI) Spain (ES) Sweden (SE) Switzerland (CH) United Kingdom (GB) Japan (JP)	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}