#Phone numbers and calling

#Search and buy

bash

curl https://api.mittis.ai/v1/numbers/search \
  -H "Authorization: Bearer $MITTIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "local", "areaCode": "804", "capabilities": ["sms", "voice"] }'

curl https://api.mittis.ai/v1/numbers/buy \
  -H "Authorization: Bearer $MITTIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phoneNumber": "+15555550123" }'

type is local (default, needs areaCode) or tollfree. You can also filter by locality, contains (1 to 7 digits) and capabilities (sms, mms, voice). List your numbers with GET /v1/numbers. Release one with POST /v1/numbers/{id}/release.

In the SDK: mittis.numbers.search({ areaCode: '415' }) and mittis.numbers.buy(phoneNumber).

#Texting from a number

Local numbers send through a registered 10DLC campaign. Attach a number with POST /v1/numbers/{id}/assign once the campaign is approved. See 10DLC registration.
Toll-free numbers use toll-free verification instead: submit it with POST /v1/numbers/{id}/verify-tollfree. The status moves pending, then verified, rejected or action_required.

#Port in an existing number

Check portability with POST /v1/ports/check, then open a request with POST /v1/ports, attach the letter of authorization and documents, and submit with POST /v1/ports/{id}/submit. Follow progress with GET /v1/ports/{id}. POST /v1/ports accepts an Idempotency-Key.

#Route inbound calls

Set where calls to a number ring with PUT /v1/numbers/{id}/route. A destination is a phone number (pstn), a SIP URI (sip), or one of your softphone devices (webrtc). The PUT replaces the whole route: omitted fields fall back to defaults.

bash

curl -X PUT https://api.mittis.ai/v1/numbers/$NUMBER_ID/route \
  -H "Authorization: Bearer $MITTIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "destinationType": "pstn", "destination": "+14155551234", "ringTimeoutSecs": 25 }'

For several destinations use destinations with a ringMode of simultaneous (default), sequential or staged. Per-route options include recordCalls, liveTranscription, voicemailEnabled and voicemailGreeting, and callerIdMode (caller or business). Ring timeout is 5 to 120 seconds.

In the SDK: mittis.numbers.setRoute(id, { destinationType: 'pstn', destination: '+14155551234' }).

#Calls, recordings and voicemail

GET /v1/calls lists calls; filter with status (for example missed) and direction. GET /v1/calls/{id} returns one, GET /v1/calls/{id}/recording its recording when recording was on, and POST /v1/calls/{id}/transfer hands a connected call to a softphone device or an external number.
GET /v1/voicemails lists captured voicemails with transcripts; GET /v1/voicemails/{id}/audio returns the audio.
/v1/blocked-numbers manages the inbound call blocklist.
Events: call.ringing, call.completed (carries answeredDevice when a softphone answered), call.missed, voicemail.received, call.transcript. See the webhook catalog.

#Browser and mobile softphones

Mittis is the control plane for softphones; media flows directly between the device and the carrier network, never through Mittis.

Register a device with POST /v1/webrtc/devices (idempotent per user and label).
Mint a short-lived login token with POST /v1/webrtc/devices/{id}/token. There is no SIP password on the client: re-mint the token when registration fails.
Send presence heartbeats with POST /v1/webrtc/devices/{id}/presence (online roughly every 20 seconds while registered, offline when the page hides). A device with a stale heartbeat is skipped when a ring wave dials.
Point a number's route at the device with a webrtc destination (the device id).
Answering needs no Mittis call: accept the call in the client, and Mittis learns of it from the carrier.
To place an outbound call, POST /v1/webrtc/calls: Mittis rings the device, auto-answers it, then dials the callee and bridges them. from must be one of your voice numbers.

call.ringing is the push-wake signal for backgrounded apps. Read the receiver rules before relying on it.