Skip to main content

PhoneNumber

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: 1001
    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: 1001
    businessHoursOutsideTransportstring | nullnullable

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

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

    idstring<uuid>
    trunkIdstring<uuid>
    e164string

    Phone number or SIP user imported to Retell.

    providerAliasesstring[]
    retellImportIdentifierstring
    routingModestring

    Possible values: [imported_number, dial_to_sip]

    enabledboolean
    inboundEnabledboolean
    outboundEnabledboolean
    pstnFailoverEnabledboolean
    pstnFailoverDestinationstring | nullnullable

    Verified US PSTN failover forwarding destination.

    pstnFailoverVerifiedAt(string | null)<date-time>nullable
    pstnFailoverVerificationStatusstring

    Possible values: [not_configured, pending, verified, failed, expired]

    sipHeaderMappings object[]

    Possible values: <= 10

  • Array [
    • providerHeaderstringrequired

    Header name received from or written toward the SIP provider.

    retellHeaderstringrequired

    Retell-visible X-* or P-Asserted-Identity header.

    Possible values: Value must match regular expression ^(X-[A-Za-z0-9_-]+|P-Asserted-Identity)$

    directionstringrequired

    Possible values: [inbound, bidirectional]

  • ]
    • retellWorkspaceAssignments object[]

    Additional Retell workspace imports and agent assignments for this number.

  • Array [
    • idstring<uuid>
    phoneNumberIdstring<uuid>
    retellWorkspaceIdstring<uuid>
    friendlyNamestring | nullnullable
    retellImportIdentifierstring
    inboundAgents object[]
  • Array [
    • agentIdstringrequired
    agentVersioninteger | string | nullnullable
    weightnumberrequired

    Possible values: >= 0 and <= 1

  • ]
    • failoverAgents object[]
  • Array [
    • agentIdstringrequired
    agentVersioninteger | string | nullnullable
    weightnumberrequired

    Possible values: >= 0 and <= 1

  • ]
    • failoverEnabledboolean
    enabledboolean
    retellImportStatusstring
    retellLastErrorstring | nullnullable
    workspace object
    anyOf
    idstring<uuid>
    friendlyNamestring
    importPrefixstring

    Prefix used when importing the same SIP number into this Retell workspace.

    tokenFirst6string | nullnullable
    tokenLast4string | nullnullable
    statusstring
    validatedAt(string | null)<date-time>nullable
    lastErrorstring | nullnullable
    enabledboolean
    monthlyPriceCentsinteger

    Current additional-workspace amount from the active BillingPriceConfig catalog.

    createdAtstring<date-time>
    updatedAtstring<date-time>
    createdAtstring<date-time>
    updatedAtstring<date-time>
  • ]
    • PhoneNumber
    {
      "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",
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "trunkId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "e164": "string",
      "providerAliases": [
        "string"
      ],
      "retellImportIdentifier": "string",
      "routingMode": "imported_number",
      "enabled": true,
      "inboundEnabled": true,
      "outboundEnabled": true,
      "pstnFailoverEnabled": true,
      "pstnFailoverDestination": "string",
      "pstnFailoverVerifiedAt": "2024-07-29T15:51:28.071Z",
      "pstnFailoverVerificationStatus": "not_configured",
      "sipHeaderMappings": [
        {
          "providerHeader": "string",
          "retellHeader": "string",
          "direction": "inbound"
        }
      ],
      "retellWorkspaceAssignments": [
        {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "phoneNumberId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "retellWorkspaceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "friendlyName": "string",
          "retellImportIdentifier": "string",
          "inboundAgents": [
            {
              "agentId": "string",
              "agentVersion": 0,
              "weight": 0
            }
          ],
          "failoverAgents": [
            {
              "agentId": "string",
              "agentVersion": 0,
              "weight": 0
            }
          ],
          "failoverEnabled": true,
          "enabled": true,
          "retellImportStatus": "string",
          "retellLastError": "string",
          "workspace": {
            "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "friendlyName": "string",
            "importPrefix": "string",
            "tokenFirst6": "string",
            "tokenLast4": "string",
            "status": "string",
            "validatedAt": "2024-07-29T15:51:28.071Z",
            "lastError": "string",
            "enabled": true,
            "monthlyPriceCents": 0,
            "createdAt": "2024-07-29T15:51:28.071Z",
            "updatedAt": "2024-07-29T15:51:28.071Z"
          },
          "createdAt": "2024-07-29T15:51:28.071Z",
          "updatedAt": "2024-07-29T15:51:28.071Z"
        }
      ]
    }