Skip to main content
GET
/
v1
/
phones
List Phones
curl --request GET \
  --url https://api.example.com/v1/phones
List all phones currently registered with your organization.

​
Request

curl https://api.tapkit.ai/v1/phones \
  -H "X-API-Key: joot_your_api_key"

​
Response

[
  {
    "id": "abc123-def456",
    "name": "iPhone 15 Pro",
    "device_name": "iPhone 15 Pro",
    "display_name": "My Work Phone",
    "unique_id": "00008030-001A2B3C4D5E6F",
    "phone_number": "+15551234567",
    "shortcut_token": "st_abc123",
    "typing_method": "shortcut",
    "speed": 30,
    "activation_state": "active",
    "activated_at": "2024-01-10T15:00:00Z",
    "deactivated_at": null,
    "consumes_entitlement": true,
    "can_control": true,
    "can_view_on_web": true,
    "connection_status": "online",
    "connected_mac_id": "mac_xyz789",
    "width": 1179,
    "height": 2556,
    "created_at": "2024-01-10T14:30:00Z"
  }
]

​
Response Fields

FieldTypeDescription
idstringServer-assigned phone identifier
namestringDevice model name
device_namestringDevice hardware name
display_namestring | nullCustom display name (set via update-settings)
unique_idstringHardware identifier (UDID)
phone_numberstring | nullPhone number if available
shortcut_tokenstring | nullToken for iOS Shortcut authentication
typing_methodstringDefault typing method: "keys", "paste", "shortcut", or "shortcut_legacy"
speednumberSwitch Control scanning speed: 30 (slow) or 90 (fast)
activation_statestring"active" or "inactive"
activated_atstring | nullISO 8601 timestamp of activation
deactivated_atstring | nullISO 8601 timestamp of deactivation
consumes_entitlementbooleanWhether this phone counts against plan limits
can_controlbooleanWhether the phone can be controlled via API
can_view_on_webbooleanWhether the phone screen can be viewed in the web dashboard
connection_statusstring"online", "available", or "offline"
connected_mac_idstring | nullID of the Mac this phone is connected to
widthintegerScreen width in pixels
heightintegerScreen height in pixels
created_atstringISO 8601 timestamp of phone registration

​
Examples

​
List All Phones

import requests

response = requests.get(
    "https://api.tapkit.ai/v1/phones",
    headers={"X-API-Key": "joot_..."}
)
phones = response.json()

for phone in phones:
    status = phone["connection_status"]
    name = phone["display_name"] or phone["name"]
    print(f"{name} ({phone['id']}) - {status}")

​
Find Available Phone

phones = response.json()
available = next(
    (p for p in phones if p["connection_status"] in ("online", "available") and p["can_control"]),
    None
)

if available:
    phone_id = available["id"]

​
Notes

  • Returns an empty array [] if no phones are connected
  • Phone IDs remain stable for the same physical device
  • The unique_id corresponds to the device’s UDID