# Widely Mobile — product and API knowledge Canonical JSON: https://api.swiftcom.cc/api/public/widely-knowledge OpenAPI: https://api.swiftcom.cc/api/public/widely-knowledge.openapi.json Human-readable: https://widely-mobile.com/developers llms.txt: https://widely-mobile.com/llms.txt ## Product facts - 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. 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. Use these canonical destinations when telling the customer where to go. Do not invent routes. Prefer the matching destination for the topic. Channel unknown: include Nav steps and the Absolute URL. | Key | Label | Path | Absolute URL | Nav steps | |-----|-------|------|--------------|-----------| | profile | Profile | `/profile` | https://webapp.widely-mobile.com/profile | tap your profile picture (top right) → Profile | | account | Account | `/account` | https://webapp.widely-mobile.com/account | tap your profile picture (top right) or Home → All settings → Account → Account | | phone_numbers | Phone Numbers | `/did` | https://webapp.widely-mobile.com/did | Home tab → Phone numbers, or tap your profile picture (top right) or Home → All settings → Phone Numbers | | balance | Balance & Payments | `/balance` | https://webapp.widely-mobile.com/balance | Home tab → Balance, or tap your profile picture (top right) or Home → All settings → Balance & Payments | | balance_topup | Top Up | `/balance/topup` | https://webapp.widely-mobile.com/balance/topup | Home → Balance → Top Up, or tap your profile picture (top right) or Home → All settings → Balance & Payments → Top Up | | caller_ids | Caller IDs | `/callerid` | https://webapp.widely-mobile.com/callerid | Home tab → Caller ID, or tap your profile picture (top right) or Home → All settings → Caller IDs | | esim | Mobile data (eSIM) | `/esim/oneglobal` | https://webapp.widely-mobile.com/esim/oneglobal | Home tab → Mobile data (eSIM), or tap your profile picture (top right) or Home → All settings → Mobile data (eSIM) | | call_forwarding | Receive SIM calls | `/call-forwarding` | https://webapp.widely-mobile.com/call-forwarding | Home tab → Receive SIM calls, or tap your profile picture (top right) or Home → All settings → SIM Call Forwarding | | rate_checker | Rate Checker | `/rate-checker` | https://webapp.widely-mobile.com/rate-checker | tap your profile picture (top right) or Home → All settings → Rate Checker (or from Mobile data (eSIM)) | | membership | Your plan | `/settings/membership` | https://webapp.widely-mobile.com/settings/membership | tap your profile picture (top right) or Home → All settings → Account → Your plan | | call_recording | Call recording | `/settings/call-recording` | https://webapp.widely-mobile.com/settings/call-recording | tap your profile picture (top right) or Home → All settings → Calls and messages → Call services → Call recording | | voicemail | Voicemail | `/settings/voicemail` | https://webapp.widely-mobile.com/settings/voicemail | Home → Search → Voicemail | | language | Language | `/settings/language` | https://webapp.widely-mobile.com/settings/language | tap your profile picture (top right) or Home → All settings → App → Language | | notifications | Notifications | `/settings/notifications` | https://webapp.widely-mobile.com/settings/notifications | tap your profile picture (top right) or Home → All settings → App → Notifications | | travel_ready | Ready to travel | `/travel-ready` | https://webapp.widely-mobile.com/travel-ready | Home tab → Ready to travel (eSIM, Receive SIM calls, and wallet on this phone) | | support | Help & Support | `/settings/support` | https://webapp.widely-mobile.com/settings/support | tap your profile picture (top right) or Home → All settings → Help & Support | | sip_trunks | SIP trunks | `/settings/sip-trunks` | https://webapp.widely-mobile.com/settings/sip-trunks | tap your profile picture (top right) or Home → All settings → Calls and messages → Connectivity → SIP trunks | | api_keys | API keys | `/settings/api-keys` | https://webapp.widely-mobile.com/settings/api-keys | tap your profile picture (top right) or Home → All settings → Calls and messages → Connectivity → API keys | ## Auth and CRUD Authorization: Bearer . Issued at login. JWT identity is User.id — never use it as consumer_user_id. Authorization: Bearer pk_live_ (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// and GET/PUT/DELETE /api//. 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 - 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. ## 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] fields: client_shell - 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