Create Phone Number - SigmaMind AI

Authorizations

X-API-Key

string

header

required

Authenticate every request by passing your API key in the X-API-Key header. To get your key, go to Dashboard → API Keys and create or copy your Production API key.

Body

application/json

Request body to purchase and provision a new phone number through SigmaMind. Either phoneNumber or countryCode must be provided. Supply phoneNumber to purchase a specific number, or supply countryCode (with optional areaCode) to let the system auto-select an available number in that region.

friendlyName

string

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.

Maximum string length: 128

Example:

"Support Line - US"

countryCode

string

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').

Pattern: ^[A-Z]{2}$

Example:

"US"

areaCode

integer<int32>

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.

Required range: 100 <= x <= 99999

Example:

415

phoneNumber

string

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.

Pattern: ^\+[1-9][0-9]{6,14}$

Example:

"+14155552671"

inboundAgentId

string

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.

Maximum string length: 64

Example:

"awTw7UKhOsLGiDbt"

outboundAgentId

string

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.

Maximum string length: 64

Example:

"awTw7UKhOsLGiDbt"

outboundPhoneNumber

string

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.

Pattern: ^\+[1-9][0-9]{6,14}$

Example:

"+14155552671"

Response

Created

sipPhoneNumber

string

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

Example:

"+14155552671"

provider

enum<string>

The service provider associated with the phone number.

Available options:

twilio,

telnyx,

byo

Example:

"twilio"

inboundAgentId

string

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

Example:

"agent_D5D0p7TUs66TTAEAx"

outboundAgentId

string

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

Example:

"agent_D5D0p7TUs66TTAEAx"

outboundPhoneNumber

string

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

Example:

"+14155552671"

active

boolean

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

Example:

true

friendlyName

string

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

Example:

"Support Line - US"