phone numbers
Provision managed numbers, import SIP trunk numbers, and manage phone-number business verification.
speko.phoneNumbers manages caller IDs and inbound numbers for the authenticated organization.
const numbers = await speko.phoneNumbers.list();
const imported = await speko.phoneNumbers.importSipTrunk({
e164: '+12015550199',
sipConnectionInstallationId: '00000000-0000-4000-8000-000000000010',
direction: 'both',
agentId: 'agent_123',
});Managed number purchase is the US-number path and requires phone-number business verification plus sufficient credits. For numbers you already own, or non-US carrier paths, import a SIP trunk number and link it to an agent.
Inbound routing is controlled by direction, agentId, and dispatchMetadataTemplate. A number that allows inbound calls must have either a linked agent or a dispatch metadata template. Linked agents hydrate the call prompt, routing intent, provider preferences, tools, and lifecycle webhooks; templates add static or token-substituted metadata.
Methods
| Method | Description |
|---|---|
list() | List all organization phone numbers. |
searchAvailable(params?) | Search platform-managed numbers available to buy. |
get(id) | Fetch one phone-number row. |
create(params) | Buy a managed number. Requires business verification and sufficient credits. |
importSipTrunk(params) | Register a customer-owned SIP-trunk number. |
update(id, params) | Update direction, metadata template, label, or linked agent. |
delete(id) | Release or unregister a phone number. |
getKyb() | Read business verification state. |
saveKybDraft(params) | Save a business verification draft. |
submitKyb(params) | Submit business verification for review. |
PhoneNumberRow
| Field | Type | Description |
|---|---|---|
id | string | Speko phone-number id. |
e164 | string | E.164 phone number. |
source | 'managed' | 'sip_trunk' | Platform-managed number or customer SIP-trunk number. |
providerResourceId | string | null | Platform-neutral managed provider id. |
sipConnectionInstallationId | string | null | Installed SIP connection used for productized SIP imports. |
sipProviderName | string | null | Display label for the SIP provider/account. |
direction | 'inbound' | 'outbound' | 'both' | Allowed call direction. |
agentId | string | null | Agent linked for inbound calls. |
dispatchMetadataTemplate | Record<string, unknown> | null | Optional template merged into inbound session metadata. Supports tokens such as {{callerNumber}}, {{dialedNumber}}, and {{forwardedFromNumber}}. |
setupStatus | PhoneNumberSetupStatus | Readiness state for inbound/outbound use. |
sms10dlcProfileId, smsCampaignId, smsAssignmentStatus | nullable | SMS assignment state when applicable. |
Pass null to update() for label, dispatchMetadataTemplate, or agentId to clear them.
Inbound forwarding
When a carrier forwards a call, Speko attempts to normalize the original forwarding source from provider fields and SIP headers. The value is available as forwardedFromNumber in call metadata and as forwarded_from_number in pre-call webhooks.
Business verification
Managed phone-number purchases are gated by phone-number KYB.
const kyb = await speko.phoneNumbers.getKyb();
await speko.phoneNumbers.submitKyb({
businessProfile: {
legalName: 'Acme Inc.',
displayName: 'Acme',
entityType: 'Corporation',
country: 'US',
website: 'https://example.com',
address: {
street: '1 Market St',
city: 'San Francisco',
state: 'CA',
postalCode: '94105',
country: 'US',
},
useCase: 'Customer support calls and appointment reminders.',
expectedUsage: '500 calls per month in the US.',
},
authorizedRepresentative: {
name: 'Ava Martinez',
title: 'Operations Lead',
email: 'ava@example.com',
phone: '+12015551234',
},
attestationAccepted: true,
});