Documentation

Getting started

What an account gives you, how credentials are issued, and the shortest path from nothing to a connected call.

What an account includes

One account carries everything: origination and termination, DID inventory, SMS and MMS, programmable routing, recording and transcription, hosted PBX, and AI Voice Agents. There are no feature tiers to buy into and no per-seat license to use the network. You turn on what you need and pay the published rate for the usage it generates.

Sub-accounts sit underneath the parent account and are how platform customers separate their own tenants. Each sub-account gets its own numbers, trunks, routing configuration, and CDR rollup, while rating and settlement stay at the parent. See sub-account rollups.

Credentials and environments

Credentials are issued during onboarding rather than from a self-serve form, because a trunk on a Tier 2 network is an authenticated path onto the PSTN. You receive three things: a SIP trunk hostname, either a SIP username and password or an IP allowlist entry, and an API bearer token scoped to your account.

Ask for a sandbox token at the same time. Sandbox accepts the same API calls, returns the same object shapes, and delivers the same webhooks, but numbers are reserved from a test pool and calls terminate to a test answering service instead of the PSTN. Build against sandbox, then swap the token and the trunk hostname.

Connecting your first trunk

Decide first whether you are authenticating by registration or by IP. Registration suits endpoints on dynamic addresses and small PBXs. IP authentication suits softswitches and anything carrying volume, because it removes the registration refresh from the failure surface. Both are described in registration and IP authentication.

Then point your system at the trunk hostname, allow the codecs you want, and place a test call to a number you control. A working Asterisk configuration is in the Asterisk example. If the first call fails, the SIP response code tells you which side rejected it; see reading SIP response codes.

Buying and assigning your first number

Search inventory by rate center, state, or prefix, reserve the number you want so nobody else takes it while you finish the flow, then buy it and assign it to a trunk or a routing target. All four steps are API calls, which is why most platform customers put number selection inside their own signup flow rather than in a support ticket.

Local voice DIDs start at $1.10 per month with a $0.40 one-time charge, toll-free at $1.50 per month, and vanity toll-free at $1.50 per month plus a $30 one-time reservation. Add Enhanced 911 before the number carries real traffic; see E911 and address records.

Placing your first call

You can originate two ways. Send an INVITE from your own softswitch over the trunk, which is what a PBX or dialer does, or call the API and let the network bridge both legs, which is what a platform without its own media stack does. The API route is documented in the API reference.

Set a From header that matches a DID on your account. Calls presenting a number you do not own are rejected, which is the single most common cause of a 403 on a new trunk. Internal traffic that stays on our network is free in both directions.

Go-live checklist

• Trunk authenticates, registers if applicable, and survives a restart of your own system.
• Outbound calls complete to landline, mobile, and toll-free destinations.
• Inbound calls reach the right target, including after your failover target takes over.
• DTMF is captured by whatever IVR the call lands in. See DTMF and media.
• E911 address records are in place for every DID that a person might dial 911 from.
• Recording, if you use it, is on at the right scope and the retention window matches your obligations.
• A webhook endpoint is receiving events and verifying signatures. See signature verification.
• Spend caps and velocity limits are set so a misconfiguration costs you a small number instead of a large one.

Back to contents

Numbers and porting

Inventory, DID types, E911, caller identity, and what actually happens between an LOA and a cutover.

Searching and reserving inventory

Search by rate center, state, NPA, prefix, or a pattern for vanity. Reserve holds a number for a short window so a user can finish a signup flow without losing it to another buyer, then buy converts the reservation and assigns the number to a trunk or routing target.

All of it is API-driven, and coverage spans local and toll-free numbers in more than 100 countries. Put the search in your own product and your users never see our name; provisioning becomes a step in your onboarding rather than an email to us.

DID types and what they cost

• Local voice. From $1.10 per month plus a $0.40 one-time charge.
• Local fax. From $1.99 per month.
• Toll-free voice. From $1.50 per month.
• Vanity toll-free. From $1.50 per month plus a $30 one-time reservation.

Inbound minutes are rated separately: $0.009 per minute on local DIDs and $0.027 on toll-free. Unlimited inbound plans are available on select DID types by request. The full card, with footnotes, is on the pricing page.

E911 and address records

Enhanced 911 is $1.50 per DID per month plus a $1.50 one-time charge, and it attaches a dispatchable address to the number so an emergency call reaches the right public safety answering point with a location attached. Provision it before the number carries traffic from a place where a person might dial 911.

Address records have to stay current. If a user moves a desk phone or a softphone to a new site, the record must follow, and that is your workflow to own because we cannot see it. Numbers used only for outbound automated dialing still need a valid address on file.

CNAM, directory listing, and caller identity

A CNAM dip on an inbound call is $0.008 per call and returns the calling name the originating carrier published. Setting the outbound caller ID name on your own numbers is free. A directory listing is $10 one time, and directory assistance calls to 411 are $0.99 each.

Caller name is not the same as caller reputation. Analytics services that label calls as spam make their own judgments from call patterns, and a clean CNAM record does not override them. Attestation and calling behavior are what move that; see recording and compliance.

The porting process

You send a Letter of Authorization and a recent bill. We pull the Customer Service Record from the losing carrier and compare it to the LOA before submitting, which means most rejections happen on our side, quietly, days before a cutover date exists. Once the port is accepted, the losing carrier issues a Firm Order Commitment date.

Cutover windows are chosen around your call volume rather than the losing carrier default. A clean simple local port typically runs seven to ten business days from a valid LOA; toll-free is usually faster. Partial ports move a subset of a block without stranding the rest of the range. Port state is exposed over the API so your own dashboard can show it.

Why ports get rejected

• The account name or service address on the LOA does not match the Customer Service Record, character for character.
• The billing telephone number is wrong, or the requested numbers include the BTN on a partial port.
• A pending order exists on the account at the losing carrier.
• The account has a port-out freeze or a PIN requirement that has not been satisfied.
• The numbers are in a different rate center than the LOA claims.

Send the most recent bill rather than a summary screen. It carries the exact account name, the BTN, and the service address in the form the losing carrier will check against.

Releasing numbers

Releasing a DID stops its monthly charge from the next billing cycle and returns it to inventory. Releases are not reversible once the number leaves your account, so scripted cleanup jobs should confirm the number is idle in CDRs before calling the endpoint.

Porting a number away is a different operation and starts at the gaining carrier, not here. We do not block port-outs; send the request through them and we will respond to the Customer Service Record request.

Back to contents

Messaging and 10DLC

Sending, registration, throughput, verification, consent, and why an accepted message is not a delivered message.

Sending and receiving

Long-code and toll-free SMS are $0.0075 to send and $0.0075 to receive. MMS is $0.02 each way. Inbound messages arrive at your webhook endpoint as message.received events; see the event catalog.

A successful send response means we accepted the message for delivery, nothing more. The delivery outcome arrives later as a separate event, which is the distinction that catches most new integrations; see delivery receipts.

Brand and campaign registration

Application-to-person traffic on long codes has to be registered. You register a brand, which identifies the business, then one or more campaigns, which describe what you actually send and how recipients consented to receive it. We prepare and submit the packet as part of onboarding rather than handing you a form.

The campaign description has to match the traffic. A campaign registered for appointment reminders that carries marketing content is the fastest route to filtering, and the filtering is silent: messages are accepted, billed by the sending path, and never delivered.

Throughput tiers and message rate

Your messages-per-second ceiling is a function of your brand vetting score and your campaign type, not a setting we can raise on request. Raising throughput means resubmitting vetting with better supporting information, which we will do with you.

Design for the ceiling. Queue on your side and send at a steady rate rather than bursting, because exceeding the per-second limit produces carrier-side throttling that looks like random delivery failure rather than a clean rejection.

Toll-free verification

Toll-free numbers used for messaging go through a separate verification process. Unverified toll-free traffic is heavily filtered, so verification is not optional if delivery matters. We prepare and submit the verification packet, including the opt-in flow evidence, which is the part that gets packets returned.

Have a real opt-in screenshot ready: the form, the checkbox, and the disclosure text as a recipient sees them. A description of the opt-in is not evidence of the opt-in.

Opt-out, STOP, and HELP

STOP, UNSTOP, START, and HELP keywords are handled at the number level and the resulting consent state is exposed over the API. Once a recipient is in a STOP state on a number, further messages to them from that number are blocked before they reach a carrier.

Consent state is per number, not per account, which matters when you rotate sending numbers. Read the state before you send rather than discovering it in a delivery receipt, and mirror it into your own system so your application does not keep queueing messages that will never leave.

Delivery receipts

A delivery receipt is the carrier answer about what happened to the message. It arrives as a message.delivered event, or as a failure with a reason code, and it can arrive seconds or minutes after the send. Treat the send response as queued and the receipt as the outcome.

If sends succeed and receipts never arrive, the problem is usually your webhook endpoint rather than the message path; see debugging deliveries. If receipts arrive as failures, the reason code distinguishes an invalid number from carrier filtering from a handset that is out of coverage.

MMS

MMS is $0.02 each way and carries images, audio, video, and longer text. Attachment size limits are set by the receiving carrier rather than by us, and the practical ceiling is lower than the documented one, so compress before sending if delivery rate matters more than fidelity.

Group messaging behaves differently across carriers and handsets. If your use case needs guaranteed one-to-one delivery semantics, send individual messages rather than a group thread.

Back to contents

Webhooks and events

How events reach you, what a payload looks like, and how to verify that it came from us.

Registering an endpoint

Register an HTTPS endpoint and subscribe it to the event types you want. You can register several endpoints and give each a different subscription, which is the clean way to separate a billing consumer from a call-flow consumer without one team breaking the other.

Return a 2xx quickly. Do the work afterward, out of band. An endpoint that does its processing inline and answers in eight seconds will be retried while it is still working, and you will process the same event twice.

Payload shape

Every delivery is a POST with a JSON body. The envelope is identical across event types: an event id, a type, a creation timestamp, the account, and a data object whose shape depends on the type. A call.completed delivery looks like this.

Fields are added over time and are never removed without notice, so parse defensively and ignore keys you do not recognize.

Event catalog

• call.initiated and call.answered for live call progress.
• call.completed when the leg ends, carrying duration, cause, and the applied rate.
• recording.available when media is stored and fetchable.
• transcription.available when text, speaker labels, and timestamps are ready.
• message.received for inbound SMS and MMS.
• message.delivered for carrier delivery receipts, including failures with a reason code.
• number.ported when a port completes and the number is live on our network.
• bid.won when a buyer takes a call in real-time bidding.

The same catalog is listed with its use in the API reference.

Signature verification

Each delivery carries an X-Solvedtele-Signature header holding a timestamp and an HMAC over the timestamp and the raw request body, keyed with your endpoint signing secret. Compute the same HMAC over the bytes you received and compare in constant time.

Verify against the raw body, before any JSON parsing or re-serialization, because a reordered key changes the bytes and breaks the comparison. Reject deliveries whose timestamp is outside a tolerance window, typically five minutes, so a captured request cannot be replayed at you later.

Retries and ordering

Non-2xx responses and timeouts are retried with exponential backoff. That makes at-least-once delivery the contract, so consumers must be idempotent: key on the event id and discard one you have already processed.

Ordering is not guaranteed. A recording.available event can arrive before the call.completed event for the same call. Reconcile on the call id and the timestamps in the payload rather than on arrival order.

Debugging deliveries

Start by confirming the endpoint is reachable from the public internet over TLS with a valid certificate chain, including intermediates. A certificate that a browser accepts because it caches an intermediate will still fail a server-side client.

Then check the response code and the response time in your own access log. The three recurring causes of missing events are a firewall rule, an endpoint that answers slower than the delivery timeout, and a signature check comparing against a re-serialized body.

Back to contents

AI Voice Agents

Autonomous voice agents on rails built for machine turn-taking, billed at $0.10 per minute of talk time.

Creating an agent

An agent is a configuration: the instructions that define its task, the voice it speaks with, the tools it is allowed to call, and the conditions under which it hands off to a human. Create it once over the API and reference it by id when you start sessions.

Write the handoff conditions before you write the script. An agent that cannot recognize when it is out of its depth produces the worst calls on the platform, and the transfer path is what turns that from a failure into a routed call.

Starting a session

A session binds an agent to a call. Start one outbound, in which case the network places the call and connects the agent when it is answered, or attach one to an inbound call arriving on a DID or out of a queue. Either way the session gets a session id that ties it to the CDR and to any recording.

Sessions can be listed and inspected after the fact, so a conversation that went wrong is reviewable with the same tooling as a human call.

The latency budget

A natural turn leaves a few hundred milliseconds between a person finishing and a reply starting. That budget has to cover speech recognition, inference, speech synthesis, and the network in both directions, which is why the media path is treated as a product rather than as plumbing.

Protect the budget where you control it. Keep tool calls fast or make them asynchronous, prefer uncompressed audio in, and keep prompts short enough that the first token is not waiting on a long context; see codecs and transcoding.

Turn detection and barge-in

Turn detection decides when the caller has finished speaking. Too eager and the agent interrupts; too patient and it feels slow. Barge-in lets a caller cut the agent off mid-sentence, which people do constantly and which an agent that ignores it will lose the call over.

Both depend on a clean, symmetric media path. Asymmetric RTP and aggressive comfort noise are the usual causes of an agent that talks over people; see DTMF and media.

Warm transfer to a human

An agent can transfer to a queue, to a specific target, or into the routing engine to be treated like any other call, including real-time bidding. The conversation context travels with the transfer so the person who picks up is not starting from nothing.

Route the transfer through the same skills and license rules a human-originated call would use. An agent handing a licensed-product call to an unlicensed producer is the same compliance problem it would be without the agent; see skills and state license routing.

What $0.10 per minute covers

The agent rate is $0.10 per minute of talk time and covers the managed agent itself. Standard PSTN rates apply to the underlying connectivity when you use the network without the agent product, and recording, transcription, and the analysis services rate separately at their published rates.

You do not have to use agents to use the network. Connectivity, numbers, messaging, routing, PBX, and recording all stand on their own; the agent is an optional product on top. Volume and platform pricing is quoted.

Back to contents