{"openapi":"3.1.0","info":{"title":"Kazee Phone API","version":"0.1.0","description":"Everything a person can do in Kazee Phone (their line and devices, calls, the phonebook, and the organisation's Phone administration) as plain HTTPS calls that answer in JSON.\n\n**Sign in.** Send `Authorization: Bearer <token>` with every call. The token comes from Kazee sign-in, and the person must have access to Kazee Phone in Kazee Central. Each call lists the permission it needs; calls marked *any signed-in member* need only that access. Your organisation comes from the token, so calls never ask for it.\n\n**People, not apps.** The calls in *Calls* and the push-token calls act only for a person's own session: an app's service token or a bot on its own key is refused with `403 person_required`. A bot acting on its owner's pass is refused (`403`, `askFirst: true`) on anything that deletes or changes who has Phone access.\n\n**IDs and dates.** People and organisations are Kazee Central IDs (24 hex characters, e.g. `65f1c0ffee0000000000a1b2`); Phone's own records use UUIDs. Phone numbers are E.164 (`+254712345678`). Dates are ISO 8601 in UTC, e.g. `2026-10-20T09:00:00.000Z`.\n\n**Errors.** A call that fails answers with a 4xx or 5xx status and `{ \"success\": false, \"error\": \"invalid_identifier\", \"code\": \"invalid_identifier\" }`: `error` and `code` hold the same short code. A missing or empty required input answers `400` with `{ \"error\": \"Missing required field: number\" }`.\n\n**For bots.** This page is built from the Kazee Phone code itself. The raw file is at `/api/swagger`."},"tags":[{"name":"My phone","description":"Your line and what you may do with it, your recent calls, the organisation's extension directory and your preferences."},{"name":"Devices","description":"The devices that receive your calls: taking your line on a device, keeping it, letting it go, and the push token that wakes Kazee Phone for Android."},{"name":"Calls","description":"Who is calling, filing notes and outcomes on the CRM call you are on, and starting calls from a browser or another device."},{"name":"Contacts","description":"The organisation's phonebook (owned by Kazee Contacts) and your own starred contacts."},{"name":"Administration","description":"Phone setup for your organisation: its PBX domain, which person has which extension, new extensions, and ending a device's access."},{"name":"Android app","description":"Releases of Kazee Phone for Android, for its in-app updater."},{"name":"Account","description":"Who you are signed in as."},{"name":"Widgets","description":"Worked example of the data-access pattern, kept from the app template."}],"paths":{"/phone/contacts":{"get":{"tags":["Contacts"],"summary":"Search the phonebook","description":"The organisation's phonebook (owned by Kazee Contacts): active contacts that have at least one phone number, by name, up to 100, each marked when you starred it. Search by name or number; optionally only your starred ones. Needs contacts.read.\n\n**Permission:** `phone.contacts.read` (View Phone contacts).","operationId":"phoneContacts","parameters":[{"name":"favorites","in":"query","required":false,"schema":{"type":"string","enum":["true","false"],"default":"false"},"description":"\"true\" to list only the contacts you starred","example":"true"},{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":160,"default":""},"description":"Part of a name or number to look for (up to 160 characters); empty lists everyone","example":"acme"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"contacts":{"type":"array","items":{"type":"object","properties":{"partyId":{"type":"string","description":"The Contacts party ID"},"displayName":{"type":"string","description":"Name in Contacts"},"numbers":{"type":"array","items":{"type":"string"},"description":"Its phone and mobile numbers (up to 20)"},"favorite":{"type":"boolean","description":"True when you starred it"}}}}}},"example":{"contacts":[{"partyId":"par_0123456789abcdef0123456789abcdef","displayName":"Acme Supplies","numbers":["+254712345678","+254733000111"],"favorite":true}]}}}},"400":{"description":"invalid_filter: favorites is not true or false; invalid_search: q is over 160 characters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"organisation_mismatch: the token's organisation does not match the request's","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"phone_unavailable: something failed on Phone's side (database, Redis); try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["phone.contacts.read"]}],"x-required-scopes":["phone.contacts.read"]}},"/phone/me":{"get":{"tags":["My phone"],"summary":"Get my line","description":"Your own Phone line: your extension (or null when none is assigned), whether you may administer Phone, and whether every device of yours rings (ring-all). Any signed-in member may call it; it also records your display name in Phone's people list, which administrators pick from (it never re-enables a person Central has disabled).\n\n**Permission:** any signed-in member.","operationId":"phoneMe","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"phone":{"type":"object","properties":{"userId":{"type":"string","description":"Your Central person ID"},"organizationId":{"type":"string","description":"Your Central organisation ID"},"assignment":{"type":"object","properties":{"id":{"type":"string","description":"The assignment's ID (UUID)"},"extension":{"type":"string","description":"Your extension number (2 to 10 digits)"},"domain":{"type":"string","description":"The PBX domain the extension lives on"},"displayName":{"type":"string"}},"description":"Your enabled extension, or null when you have none (or its PBX domain is disabled)"},"canAdminister":{"type":"boolean","description":"True when you hold the phone.admin permission (Administration calls)"},"ringAll":{"type":"boolean","description":"True when ring-all is live: each of your devices holds its own lease and all of them ring. Always present"}}}}},"example":{"phone":{"userId":"65f1c0ffee0000000000a1b2","organizationId":"65f1c0ffee0000000000e5f6","assignment":{"id":"0b7e2f4a-3c1d-4e5f-9a8b-7c6d5e4f3a21","extension":"1042","domain":"acme-ltd.pbx.kazee.africa","displayName":"Wanjiru Kamau"},"canAdminister":false,"ringAll":true}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"organisation_mismatch: the token's organisation does not match the request's","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"phone_unavailable: something failed on Phone's side (database, Redis); try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":[]}]}},"/phone/devices":{"get":{"tags":["Devices"],"summary":"List my receiving devices","description":"Your devices that are receiving calls now (an unexpired, unrevoked lease), newest first, up to 500. Any signed-in member may call it.\n\n**Permission:** any signed-in member.","operationId":"phoneDevices","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"devices":{"type":"array","items":{"type":"object","properties":{"deviceId":{"type":"string","description":"The device's own id (32 lowercase hex)"},"leaseId":{"type":"string","description":"Its current PBX lease (32 lowercase hex)"},"userId":{"type":"string","description":"Central ID of the person holding the lease"},"createdAt":{"type":"string","format":"date-time","description":"When the lease was taken"},"expiresAt":{"type":"string","format":"date-time","description":"When the lease ends unless renewed (about every 30 seconds; at most 120 seconds ahead)"},"kind":{"type":"string","description":"web (a browser), desktop (the desktop app) or android"},"label":{"type":"string","description":"\"browser\", \"desktop app\" or \"Android phone\""}}}}}},"example":{"devices":[{"deviceId":"3f9a1c0e5b7d4a2f8e6c1b0d9a7f5e3c","leaseId":"5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c0b","userId":"65f1c0ffee0000000000a1b2","createdAt":"2026-10-20T09:00:00.000Z","expiresAt":"2026-10-20T09:02:00.000Z","kind":"android","label":"Android phone"},{"deviceId":"7c5e3a1f9d8b6c4e2a0f8d6b4c2e0a9f","leaseId":"8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d","userId":"65f1c0ffee0000000000a1b2","createdAt":"2026-10-20T08:15:00.000Z","expiresAt":"2026-10-20T09:01:40.000Z","kind":"web","label":"browser"}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"organisation_mismatch: the token's organisation does not match the request's","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"phone_unavailable: something failed on Phone's side (database, Redis); try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":[]}]}},"/phone/directory":{"get":{"tags":["My phone"],"summary":"List the extension directory","description":"The organisation's extension directory: every enabled extension of a person who is not disabled, by extension number, up to 1000, with whether they have a receiving Phone device and are on do-not-disturb. Any signed-in member may call it.\n\n**Permission:** any signed-in member.","operationId":"phoneDirectory","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"directory":{"type":"array","items":{"type":"object","properties":{"extension":{"type":"string","description":"Extension number (2 to 10 digits)"},"displayName":{"type":"string","description":"Name on the extension"},"phoneEnabled":{"type":"boolean","description":"True when the person has a live Phone device lease now (may lag a lost device by up to 120 seconds; says nothing about desk phones)"},"doNotDisturb":{"type":"boolean","description":"True when the person has do-not-disturb on"}}}}}},"example":{"directory":[{"extension":"1042","displayName":"Wanjiru Kamau","phoneEnabled":true,"doNotDisturb":false},{"extension":"1043","displayName":"Otieno Mwangi","phoneEnabled":false,"doNotDisturb":true}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"organisation_mismatch: the token's organisation does not match the request's","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"phone_unavailable: something failed on Phone's side (database, Redis); try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":[]}]}},"/phone/history":{"get":{"tags":["My phone"],"summary":"List my recent calls","description":"Your last 100 calls, newest first: calls on extensions you held at the time, from the browser, the apps and your desk phone. Call details only, never recordings or transcripts. Any signed-in member may call it.\n\n**Permission:** any signed-in member.","operationId":"phoneHistory","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"calls":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The call row's ID (UUID)"},"direction":{"type":"string","description":"incoming, outgoing or internal"},"number":{"type":"string","description":"The other party's number or extension as the PBX gave it"},"displayName":{"type":"string","description":"The other party's name: the PBX's, else the Contacts name for partyId, else empty"},"partyId":{"type":"string","description":"The Contacts party of the other side, or null"},"startedAt":{"type":"string","format":"date-time","description":"When the call started"},"answeredAt":{"type":"string","format":"date-time","description":"When it was answered, or null"},"endedAt":{"type":"string","format":"date-time","description":"When it ended, or null while it lasts"},"outcome":{"type":"string","description":"answered, missed, busy or not answered; null while the call lasts"}}}}}},"example":{"calls":[{"id":"6c5b4a39-2817-4f06-a5e4-d3c2b1a09f8e","direction":"outgoing","number":"+254712345678","displayName":"Acme Supplies","partyId":"par_0123456789abcdef0123456789abcdef","startedAt":"2026-10-20T09:00:00.000Z","answeredAt":"2026-10-20T09:00:07.000Z","endedAt":"2026-10-20T09:04:31.000Z","outcome":"answered"},{"id":"7d6c5b4a-3928-4170-b6f5-e4d3c2b1a0f9","direction":"incoming","number":"+254733000111","displayName":"","partyId":null,"startedAt":"2026-10-20T08:41:12.000Z","answeredAt":null,"endedAt":"2026-10-20T08:41:40.000Z","outcome":"missed"}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"organisation_mismatch: the token's organisation does not match the request's","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"phone_unavailable: something failed on Phone's side (database, Redis); try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":[]}]}},"/phone/preferences":{"get":{"tags":["My phone"],"summary":"Get my preferences","description":"Your Phone preferences: today only do-not-disturb (false until you set it). Any signed-in member may call it.\n\n**Permission:** any signed-in member.","operationId":"phonePreferences","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"preferences":{"type":"object","properties":{"dnd":{"type":"boolean","description":"Do-not-disturb: when true, calls to your extension do not wake your Android app"}}}}},"example":{"preferences":{"dnd":false}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"organisation_mismatch: the token's organisation does not match the request's","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"phone_unavailable: something failed on Phone's side (database, Redis); try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":[]}]},"post":{"tags":["My phone"],"summary":"Set do-not-disturb","description":"Turns your do-not-disturb on or off and answers your preferences. The directory shows it to colleagues, and while it is on a call does not wake your Android app. Any signed-in member may call it.\n\n**Permission:** any signed-in member.","operationId":"phoneSetPreferences","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"dnd":{"type":"boolean","description":"true to turn do-not-disturb on, false to turn it off. Must be a JSON boolean in the body, not a string","examples":[true]}},"required":["dnd"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"preferences":{"type":"object","properties":{"dnd":{"type":"boolean","description":"Your do-not-disturb, as now saved"}}}}},"example":{"preferences":{"dnd":true}}}}},"400":{"description":"invalid_dnd: dnd is not a JSON boolean (the strings \"true\" and \"false\" are refused)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"organisation_mismatch: the token's organisation does not match the request's","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"phone_unavailable: something failed on Phone's side (database, Redis); try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":[]}]}},"/phone/admin":{"get":{"tags":["Administration"],"summary":"Get the Phone administration overview","description":"Everything the Phone administration page shows for your organisation: the PBX's extensions, who has which extension, the people Phone knows (up to 200, by name), and every receiving device in the organisation (newest first, up to 500). Needs phone.admin; a bot on its owner's pass may read it.\n\n**Permission:** `phone.phone.admin` (Manage Phone assignments).","operationId":"phoneAdminRead","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"administration":{"type":"object","properties":{"extensions":{"type":"array","items":{"type":"object","properties":{"extension_uuid":{"type":"string","description":"The PBX extension's ID: extensionId in Assign an extension"},"domain_uuid":{"type":"string","description":"The PBX domain's ID: domainId in Adopt the PBX domain"},"domain":{"type":"string"},"extension":{"type":"string"},"display_name":{"type":"string","description":"The name the PBX has on the extension"}}},"description":"The organisation's extensions as the PBX lists them (up to 1000), with the PBX's own field names"},"assignments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"userId":{"type":"string","description":"Central ID of the person assigned"},"extensionId":{"type":"string","description":"The PBX extension's ID"},"extension":{"type":"string"},"enabled":{"type":"boolean","description":"False when Phone access was disabled for this person"},"revision":{"type":"integer","description":"Goes up by one on each change; a device leased under an older revision cannot renew"},"displayName":{"type":"string"},"domain":{"type":"string"}}},"description":"Every assignment, enabled or not, by extension number (up to 1000)"},"users":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string"},"displayName":{"type":"string"},"disabled":{"type":"boolean","description":"True when disabled in Central"}}},"description":"People Phone knows (from Kazee Central, or who opened Phone), by name"},"devices":{"type":"array","items":{"type":"object","properties":{"deviceId":{"type":"string"},"leaseId":{"type":"string"},"userId":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"kind":{"type":"string","description":"web, desktop or android"},"label":{"type":"string"}}},"description":"Every receiving device in the organisation"}}}}},"example":{"administration":{"extensions":[{"extension_uuid":"1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d","domain_uuid":"9f8e7d6c-5b4a-4321-8fed-cba987654321","domain":"acme-ltd.pbx.kazee.africa","extension":"1042","display_name":"Wanjiru Kamau"},{"extension_uuid":"2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e","domain_uuid":"9f8e7d6c-5b4a-4321-8fed-cba987654321","domain":"acme-ltd.pbx.kazee.africa","extension":"1043","display_name":"Front desk"}],"assignments":[{"id":"0b7e2f4a-3c1d-4e5f-9a8b-7c6d5e4f3a21","userId":"65f1c0ffee0000000000a1b2","extensionId":"1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d","extension":"1042","enabled":true,"revision":3,"displayName":"Wanjiru Kamau","domain":"acme-ltd.pbx.kazee.africa"}],"users":[{"userId":"65f1c0ffee0000000000c3d4","displayName":"Otieno Mwangi","disabled":false},{"userId":"65f1c0ffee0000000000a1b2","displayName":"Wanjiru Kamau","disabled":false}],"devices":[{"deviceId":"3f9a1c0e5b7d4a2f8e6c1b0d9a7f5e3c","leaseId":"5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c0b","userId":"65f1c0ffee0000000000a1b2","createdAt":"2026-10-20T09:00:00.000Z","expiresAt":"2026-10-20T09:02:00.000Z","kind":"android","label":"Android phone"}]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"organisation_mismatch: the token's organisation does not match the request's","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/ServerError"},"502":{"description":"pbx_invalid_directory: the PBX's extension list is malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"pbx_unreachable, pbx_unavailable or phone_not_configured: the PBX cannot be reached or Phone is not set up to reach it; phone_unavailable: something failed on Phone's side (database, Redis); try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["phone.phone.admin"]}],"x-required-scopes":["phone.phone.admin"]}},"/mobile/apk/check":{"get":{"tags":["Android app"],"summary":"Check for a Kazee Phone app update","description":"The Kazee Phone app's in-app updater asks whether a newer release exists and whether it must install it. Needs no sign-in.\n\n**Sign-in:** not needed.","operationId":"checkAppVersion","parameters":[{"name":"currentVersion","in":"query","required":true,"schema":{"type":"string"},"description":"The app's own version, three numbers like 1.2.3","example":"0.4.1"},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["android","ios"]},"description":"Which app; android when left out","example":"android"},{"name":"versionCode","in":"query","required":false,"schema":{"type":"integer"},"description":"The app's Android versionCode. When sent (above 0) it decides whether an update is available; when left out the version is compared","example":20}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"update":{"type":"object","properties":{"updateAvailable":{"type":"boolean","description":"True when the latest release is newer than the app asking (by versionCode when it is sent, else by version). When there is no release at all, the reply is only { updateAvailable: false }"},"forceUpdate":{"type":"boolean","description":"True when the app must update before it can be used: the latest release is a required one, or the app skipped an earlier required release"},"version":{"type":"string","description":"Version of the latest release"},"versionCode":{"type":"integer","description":"Android versionCode of the latest release"},"downloadUrl":{"type":"string","description":"Where to download the APK"},"sha256":{"type":"string","description":"SHA-256 of the APK in lowercase hex, to check the download; null when not recorded"},"releaseNotes":{"type":"string","description":"What changed; empty when none"}}}}},"example":{"update":{"updateAvailable":true,"forceUpdate":false,"version":"0.4.2","versionCode":21,"downloadUrl":"https://blobstore.inet.africa:9000/kazee-phone-apk/kazee-phone-0.4.2-vc21.apk?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=BBGbPdf0gs3vr6I85l5i%2F20261118%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20261118T193008Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=089563ae23e278f8600c3df3f7ee36ac8fbd7a27e6a89f1b7bef5046ae481cf0","sha256":"3f7a9c2e5b8d1f4a6c0e9b2d7f5a3c1e8b6d4f2a0c9e7b5d3f1a8c6e4b2d0f9a","releaseNotes":"Calls ring faster after the phone wakes from sleep."}}}}},"400":{"description":"currentVersion is not a version like 1.2.3 (invalid_version), or platform is not android or ios (invalid_platform)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"The release registry could not be read (phone_unavailable)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[]}},"/mobile/apk/latest":{"get":{"tags":["Android app"],"summary":"Get the latest Kazee Phone app release","description":"The newest published release of the Kazee Phone app for a platform, with its download link. Needs no sign-in.\n\n**Sign-in:** not needed.","operationId":"getLatestAppVersion","parameters":[{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["android","ios"]},"description":"Which app; android when left out","example":"android"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"release":{"type":"object","properties":{"platform":{"type":"string"},"version":{"type":"string"},"versionCode":{"type":"integer","description":"Android versionCode of the release"},"downloadUrl":{"type":"string","description":"Where to download the APK"},"sha256":{"type":"string","description":"SHA-256 of the APK in lowercase hex; null when not recorded"},"releaseNotes":{"type":"string","description":"What changed; empty when none"},"forceUpdate":{"type":"boolean","description":"Whether this release itself is a required update (an app that skipped an earlier required release must also update: use the update check for that)"},"createdAt":{"type":"string","format":"date-time"}}}}},"example":{"release":{"platform":"android","version":"0.4.2","versionCode":21,"downloadUrl":"https://blobstore.inet.africa:9000/kazee-phone-apk/kazee-phone-0.4.2-vc21.apk?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=BBGbPdf0gs3vr6I85l5i%2F20261118%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20261118T193008Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=089563ae23e278f8600c3df3f7ee36ac8fbd7a27e6a89f1b7bef5046ae481cf0","sha256":"3f7a9c2e5b8d1f4a6c0e9b2d7f5a3c1e8b6d4f2a0c9e7b5d3f1a8c6e4b2d0f9a","releaseNotes":"Calls ring faster after the phone wakes from sleep.","forceUpdate":false,"createdAt":"2026-10-20T09:00:00.000Z"}}}}},"400":{"description":"platform is not android or ios (invalid_platform)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No release has been published for that platform yet (no_release)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"The release registry could not be read (phone_unavailable)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[]}},"/me":{"get":{"tags":["Account"],"summary":"Get who you are signed in as","description":"Who you are signed in as, straight from your Kazee sign-in: your Kazee Central ID, organisation, name, email and the Kazee Phone permissions your token carries. Any signed-in person with Kazee Phone access may call it; it changes nothing.\n\n**Permission:** any signed-in member.","operationId":"me","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string","description":"Your Kazee Central ID"},"organizationId":{"type":"string","description":"Your organisation's Kazee Central ID"},"name":{"type":"string","description":"Your name as Kazee Central has it (first and last name joined when there is no full name)"},"email":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"},"description":"The Kazee Phone permissions your token carries, as Kazee Central grants them (e.g. phone.phone.admin); empty when it carries none"}}}}},"example":{"user":{"id":"65f1c0ffee0000000000c3d4","organizationId":"65f1c0ffee0000000000a1b2","name":"Amina Wanjiru","email":"amina.wanjiru@example.com","scopes":["phone.widgets.read","phone.contacts.read"]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":[]}]}},"/widgets":{"get":{"tags":["Widgets"],"summary":"List widgets","description":"Your organisation's widgets that are not deleted, newest first. Widgets are the app template's worked example of the data-access pattern. Changes nothing.\n\n**Permission:** `phone.widgets.read` (View widgets).","operationId":"listWidgets","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":200},"description":"At most this many widgets, up to 500","example":50},{"name":"search","in":"query","required":false,"schema":{"type":"string"},"description":"Only widgets whose name contains this text (any case)","example":"desk"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"widgets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The widget's ID (wid_ followed by 32 hex characters)"},"name":{"type":"string"},"status":{"type":"string","description":"active or archived"},"created_at":{"type":"string","format":"date-time","description":"When the widget was created"}}}},"count":{"type":"integer","description":"How many widgets are in this reply"}}},"example":{"widgets":[{"id":"wid_019a3c4e7b217c3d9e4f1a2b3c4d5e6f","name":"Front desk display","status":"active","created_at":"2026-10-20T09:00:00.000Z"}],"count":1}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["phone.widgets.read"]}],"x-required-scopes":["phone.widgets.read"]},"post":{"tags":["Widgets"],"summary":"Create a widget","description":"Adds a widget to your organisation, active. Widgets are the app template's worked example of the data-access pattern. Answers 200.\n\n**Permission:** `phone.widgets.create` (Create widgets).","operationId":"createWidget","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The widget's name, unique in your organisation (any case) among widgets not deleted","examples":["Front desk display"]}},"required":["name"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"widget":{"type":"object","properties":{"id":{"type":"string","description":"The new widget's ID (wid_ followed by 32 hex characters)"},"name":{"type":"string"},"status":{"type":"string","description":"Always active for a new widget"}}}}},"example":{"widget":{"id":"wid_019a3c4e7b217c3d9e4f1a2b3c4d5e6f","name":"Front desk display","status":"active"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"A widget with that name (any case) already exists in your organisation (error \"That record already exists.\")","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["phone.widgets.create"]}],"x-required-scopes":["phone.widgets.create"]}},"/phone/favorites":{"post":{"tags":["Contacts"],"summary":"Star a contact","description":"Stars or unstars a phonebook contact for you only; the contact itself (owned by Kazee Contacts) does not change. Needs contacts.read.\n\n**Permission:** `phone.contacts.read` (View Phone contacts).","operationId":"phoneFavorite","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"favorite":{"type":"boolean","description":"true to star, false to unstar. Must be a JSON boolean, not a string","examples":[true]},"partyId":{"type":"string","pattern":"^par_[a-f0-9]{32}$","description":"The contact's party ID, from Search the phonebook","examples":["par_0123456789abcdef0123456789abcdef"]}},"required":["favorite","partyId"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"preference":{"type":"object","properties":{"favorite":{"type":"boolean","description":"Whether the contact is now starred"}}}}},"example":{"preference":{"favorite":true}}}}},"400":{"description":"invalid_favorite: partyId is not par_ and 32 lowercase hex, or favorite is not a JSON boolean","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"organisation_mismatch: the token's organisation does not match the request's","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"contact_unavailable: no active contact with that partyId","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"phone_unavailable: something failed on Phone's side (database, Redis); try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["phone.contacts.read"]}],"x-required-scopes":["phone.contacts.read"]}},"/phone/caller-brief":{"post":{"tags":["Calls"],"summary":"Get a caller brief","description":"Who is calling: the people and cards Kazee apps (today CRM, which also serves Desk and Books) know for a number, each app showing only what you may see there, plus the call outcomes you may set. Only a person's own session may ask: an app's service token or a bot on its own key is refused (403 person_required). An app that is slow (over 1.2 seconds) or down adds nothing and the brief still answers 200; providers says how each app did. Briefs are kept 60 seconds per person and number.\n\n**Permission:** any signed-in member.","operationId":"phoneCallerBrief","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"callId":{"type":"string","description":"The call's own ID (visible ASCII, up to 128 characters), only for the log","examples":["4f1c2a9e@phone.kazee.africa"]},"callRef":{"type":"string","pattern":"^[a-z]{2,16}:[a-z_]{2,32}:[A-Za-z0-9_-]{1,64}$","description":"The record the call was placed from, as app:type:id (from the dial link), passed on to the apps","examples":["crm:contact:42"]},"direction":{"type":"string","enum":["inbound","outbound","internal"],"description":"Which way the call goes, passed on to the apps","examples":["inbound"]},"number":{"type":"string","description":"The other party's number. Read as E.164 with Kenya as the default country: 0712345678, 254712345678, +254 712 345678 and 00254712345678 all work","examples":["+254712345678"]}},"required":["number"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"v":{"type":"integer","description":"Contract version, always 1"},"people":{"type":"array","items":{"type":"object","properties":{"partyId":{"type":"string","description":"The Contacts party"},"displayName":{"type":"string"},"kind":{"type":"string","description":"person or organization"}}}},"cards":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"app":{"type":"string"},"kind":{"type":"string","description":"who, recent_calls, open_tickets, account_balance or ai_brief"},"title":{"type":"string"},"priority":{"type":"integer","description":"Lower shows first; at most 5 cards"},"lines":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"}}},"description":"Up to 4 label/value lines of plain text (80 characters each)"},"badges":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"tone":{"type":"string","description":"neutral, info, warning, danger or success"}}}},"actions":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","description":"open (a link), note, outcome or ticket; links are always https on kazee.africa"},"label":{"type":"string"},"href":{"type":"string"}}}},"asOf":{"type":"string","format":"date-time","description":"When the app's data was read"}}}},"ambiguous":{"type":"boolean","description":"True when the number matches more than one party: only who cards are kept, so you pick"},"dispositions":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"A call outcome code you may set with File a call action (disposition)"},"label":{"type":"string"}}}},"providers":{"type":"array","items":{"type":"object","properties":{"app":{"type":"string"},"ok":{"type":"boolean","description":"False when the app failed, timed out or refused; then the entry also has reason (e.g. timeout, unauthorized, forbidden, http_500, misconfigured)"},"ms":{"type":"integer","description":"How long the app took"}}}}}},"example":{"v":1,"people":[{"partyId":"par_0123456789abcdef0123456789abcdef","displayName":"Wanjiru Kamau","kind":"person"}],"cards":[{"id":"crm:contact:42","app":"crm","kind":"who","title":"Wanjiru Kamau, Acme Supplies","priority":10,"lines":[{"label":"Owner","value":"Otieno Mwangi"},{"label":"Stage","value":"Customer"}],"badges":[{"text":"VIP","tone":"info"}],"actions":[{"kind":"open","label":"Open in CRM","href":"https://crm.kazee.africa/contacts/42"}],"asOf":"2026-10-20T09:00:00.000Z"}],"ambiguous":false,"dispositions":[{"code":"interested","label":"Interested"},{"code":"call_back","label":"Call back later"}],"providers":[{"app":"crm","ok":true,"ms":214}]}}}},"400":{"description":"invalid_number: not a phone number Phone can read as E.164 (Kenya by default); invalid_call_ref: callRef is not app:type:id; invalid_call_id: callId is not visible ASCII up to 128; invalid_direction: not inbound, outbound or internal","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"person_required: only a person's own session may do this; an app's service token or a bot on its own key is refused; organisation_mismatch: the token's organisation does not match the request's","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"phone_unavailable: something failed on Phone's side (database, Redis); try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":[]}]}},"/phone/call-action":{"post":{"tags":["Calls"],"summary":"File a call action","description":"Files a note, an outcome (disposition), a link to the record you dialled from, or a Desk ticket on the CRM call you are on (or just had), as yourself; CRM checks your own permissions. Send a JSON body with \"action\" (note, disposition, link or ticket) at the top level next to number, payload and requestId: \"action\" is read from the raw JSON body, not as a normal input, because ActionHero reserves that name. Phone picks the call itself and never guesses. Only a person's own session may do this: an app's service token or a bot on its own key is refused (403 person_required). A refusal also carries v: 1 and ok: false.\n\n**Permission:** any signed-in member.","operationId":"phoneCallAction","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"number":{"type":"string","description":"The other party's number (read as E.164, Kenya by default). Phone finds your call with it","examples":["+254712345678"]},"payload":{"type":"object","description":"What to file, by the body's top-level \"action\" field (send it next to payload in the JSON body; it is not a normal input because ActionHero reserves the name). note: {\"text\"} up to 2000 characters; disposition: {\"code\"} matching ^[a-z_]{2,40}$ (one of the brief's dispositions); link: {\"ref\"} as app:type:id; ticket: {\"subject\"} up to 200 characters and optional {\"body\"} up to 5000","examples":[{"subject":"Invoice copy requested","body":"Wants March's invoice again."}]},"requestId":{"type":"string","format":"uuid","description":"A uuid v4 you make for this action; CRM uses it so a retry is not filed twice","examples":["9e107d9d-372b-4b6e-8f2c-5d4e3a2b1c0d"]},"sipCallId":{"type":"string","description":"Your side's SIP Call-ID, when the browser knows it (visible ASCII, up to 128): picks that call when several match the number; otherwise the newest wins","examples":["a84b4c76e66710@phone.kazee.africa"]}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"v":{"type":"integer","description":"Contract version, always 1"},"ok":{"type":"boolean","description":"True when CRM applied the action"},"action":{"type":"string","description":"The action filed: note, disposition, link or ticket"},"callLogId":{"type":"string","description":"CRM's call log the action went on, when CRM says"},"result":{"type":"object","properties":{"ticketId":{"type":"string","description":"For a ticket: the new Desk ticket's ID"},"url":{"type":"string","description":"For a ticket: its link (https on kazee.africa only). result is {} for the other actions"}}}}},"example":{"v":1,"ok":true,"action":"ticket","callLogId":"cl_8f3a2b1c","result":{"ticketId":"10452","url":"https://desk.kazee.africa/tickets/10452"}}}}},"400":{"description":"invalid_number, invalid_action (the body's action is missing or unknown), invalid_payload (the payload does not fit its action), invalid_request_id (not a uuid v4), invalid_sip_call_id; or invalid: CRM refused the content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"person_required: only a person's own session may do this; an app's service token or a bot on its own key is refused; forbidden: CRM says you may not do this action","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"call_not_found: no call of yours with that number started in the last 12 hours that is live or ended at most 30 minutes ago; conflict_manual_link: the call is already linked to another record","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"unavailable: CRM could not be reached or refused Phone; phone_unavailable: something failed on Phone's side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"timeout: CRM did not answer within 3 seconds; it may still apply the action, so retry with the same requestId","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":[]}]}},"/phone/dial-request":{"post":{"tags":["Calls"],"summary":"Ask my other device to call","description":"Asks another of your devices that is receiving calls (the one most recently acquired or renewed, never the asking device) to place a call to this number: it shows its usual confirmation and never dials by itself. Answers 202 once the request is pushed. Sending the same requestId again within 10 minutes answers the same without a second push. At most 10 a minute. Only a person's own session may ask: an app's service token or a bot on its own key is refused (403 person_required).\n\n**Permission:** any signed-in member.","operationId":"phoneDialRequest","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"deviceId":{"type":"string","description":"The asking device's own id (32 lowercase hex) when it is itself receiving calls, so the request never goes back to it","examples":["7c5e3a1f9d8b6c4e2a0f8d6b4c2e0a9f"]},"number":{"type":"string","description":"The number to call. Read as E.164 with Kenya as the default country (0712345678 works)","examples":["+254712345678"]},"ref":{"type":"string","pattern":"^[a-z]{2,16}:[a-z_]{2,32}:[A-Za-z0-9_-]{1,64}$","description":"The record the call is placed from, as app:type:id, passed to the device","examples":["crm:contact:42"]},"requestId":{"type":"string","format":"uuid","description":"A uuid v4 you make for this request; reuse it to retry","examples":["3b241101-e2bb-4255-8caf-4136c566a962"]}}}}}},"responses":{"202":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"v":{"type":"integer","description":"Contract version, always 1"},"requestId":{"type":"string","description":"Your requestId, lowercased"},"device":{"type":"object","properties":{"id":{"type":"string","description":"The device the request went to (32 lowercase hex)"},"kind":{"type":"string","description":"web, desktop or android"},"label":{"type":"string","description":"\"browser\", \"desktop app\" or \"Android phone\""}}}}},"example":{"v":1,"requestId":"3b241101-e2bb-4255-8caf-4136c566a962","device":{"id":"3f9a1c0e5b7d4a2f8e6c1b0d9a7f5e3c","kind":"android","label":"Android phone"}}}}},"400":{"description":"invalid_number (not readable as E.164), invalid_ref (not app:type:id), invalid_request_id (not a uuid v4), invalid_device_id (not 32 lowercase hex)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"person_required: only a person's own session may do this; an app's service token or a bot on its own key is refused; organisation_mismatch: the token's organisation does not match the request's","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"no_device: none of your other devices is receiving calls","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"429":{"description":"rate_limited: more than 10 requests in a minute","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"unavailable: the request could not be pushed, retry with the same requestId; phone_unavailable: something failed on Phone's side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":[]}]}},"/phone/click-to-call":{"post":{"tags":["Calls"],"summary":"Click to call","description":"Calls a number through Kazee Phone: the PBX rings every device on your own extension first and dials the number once you answer, so answering is the confirmation. Answers 202 while your devices ring. At most 6 a minute. Only a person's own session with an assigned extension may do this: an app's service token or a bot on its own key is refused (403 person_required).\n\n**Permission:** any signed-in member.","operationId":"phoneClickToCall","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"number":{"type":"string","description":"The number to call, 3 to 20 digits with an optional leading +; spaces, dots, dashes and brackets are dropped. Dialled as given (not turned into E.164)","examples":["0712 345 678"]},"ref":{"type":"string","pattern":"^[a-z]{2,16}:[a-z_]{2,32}:[A-Za-z0-9_-]{1,64}$","description":"The record the call is placed from, as app:type:id, passed to the PBX","examples":["crm:contact:42"]}}}}}},"responses":{"202":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"v":{"type":"integer","description":"Contract version, always 1"},"requestId":{"type":"string","description":"The PBX callback's ID (32 lowercase hex), for support"},"status":{"type":"string","description":"Always ringing: your devices are ringing"}}},"example":{"v":1,"requestId":"d41d8cd98f00b204e9800998ecf8427e","status":"ringing"}}}},"400":{"description":"invalid_number: not 3 to 20 digits with an optional leading + (spaces, dots, dashes and brackets are dropped); invalid_ref: ref is not app:type:id; or the PBX refused the request with its own code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"person_required: only a person's own session may do this; an app's service token or a bot on its own key is refused; extension_not_assigned: you have no enabled extension; organisation_mismatch: the token's organisation does not match the request's","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"429":{"description":"too_many_calls: more than 6 in a minute; or the PBX's own pacing (callback_pending, callback_rate)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"pbx_unreachable, pbx_unavailable or phone_not_configured: the PBX cannot be reached or Phone is not set up to reach it; phone_unavailable: something failed on Phone's side (database, Redis); try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":[]}]}},"/phone/client-event":{"post":{"tags":["Calls"],"summary":"Report a call event from my browser","description":"Reports what a click-to-call or an Answer came to in your browser, for Phone's support log. Only the listed words, a small count, app slugs and an error code are kept; any other value is dropped silently, never echoed. No numbers, no free text. Past 30 a minute, events are dropped and the answer says recorded: false. Only a person's own session may report: an app's service token or a bot on its own key is refused (403 person_required).\n\n**Permission:** any signed-in member.","operationId":"phoneClientEvent","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"engineApp":{"type":"string","pattern":"^[a-z][a-z0-9-]{1,23}$","description":"App slug of the tab running the calls","examples":["phone"]},"engineMic":{"type":"string","enum":["granted","prompt","denied","unknown","none"],"description":"Microphone permission in the tab running the calls","examples":["granted"]},"hereApp":{"type":"string","pattern":"^[a-z][a-z0-9-]{1,23}$","description":"App slug of this tab (crm, spaces, tickets, phone ...)","examples":["crm"]},"hereMic":{"type":"string","enum":["granted","prompt","denied","unknown","none"],"description":"Microphone permission in this tab","examples":["granted"]},"others":{"type":"integer","minimum":0,"maximum":20,"description":"How many other live devices of yours there are (0 to 20)","examples":[1]},"outcome":{"type":"string","enum":["ringing","blocked","here","failed"],"description":"What it came to (blocked: nothing rang because nothing of yours could answer)","examples":["ringing"]},"reason":{"type":"string","pattern":"^[a-z_]{1,48}$","description":"For answer_refused: the Phone error code (e.g. microphone_blocked)","examples":["microphone_blocked"]},"role":{"type":"string","enum":["engine","remote","joining","idle","parked","stopped"],"description":"This tab's part in running your calls","examples":["engine"]},"took":{"type":"string","enum":["not_needed","yes","microphone","move"],"description":"Whether the calls moved to the clicked tab, or what that needed","examples":["not_needed"]},"type":{"type":"string","enum":["dial","answer_refused"],"description":"dial: a click-to-call and what it came to; answer_refused: Answer was pressed and refused. Needed","examples":["dial"]},"via":{"type":"string","enum":["bar","link"],"description":"Where the click-to-call came from: the Kazee bar or a link","examples":["bar"]},"visible":{"type":"boolean","description":"Whether the tab was visible (true/false, or the strings \"true\"/\"false\")","examples":[true]}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"v":{"type":"integer","description":"Contract version, always 1"},"recorded":{"type":"boolean","description":"False when the event was dropped (over 30 a minute)"}}},"example":{"v":1,"recorded":true}}}},"400":{"description":"invalid_event: type is not dial or answer_refused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"person_required: only a person's own session may do this; an app's service token or a bot on its own key is refused; organisation_mismatch: the token's organisation does not match the request's","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"phone_unavailable: something failed on Phone's side (database, Redis); try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":[]}]}},"/phone/devices/acquire":{"post":{"tags":["Devices"],"summary":"Take my line on this device","description":"Takes your assigned extension on this device: answers a short PBX lease (about 120 seconds; renew it about every 30 seconds) with the one-time password and WebSocket ticket the device registers with, and the network (ICE) settings. Any signed-in member with an assigned extension may call it. Retrying with the same requestId keeps the same session. With ring-all each device holds its own lease; a device that already holds one gives up its older lease once the new one is issued, and other devices keep theirs.\n\n**Permission:** any signed-in member.","operationId":"phoneAcquire","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"deviceId":{"type":"string","description":"This device's own id: 32 lowercase hex, made once by the device and kept","examples":["3f9a1c0e5b7d4a2f8e6c1b0d9a7f5e3c"]},"kind":{"type":"string","enum":["web","desktop","android"],"description":"What this device is. Any other value is ignored; when left out, Kazee Phone for Android is recognised by its user agent and anything else counts as web","examples":["android"]},"requestId":{"type":"string","description":"32 lowercase hex, new for each acquire; send the same one again to retry an acquire whose answer was lost","examples":["a1b2c3d4e5f60718293a4b5c6d7e8f90"]}},"required":["deviceId","requestId"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"lease":{"type":"object","properties":{"userId":{"type":"string"},"organizationId":{"type":"string"},"deviceId":{"type":"string"},"leaseId":{"type":"string","description":"The PBX lease (32 lowercase hex); renew and release name it"},"extension":{"type":"string"},"domain":{"type":"string"},"password":{"type":"string","description":"One-time SIP password for this lease. Never stored by Phone; keep it in memory only"},"ticket":{"type":"string","description":"One-use WebSocket ticket (starts with the lease ID and a dot)"},"expiresAt":{"type":"integer","description":"When the lease ends unless renewed, as Unix time in seconds (not an ISO date)"},"websocketOrigin":{"type":"string","description":"The PBX WebSocket address to register with"},"iceServers":{"type":"array","items":{"type":"object","properties":{"urls":{"type":"array","items":{"type":"string"}},"username":{"type":"string"},"credential":{"type":"string"}}},"description":"STUN and TURN servers for the call's media (WebRTC RTCIceServer objects)"}}}}},"example":{"lease":{"userId":"65f1c0ffee0000000000a1b2","organizationId":"65f1c0ffee0000000000e5f6","deviceId":"3f9a1c0e5b7d4a2f8e6c1b0d9a7f5e3c","leaseId":"5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c0b","extension":"1042","domain":"acme-ltd.pbx.kazee.africa","password":"q7Hk2Lm9Np4Rs8Tv1Wx5Yz3Ab6Cd0Ef2Gh","ticket":"5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c0b.Zm9yLWRvY3Mtb25seQ","expiresAt":1760950920,"websocketOrigin":"wss://phone.pbx.kazee.africa:7443","iceServers":[{"urls":["turn:coturn.kazee.africa:3478?transport=udp","turn:coturn.kazee.africa:3478?transport=tcp"],"username":"kazee-phone","credential":"example-turn-secret"},{"urls":["stun:coturn.kazee.africa:3478"]}]}}}}},"400":{"description":"invalid_identifier: deviceId or requestId is not 32 lowercase hex (or the PBX refused the request with its own code)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"extension_not_assigned: you have no enabled extension; organisation_mismatch: the token's organisation does not match the request's","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"device_request_expired or device_request_changed: this requestId was used for a lease that has since ended or changed, so make a new one; extension_device_limit (ring-all: at most 10 live devices per extension) or extension_active_on_another_device (one-device PBX profile)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"502":{"description":"pbx_invalid_lease or pbx_invalid_response: the PBX answered something Phone cannot use","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"pbx_unreachable, pbx_unavailable or phone_not_configured: the PBX cannot be reached or Phone is not set up to reach it; phone_network_not_configured: the TURN settings are missing; phone_unavailable: something failed on Phone's side (database, Redis); try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":[]}]}},"/phone/devices/renew":{"post":{"tags":["Devices"],"summary":"Renew my device's lease","description":"Keeps this device's lease alive for up to another 120 seconds; call it about every 30 seconds. Only the person who took the lease, on the same device, may renew it, and only while the same extension assignment stands: after an assignment change the device must acquire again.\n\n**Permission:** any signed-in member.","operationId":"phoneRenew","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"deviceId":{"type":"string","description":"This device's own id (32 lowercase hex), as acquired","examples":["3f9a1c0e5b7d4a2f8e6c1b0d9a7f5e3c"]},"kind":{"type":"string","enum":["web","desktop","android"],"description":"What this device is, to correct a lease taken before kinds were kept. Any other value is ignored; when left out, the kind stays as it is (Kazee Phone for Android is still recognised by its user agent)","examples":["android"]},"leaseId":{"type":"string","description":"The lease to renew (32 lowercase hex), from acquire","examples":["5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c0b"]}},"required":["deviceId","leaseId"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"lease":{"type":"object","properties":{"leaseId":{"type":"string"},"expiresAt":{"type":"integer","description":"When the lease now ends unless renewed again, as Unix time in seconds"}}}}},"example":{"lease":{"leaseId":"5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c0b","expiresAt":1760951040}}}}},"400":{"description":"invalid_identifier: deviceId or leaseId is not 32 lowercase hex (or the PBX refused the request with its own code)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"extension_not_assigned: you no longer have an enabled extension; organisation_mismatch: the token's organisation does not match the request's","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"device_unavailable: no live lease of yours with that leaseId on that device, or your assignment changed since it was taken (acquire again)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"502":{"description":"pbx_invalid_lease or pbx_invalid_response: the PBX answered something Phone cannot use","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"pbx_unreachable, pbx_unavailable or phone_not_configured: the PBX cannot be reached or Phone is not set up to reach it; phone_unavailable: something failed on Phone's side (database, Redis); try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":[]}]}},"/phone/devices/release":{"post":{"tags":["Devices"],"summary":"Release my device","description":"Lets go of your line on this device: ends its PBX lease and any calls on it. Only your own lease on that device; releasing one already ended still answers success.\n\n**Permission:** any signed-in member.","operationId":"phoneRelease","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"deviceId":{"type":"string","description":"This device's own id (32 lowercase hex)","examples":["3f9a1c0e5b7d4a2f8e6c1b0d9a7f5e3c"]},"leaseId":{"type":"string","description":"The lease to end (32 lowercase hex), from acquire","examples":["5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c0b"]}},"required":["deviceId","leaseId"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}},"example":{"success":true}}}},"400":{"description":"invalid_identifier: deviceId or leaseId is not 32 lowercase hex","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"organisation_mismatch: the token's organisation does not match the request's","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"device_unavailable: you have no lease with that leaseId on that device","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"device_cleanup_pending: the PBX did not confirm the lease ended (it ends by itself within 120 seconds), try again; pbx_unreachable, pbx_unavailable or phone_not_configured: the PBX cannot be reached or Phone is not set up to reach it; phone_unavailable: something failed on Phone's side (database, Redis); try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":[]}]}},"/phone/push-token":{"post":{"tags":["Devices"],"summary":"Register my push token","description":"Keeps this Android device's push (FCM) token, so a call to your extension can wake Kazee Phone for Android when Android has put it to sleep. Registering again replaces the device's token; any other device or person in the organisation holding the same token loses it; you keep at most 10 tokens (one more retires the oldest). Only a person's own session may do this: an app's service token or a bot on its own key is refused (403 person_required).\n\n**Permission:** any signed-in member.","operationId":"phonePushToken","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"deviceId":{"type":"string","description":"This device's own id (32 lowercase hex), the one its leases carry","examples":["3f9a1c0e5b7d4a2f8e6c1b0d9a7f5e3c"]},"platform":{"type":"string","enum":["android"],"description":"Always \"android\"","examples":["android"]},"token":{"type":"string","maxLength":4096,"description":"The FCM registration token (visible ASCII, up to 4096)","examples":["fcm-token-dGhpcy1pcy1hLWZha2UtdG9rZW4"]}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}},"example":{"success":true}}}},"400":{"description":"invalid_device_id: deviceId is not 32 lowercase hex; invalid_token: token is not visible ASCII up to 4096 characters; invalid_platform: platform is not \"android\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"person_required: only a person's own session may do this; an app's service token or a bot on its own key is refused; organisation_mismatch: the token's organisation does not match the request's","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"phone_unavailable: something failed on Phone's side (database, Redis); try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":[]}]}},"/phone/push-token/delete":{"post":{"tags":["Devices"],"summary":"Forget my push token","description":"Forgets this device's push token when the app signs out, so calls no longer wake it. Nothing to forget still answers success. Only a person's own session may do this: an app's service token or a bot on its own key is refused (403 person_required). A bot acting on its owner's pass is refused too (403, askFirst: true): the person does this themselves.\n\n**Permission:** any signed-in member.","operationId":"phonePushTokenDelete","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"deviceId":{"type":"string","description":"This device's own id (32 lowercase hex)","examples":["3f9a1c0e5b7d4a2f8e6c1b0d9a7f5e3c"]}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}},"example":{"success":true}}}},"400":{"description":"invalid_device_id: deviceId is not 32 lowercase hex","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"person_required: only a person's own session may do this; an app's service token or a bot on its own key is refused; organisation_mismatch: the token's organisation does not match the request's; askFirst: a bot acting on its owner's pass (kzp_) is refused with { \"error\": \"askFirst: ...\", \"askFirst\": true }; the person must do this themselves in Kazee Phone","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"phone_unavailable: something failed on Phone's side (database, Redis); try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":[]}]}},"/phone/admin/domain":{"post":{"tags":["Administration"],"summary":"Adopt the PBX domain","description":"Sets up Phone for your organisation on the one PBX domain the PBX has authorised for it (domain_uuid in the administration overview). Calling it again with the same domain is fine; switching to another domain is refused. Needs phone.admin. A bot acting on its owner's pass is refused (403, askFirst: true): the person does this themselves in Kazee Phone.\n\n**Permission:** `phone.phone.admin` (Manage Phone assignments).","operationId":"phoneAdminDomain","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domainId":{"type":"string","format":"uuid","description":"The PBX's domain ID for your organisation (domain_uuid of its extensions in the administration overview)","examples":["9f8e7d6c-5b4a-4321-8fed-cba987654321"]}},"required":["domainId"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"object","properties":{"id":{"type":"string","description":"Phone's record of the domain (UUID)"},"domain":{"type":"string","description":"The PBX domain name"},"pbxDomainId":{"type":"string","description":"The PBX's own domain ID, as sent"}}}}},"example":{"domain":{"id":"4d2c8e1f-6a3b-4c7d-8e9f-1a2b3c4d5e6f","domain":"acme-ltd.pbx.kazee.africa","pbxDomainId":"9f8e7d6c-5b4a-4321-8fed-cba987654321"}}}}},"400":{"description":"invalid_identifier: domainId is not a UUID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"domain_not_available: the PBX has no extensions for your organisation, or they are not all on this domain; askFirst: a bot acting on its owner's pass (kzp_) is refused with { \"error\": \"askFirst: ...\", \"askFirst\": true }; the person must do this themselves in Kazee Phone","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"domain_change_requires_migration: your organisation already uses another PBX domain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"502":{"description":"pbx_invalid_directory: the PBX's extension list is malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"pbx_unreachable, pbx_unavailable or phone_not_configured: the PBX cannot be reached or Phone is not set up to reach it; phone_unavailable: something failed on Phone's side (database, Redis); try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["phone.phone.admin"]}],"x-required-scopes":["phone.phone.admin"]}},"/phone/admin/assign":{"post":{"tags":["Administration"],"summary":"Assign an extension","description":"Gives a person an extension (enabled: true), or turns off their Phone access (enabled: false). Any device the person has receiving is ended first, with its calls, and the person must take their line again. Asking for what is already set changes nothing. Needs phone.admin. A bot acting on its owner's pass is refused (403, askFirst: true): the person does this themselves in Kazee Phone.\n\n**Permission:** `phone.phone.admin` (Manage Phone assignments).","operationId":"phoneAdminAssign","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean","description":"true to assign the extension, false to turn the person's Phone access off. Must be a JSON boolean, not a string","examples":[true]},"extensionId":{"type":"string","format":"uuid","description":"The PBX extension's ID (extension_uuid in the administration overview). Needed also when disabling","examples":["1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d"]},"userId":{"type":"string","description":"Central ID of the person (24 lowercase hex), from users in the administration overview","examples":["65f1c0ffee0000000000c3d4"]}},"required":["enabled","extensionId","userId"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"assignment":{"type":"object","properties":{"id":{"type":"string","description":"The assignment's ID (UUID)"},"revision":{"type":"integer","description":"Goes up by one on each change; devices leased under an older revision cannot renew"}}}}},"example":{"assignment":{"id":"0b7e2f4a-3c1d-4e5f-9a8b-7c6d5e4f3a21","revision":4}}}}},"400":{"description":"invalid_identifier: userId is not a Central ID or extensionId is not a UUID; invalid_enabled: enabled is not a JSON boolean","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"organisation_mismatch: the token's organisation does not match the request's; askFirst: a bot acting on its owner's pass (kzp_) is refused with { \"error\": \"askFirst: ...\", \"askFirst\": true }; the person must do this themselves in Kazee Phone","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"extension_unavailable: the PBX has no such extension for your organisation; central_user_not_available: Phone does not know that person or they are disabled (when enabling)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"domain_not_configured: adopt the extension's PBX domain first; extension_already_assigned: another person has that extension enabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"502":{"description":"pbx_invalid_directory: the PBX's extension list is malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"device_cleanup_pending: the PBX did not confirm a device of the person ended, try again; pbx_unreachable, pbx_unavailable or phone_not_configured: the PBX cannot be reached or Phone is not set up to reach it; phone_unavailable: something failed on Phone's side (database, Redis); try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["phone.phone.admin"]}],"x-required-scopes":["phone.phone.admin"]}},"/phone/admin/extensions":{"post":{"tags":["Administration"],"summary":"Create an extension for a person","description":"Creates a new PBX extension for a person and assigns it to them: the number given, or the next free one in the organisation's ranges, set up like that range's staff line. Nothing existing changes. A person who already has an enabled extension gets it back (existing: true), so a retry never makes a second line. Needs phone.admin. A bot acting on its owner's pass is refused (403, askFirst: true): the person does this themselves in Kazee Phone.\n\n**Permission:** `phone.phone.admin` (Manage Phone assignments).","operationId":"phoneAdminCreateExtension","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"extension":{"type":"string","pattern":"^[0-9]{3,6}$","description":"The number to give, 3 to 6 digits (a JSON number is read as its digits). Leave out for the next free number","examples":["1044"]},"userId":{"type":"string","description":"Central ID of the person (24 lowercase hex). Phone must already know them (users in the administration overview)","examples":["65f1c0ffee0000000000c3d4"]}},"required":["userId"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"object","properties":{"extension":{"type":"string","description":"The extension number (3 to 6 digits)"},"extensionId":{"type":"string","description":"The PBX extension's ID (UUID)"},"existing":{"type":"boolean","description":"True when the person already had an enabled extension and nothing was created"}}}}},"example":{"created":{"extension":"1044","extensionId":"2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e","existing":false}}}}},"400":{"description":"invalid_identifier: userId is not a Central ID; invalid_extension: extension is not 3 to 6 digits (or the PBX refused the request with its own code)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"organisation_mismatch: the token's organisation does not match the request's; askFirst: a bot acting on its owner's pass (kzp_) is refused with { \"error\": \"askFirst: ...\", \"askFirst\": true }; the person must do this themselves in Kazee Phone","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"central_user_not_available: Phone does not know that person or they are disabled; extension_unavailable: the new extension is not in the PBX's list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"domain_not_configured: adopt the PBX domain first; extension_already_assigned: someone else has that extension; or the PBX's own code (e.g. the number is taken or every range is full)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"502":{"description":"pbx_invalid_response or pbx_invalid_directory: the PBX answered something Phone cannot use","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"pbx_unreachable, pbx_unavailable or phone_not_configured: the PBX cannot be reached or Phone is not set up to reach it; phone_unavailable: something failed on Phone's side (database, Redis); try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["phone.phone.admin"]}],"x-required-scopes":["phone.phone.admin"]}},"/phone/admin/revoke":{"post":{"tags":["Administration"],"summary":"End a person's device","description":"Ends one receiving device's lease, and its calls, for anyone in your organisation (from devices in the administration overview). Ending one already ended still answers success. Needs phone.admin. A bot acting on its owner's pass is refused (403, askFirst: true): the person does this themselves in Kazee Phone.\n\n**Permission:** `phone.phone.admin` (Manage Phone assignments).","operationId":"phoneAdminRevoke","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"deviceId":{"type":"string","description":"The device's id (32 lowercase hex)","examples":["3f9a1c0e5b7d4a2f8e6c1b0d9a7f5e3c"]},"leaseId":{"type":"string","description":"The lease to end (32 lowercase hex)","examples":["5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c0b"]}},"required":["deviceId","leaseId"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}},"example":{"success":true}}}},"400":{"description":"invalid_identifier: deviceId or leaseId is not 32 lowercase hex","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"organisation_mismatch: the token's organisation does not match the request's; askFirst: a bot acting on its owner's pass (kzp_) is refused with { \"error\": \"askFirst: ...\", \"askFirst\": true }; the person must do this themselves in Kazee Phone","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"device_unavailable: no lease with that leaseId on that device in your organisation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"device_cleanup_pending: the PBX did not confirm the lease ended (it ends by itself within 120 seconds), try again; pbx_unreachable, pbx_unavailable or phone_not_configured: the PBX cannot be reached or Phone is not set up to reach it; phone_unavailable: something failed on Phone's side (database, Redis); try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"kazee":["phone.phone.admin"]}],"x-required-scopes":["phone.phone.admin"]}},"/widgets/{id}":{"delete":{"tags":["Widgets"],"summary":"Delete a widget","description":"Deletes one of your organisation's widgets (it is kept, marked deleted, and its name can be used again). No such widget is not an error: the reply says deleted false. A bot acting on its owner's pass must ask first.\n\n**Permission:** `phone.widgets.delete` (Delete widgets).","operationId":"deleteWidget","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The widget's ID, in the path (/widgets/:id)","example":"wid_019a3c4e7b217c3d9e4f1a2b3c4d5e6f"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean","description":"true when the widget was deleted now; false when your organisation has no such widget or it was already deleted"}}},"example":{"deleted":true}}}},"400":{"description":"id is not wid_ followed by 32 hex characters (error \"id is not a widget ID\")","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/InvalidInput"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"kazee":["phone.widgets.delete"]}],"x-required-scopes":["phone.widgets.delete"]}}},"components":{"schemas":{"Error":{"type":"object","description":"Every error reply. The HTTP status says what kind of error it is.","properties":{"error":{"type":"string","description":"What went wrong, in words"}},"required":["error"]}},"responses":{"BadRequest":{"description":"The request was refused, for example an ID in the wrong form","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"No sign-in, or the token has expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"Signed in, but without the permission or access this needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Nothing found with that ID, or you cannot see it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InvalidInput":{"description":"A required input is missing or an input is not valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ServerError":{"description":"Something went wrong on our side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"securitySchemes":{"kazee":{"type":"http","scheme":"bearer","bearerFormat":"Kazee token","description":"Send `Authorization: Bearer <token>` with a token from Kazee sign-in. The person must have access to Kazee Phone in Kazee Central."}}},"security":[{"kazee":[]}],"x-tagGroups":[{"name":"Phone","tags":["My phone","Devices","Calls","Contacts"]},{"name":"Organisation","tags":["Administration"]},{"name":"Apps & service","tags":["Android app","Account","Widgets"]}],"servers":[{"url":"https://api.phone.kazee.africa/api"}]}