PhoneNumberCreateRequest

retellConcurrencyCheckEnabledboolean

retellConcurrencyBurstAllowedboolean

failoverEnabledboolean

failoverDestinationstring | nullnullable

Generic SIP failover destination. The sip: or sips: prefix is optional; the API normalizes before routing.

Example: +15551234567@carrier.example.com

businessHoursEnabledboolean

businessHoursTimezonestring

Example: America/New_York

businessHoursSchedule object[]

Array [

daysinteger[]required

0=Sunday, 6=Saturday.

Possible values: >= 0 and <= 6

startstringrequired

Possible values: Value must match regular expression ^\d{2}:\d{2}$

endstringrequired

Possible values: Value must match regular expression ^\d{2}:\d{2}$

actionstring

Per-window routing action. failover uses destination when provided, otherwise the default outside-hours route.

Possible values: [retell, failover]

destinationstring | nullnullable

Optional per-window SIP destination override. The sip: or sips: prefix is optional.

Example: afterhours@carrier.example.com

]

businessHoursRouteModestring

Possible values: [retell_open, retell_closed]

businessHoursOutsideDestinationstring | nullnullable

Default outside-hours SIP destination when businessHoursOutsideDestinationMode is sip_uri. The sip: or sips: prefix is optional.

Example: afterhours@carrier.example.com

inboundRetellHeaders object[]

Possible values: <= 10

Array [

namestringrequired

Possible values: Value must match regular expression ^X-[A-Za-z0-9-]+$

valuestringrequired

]

inboundWebhookUrl(string | null)<uri>nullable

inboundWebhookAuthTypestring

Possible values: [none, bearer, basic, hmac_sha256]

callerIdLookupWebhookEnabledboolean

Default value: false

callerIdLookupWebhookUrl(string | null)<uri>nullable

callerIdLookupWebhookAuthTypestring

Possible values: [none, bearer, basic, hmac_sha256]

callerIdLookupWebhookTimeoutMsinteger

Possible values: >= 250 and <= 5000

Default value: 1000

callerIdLookupWebhookFailureModestring

Possible values: [allow, block, failover]

Default value: allow

failoverDestinationModestring

sip_uri routes to a full SIP/SIPS URI. extension builds a SIP URI against the existing provider connection.

Possible values: [sip_uri, extension]

Default value: sip_uri

failoverExtensionstring | nullnullable

User, extension, DID, or SIP username to route over the existing provider connection when failoverDestinationMode is extension.

Examples:

Example 1

Example: 1001

Example 2

Example: +15551234567

failoverTransportstring | nullnullable

Optional transport override for generic SIP failover. Blank uses the SIP URI or provider transport.

Possible values: [TCP, UDP, TLS, null]

businessHoursOutsideDestinationModestring

Default outside-hours route: existing SIP provider connection, explicit SIP URI, or verified managed PSTN failover.

Possible values: [sip_connection, sip_uri, pstn_failover]

Default value: sip_connection

businessHoursOutsideExtensionstring | nullnullable

User, extension, DID, or SIP username to route over the existing SIP provider connection for outside-hours calls.

Examples:

Example 1

Example: 1001

Example 2

Example: +15551234567

businessHoursOutsideTransportstring | nullnullable

Optional transport override for the outside-hours SIP destination. Blank uses the provider or URI default.

Possible values: [TCP, UDP, TLS, null]

e164stringrequired

Possible values: non-empty and <= 80 characters, Value must match regular expression ^[+A-Za-z0-9_.-]+$

providerAliasesstring[]

Possible values: <= 30

trunkIdstring<uuid>required

nicknamestring

Possible values: non-empty

inboundAgentIdstring

Possible values: non-empty

inboundAgentVersioninteger

Possible values: >= 0

outboundAgentIdstring

Possible values: non-empty

outboundAgentVersioninteger

Possible values: >= 0

inboundAgents object[]

Possible values: <= 10

Array [

agentIdstringrequired

agentVersioninteger | string | nullnullable

weightnumberrequired

Possible values: >= 0 and <= 1

]

outboundAgents object[]

Possible values: <= 10

Array [

agentIdstringrequired

agentVersioninteger | string | nullnullable

weightnumberrequired

Possible values: >= 0 and <= 1

]

retellTransportstring

Possible values: [TCP, UDP, TLS]

Default value: TCP

routingModestring

Possible values: [imported_number, dial_to_sip]

Default value: imported_number

retellImportIdentifierModestring

Possible values: [private, provider_address]

Default value: provider_address

stripRetellPrefixboolean

Default value: true

PhoneNumberCreateRequest

{
  "retellConcurrencyCheckEnabled": true,
  "retellConcurrencyBurstAllowed": true,
  "failoverEnabled": true,
  "failoverDestination": "+15551234567@carrier.example.com",
  "businessHoursEnabled": true,
  "businessHoursTimezone": "America/New_York",
  "businessHoursSchedule": [
    {
      "days": [
        0
      ],
      "start": "string",
      "end": "string",
      "action": "retell",
      "destination": "afterhours@carrier.example.com"
    }
  ],
  "businessHoursRouteMode": "retell_open",
  "businessHoursOutsideDestination": "afterhours@carrier.example.com",
  "inboundRetellHeaders": [
    {
      "name": "string",
      "value": "string"
    }
  ],
  "inboundWebhookUrl": "string",
  "inboundWebhookAuthType": "none",
  "callerIdLookupWebhookEnabled": false,
  "callerIdLookupWebhookUrl": "string",
  "callerIdLookupWebhookAuthType": "none",
  "callerIdLookupWebhookTimeoutMs": 1000,
  "callerIdLookupWebhookFailureMode": "allow",
  "failoverDestinationMode": "sip_uri",
  "failoverExtension": "1001",
  "failoverTransport": "TCP",
  "businessHoursOutsideDestinationMode": "sip_connection",
  "businessHoursOutsideExtension": "1001",
  "businessHoursOutsideTransport": "TCP",
  "e164": "string",
  "providerAliases": [
    "string"
  ],
  "trunkId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "nickname": "string",
  "inboundAgentId": "string",
  "inboundAgentVersion": 0,
  "outboundAgentId": "string",
  "outboundAgentVersion": 0,
  "inboundAgents": [
    {
      "agentId": "string",
      "agentVersion": 0,
      "weight": 0
    }
  ],
  "outboundAgents": [
    {
      "agentId": "string",
      "agentVersion": 0,
      "weight": 0
    }
  ],
  "retellTransport": "TCP",
  "routingMode": "imported_number",
  "retellImportIdentifierMode": "provider_address",
  "stripRetellPrefix": true
}