v1

latestOpenAPI 3.0.12026-07-226992320.0 KB

Phone Numbers

Create Phone Number

Purchases and provisions a new phone number for your account. Provide a specific phoneNumber in +E.164 format, or a countryCode (optionally areaCode) to auto-select one. Returns the provisioned number, including its sipPhoneNumber for subsequent get, update, and delete calls.

post/v1/phone-numbers

Request body

friendlyNamestring

Human-readable label for this phone number. Used to identify it in listings and dashboards. If omitted, the number itself is used as the display name.

countryCodestring

ISO 3166-1 alpha-2 country code that determines which country the number is purchased from. Required when phoneNumber is not provided — the system selects an available number in this country. Ignored when phoneNumber is explicitly specified. Must be exactly two uppercase letters (e.g., 'US', 'IN', 'GB').

areaCodeinteger

Preferred area or region code used to narrow down number selection within the specified country. Optional — only considered when countryCode is provided and phoneNumber is omitted. If no number is available in this area code, the system selects the nearest available match.

phoneNumberstring

Specific phone number to purchase, in +E.164 format (e.g., +14155552671). When provided, the system attempts to purchase exactly this number. Either this field or countryCode must be supplied — both cannot be omitted. If omitted, the system auto-selects an available number based on countryCode and areaCode.

inboundAgentIdstring

Unique identifier of the agent that will handle inbound calls received on this number. When a call arrives at this number, it is routed to this agent automatically. If omitted, inbound calls will not be handled by an agent until one is assigned.

outboundAgentIdstring

Unique identifier of the agent that will handle outbound calls made from this number. When this number is used as the caller ID in an outbound call, this agent manages the conversation. If omitted, the agent must be specified explicitly at call creation time.

outboundPhoneNumberstring

Default destination number dialled during test calls initiated from this phone number, in +E.164 format. Used to verify the number is working correctly without targeting a real contact. Must be a valid number capable of receiving calls. If omitted, test calls cannot be placed until this is configured.

Example request

{
  "friendlyName": "Support Line - US",
  "countryCode": "US",
  "areaCode": 415,
  "phoneNumber": "+14155552671",
  "inboundAgentId": "awTw7UKhOsLGiDbt",
  "outboundAgentId": "awTw7UKhOsLGiDbt",
  "outboundPhoneNumber": "+14155552671"
}

Response

Created

sipPhoneNumberstring

The caller’s phone number in +E.164 format. This number must be obtained from SigmaMind or configured using SIP trunking with SigmaMind.

provider'twilio' | 'telnyx' | 'byo'

The service provider associated with the phone number.

inboundAgentIdstring

Default agent ID assigned to handle inbound calls for this phone number.

outboundAgentIdstring

Default agent ID assigned to handle outbound calls for this phone number.

outboundPhoneNumberstring

The default outbound phone number of the callee, represented in +E.164 format

activeboolean

Indicates whether the phone number is currently active and available for use.

friendlyNamestring

A user-friendly display name assigned to this phone number.

Example response

{
  "sipPhoneNumber": "+14155552671",
  "provider": "twilio",
  "inboundAgentId": "agent_D5D0p7TUs66TTAEAx",
  "outboundAgentId": "agent_D5D0p7TUs66TTAEAx",
  "outboundPhoneNumber": "+14155552671",
  "active": true,
  "friendlyName": "Support Line - US"
}