Widely Mobile

Canonical machine-readable spec: JSON · OpenAPI · Markdown · llms.txt. Brand-domain JSON: https://widely-mobile.com/widely-knowledge.

What we are

• Widely is a consumer communications app: your SIM number and/or a Widely number, on iOS, Android, web, and desktop.
• Receive SIM calls: people call your SIM; it rings in Widely.
• Free, Pro, and Business are platform capability plans. New accounts start Free with a 30-day Pro trial.
• Numbers, calls, messages, data, and extra channel capacity stay pay as you go on every plan. A platform tier does not include a DID, minutes, messages, data, or wallet credit.
• Mobile data is a pay-as-you-go eSIM from the wallet — not country bundles or a prepaid pack shop.
• Local numbers so family abroad can dial local; you answer in-app.
• Person-to-person SMS only — not bulk, marketing campaigns, or automated business notifications.

What we are not

• Not an Airalo clone or a prepaid country-pack shop.
• Not a PBX / carrier white-label product advertised on the consumer homepage.
• Not a bulk SMS platform.
• Do not advertise the retired Essential plan.
• Do not describe kosher as a product feature (it is an edition).
• Settings are opened from the profile picture or Home → All settings — never a More tab.

Numbers, calls, messages, data, and extra channel capacity stay pay as you go on every plan. A platform tier does not include a DID, minutes, messages, data, or wallet credit.

Auth and CRUD

• Authorization: Bearer <access_jwt>. Issued at login. JWT identity is User.id — never use it as consumer_user_id.
• Authorization: Bearer pk_live_<hex> (or pk_test_). Create keys via CRUD ApiKey; the full key is shown once. Hashed at rest (key_hash is never returned).
• Every consumer-scoped request must pass consumer_user_id or consumer_id as a query param (and in JSON bodies that mutate). The server does not infer CU from the JWT.
• Generic entity routes: GET/POST /api/<entity>/ and GET/PUT/DELETE /api/<entity>/<id>. Entity name is lowercased (SipTrunk → /api/siptrunk/). Nested members use ?include= or model_api_includes defaults. Writes that charge money need confirm + quoted_charge (never a single tap).
• 409 {"error":"platform_upgrade_required", ...} when a Free account hits a Pro/Business capability. Open in-app membership — do not send users to the marketing site to pay.
• A consumer User PATCH can return 200 and store nothing for restricted fields. Profile writes go through PUT /api/user_routes/update-profile; identity email/phone are OTP-owned.

SIP trunk / PBX integration

• Create a SipTrunk via POST /api/siptrunk/ (name, ip_address of your PBX, port, transport_protocol, channel_count ≥ 2).
• Or create it in the app: Connectivity → SIP trunks.
• Point the PBX at sip-uk.swiftcom.cc port 5060 (UDP unless the trunk says otherwise).
• Use sip_username / sip_password from the create response when registration_mode needs credentials. ip_only trunks authenticate on source IP.
• Extra concurrent channels are an account SIP channel pack: GET /api/membership/sip-channel-pool/quote then POST with confirm=true and quoted_charge.
• Do not invent per-minute trunk pricing — the pipe is channel-based; calls remain PAYG on the wallet.

In-app destinations

• Profile — tap your profile picture (top right) → Profile
• Account — tap your profile picture (top right) or Home → All settings → Account → Account
• Phone Numbers — Home tab → Phone numbers, or tap your profile picture (top right) or Home → All settings → Phone Numbers
• Balance & Payments — Home tab → Balance, or tap your profile picture (top right) or Home → All settings → Balance & Payments
• Top Up — Home → Balance → Top Up, or tap your profile picture (top right) or Home → All settings → Balance & Payments → Top Up
• Caller IDs — Home tab → Caller ID, or tap your profile picture (top right) or Home → All settings → Caller IDs
• Mobile data (eSIM) — Home tab → Mobile data (eSIM), or tap your profile picture (top right) or Home → All settings → Mobile data (eSIM)
• Receive SIM calls — Home tab → Receive SIM calls, or tap your profile picture (top right) or Home → All settings → SIM Call Forwarding
• Rate Checker — tap your profile picture (top right) or Home → All settings → Rate Checker (or from Mobile data (eSIM))
• Your plan — tap your profile picture (top right) or Home → All settings → Account → Your plan
• Call recording — tap your profile picture (top right) or Home → All settings → Calls and messages → Call services → Call recording
• Voicemail — Home → Search → Voicemail
• Language — tap your profile picture (top right) or Home → All settings → App → Language
• Notifications — tap your profile picture (top right) or Home → All settings → App → Notifications
• Ready to travel — Home tab → Ready to travel (eSIM, Receive SIM calls, and wallet on this phone)
• Help & Support — tap your profile picture (top right) or Home → All settings → Help & Support
• SIP trunks — tap your profile picture (top right) or Home → All settings → Calls and messages → Connectivity → SIP trunks
• API keys — tap your profile picture (top right) or Home → All settings → Calls and messages → Connectivity → API keys

Entities

• Account /api/account/ [list,get,create,update,delete]
• ApiKey /api/apikey/ [list,get,create,update,delete]
• BroadcastList /api/broadcastlist/ [list,get,create,update,delete]
• CallQueue /api/callqueue/ [list,get,create,update,delete]
• CallerID /api/callerid/ [list,get,create,update,delete]
• ConsumerUser /api/consumeruser/ [list,get,create,update,delete]
• ConsumerUserInvite /api/consumeruserinvite/ [list,get,create,update,delete]
• DID /api/did/ [list,get,create,update,delete]
• Extension /api/extension/ [list,get,create,update,delete]
• IVRConfig /api/ivrconfig/ [list,get,create,update,delete]
• LCR /api/lcr/ [list,get,create,update,delete]
• LCRTrunk /api/lcrtrunk/ [list,get,create,update,delete]
• Rate /api/rate/ [list,get,create,update,delete]
• RateSheet /api/ratesheet/ [list,get,create,update,delete]
• RoutingRule /api/routingrule/ [list,get,create,update,delete]
• SharedTrunk /api/sharedtrunk/ [list,get,create,update,delete]
• SipTrunk /api/siptrunk/ [list,get,create,update,delete]
• TimeGroup /api/timegroup/ [list,get,create,update,delete]
• User /api/user/ [list,get,create,update,delete]
• VerifiedNumber /api/verifiednumber/ [list,get,create,update,delete]

Custom routes

• GET /api/membership/plans — Platform tiers with capabilities for the signed-in account
• GET /api/membership/plans/public — Public Free/Pro/Business cards (no session)
• POST /api/membership/upgrade — Upgrade platform tier; debit the Consumer wallet
• POST /api/membership/downgrade — Schedule a tier downgrade at period end
• GET /api/membership/sip-channel-pool — Shared SIP channel pack capacity for the account
• GET /api/membership/sip-channel-pool/quote — Read-only price for a SIP channel pack change
• POST /api/membership/sip-channel-pool — Commit SIP pack change: confirm=true plus quoted_charge echo
• GET /api/membership/channel-quote — Read-only price for extra DID channels
• GET /api/balance_and_payment_routes/get-balance — Wallet available_balance and currency
• GET /api/pricing/public/data-rate-card — PAYG eSIM rate card (query currency, country_code)
• POST /api/pricing/public/estimate-data-cost — Estimate PAYG data cost for country + GB
• POST /api/pricing/public/check-call-rate — Indicative per-minute call rate
• GET /api/pricing/public/did-rates — Indicative DID monthly/setup rates
• POST /api/voip/check-rate — Signed-in rate checker (same engine as the app)
• POST /api/sim_orders/sims/purchase — Provision a PAYG eSIM (wallet debit; install-first / platform cap apply)
• POST /api/call_forwarding/setup_call_forwarding — Start Receive SIM calls for a verified number
• POST /api/call_forwarding/test_forwarding — Place the verification call used to prove SIM forwarding