# LifeKnightAPI Documentation

> Documentation for LifeKnightAPI

## API Reference
- [Get JWT Token (Login)](https://docs.lifeknight.ai/reference/post_auth-token.md): Authenticates a user with email/password and returns a JWT token valid for 30 days. This is the primary login endpoint for API v2. No session is created.
- [Request password reset](https://docs.lifeknight.ai/reference/post_auth-pwd-reset.md): Sends a password reset email to the user's registered email address.
- [Forgot PIN](https://docs.lifeknight.ai/reference/post_auth-forgot-pin.md): Generates a new random 4-digit PIN and emails it to the authenticated user. The old PIN is replaced immediately. No request body needed.
- [Get own profile](https://docs.lifeknight.ai/reference/get_profile.md): Returns the authenticated user's profile including id, name, email, terra_uid, organization info, access_type, and tag.
- [Update own profile](https://docs.lifeknight.ai/reference/put_profile.md): Updates the authenticated user's profile. Supports updating `terra_uid` and/or address fields. At least one valid field must be provided. Address updates are validated for E911 compatibility.
- [Get user by ID](https://docs.lifeknight.ai/reference/get_users-id.md): Retrieves a user's full profile with address. Users can only access their own profile (authorization enforced — returns 403 if user ID doesn't match).
- [Update user](https://docs.lifeknight.ai/reference/put_users-id.md): General-purpose user update endpoint. Supports updating multiple fields in a single request: name, calendar, PIN, password, address, phone, and phone2. Only fields included in the request will be updated. Phone changes trigger an SMS verification flow.
- [Delete user account](https://docs.lifeknight.ai/reference/delete_users-id.md): Permanently deletes the user's account. Also removes associated DID assignment. Users can only delete their own account.
- [Get user address](https://docs.lifeknight.ai/reference/get_users-userid-address.md): Retrieves the user's saved address information. Users can only access their own address.
- [Revert phone number](https://docs.lifeknight.ai/reference/post_users-userid-revert-phone.md): Cancels a pending phone number change and reverts to the previously verified phone number. Clears `phone2` and `phone2_verified` fields and deletes the pending SMS verification record.
- [Check Android subscription](https://docs.lifeknight.ai/reference/get_users-userid-subscription.md): Checks the Android subscription status for a user. Returns whether the subscription is expired based on the latest order and product duration. Admin users are always treated as having active subscriptions.
- [Check iOS subscription](https://docs.lifeknight.ai/reference/get_users-userid-subscription-ios.md): Checks the iOS subscription status for a user by looking up the latest iOS subscription record and comparing its expiry date.
- [Assign DID to user](https://docs.lifeknight.ai/reference/post_users-userid-assign-did.md): Assigns a DID (Direct Inward Dialing) phone number to a user. Picks a random unreserved, unassigned DID from the pool and links it to the user via the did_user table. The DID serves as the caller ID for outgoing SMS and calls from LifeKnight. Also sends an SMS notification to the user with their new number.  **Side Effects:** - Creates `did_user` record (auto-logs to `users.did_history` via model boot event) - Sends SMS to user's phone with the new caller ID
- [List check-ins](https://docs.lifeknight.ai/reference/get_checkin.md): Retrieves all active/pending check-ins for the authenticated user. Excludes corrupted, escalated, and dismissed check-ins. Includes snooze count, timezone-adjusted times, and subscription/verification status.
- [Create a check-in](https://docs.lifeknight.ai/reference/post_checkin.md): Creates a new check-in (safety alarm) for the authenticated user. Validates E911 address compatibility, time constraints, and contact selection.
- [Get check-in count](https://docs.lifeknight.ai/reference/get_checkin-count.md): Returns the total number of check-ins (including soft-deleted) for the authenticated user.
- [Validate address (E911)](https://docs.lifeknight.ai/reference/post_checkin-address-valid.md): Validates whether a given address is compatible with E911 emergency services. Returns suggested address alternatives if the input is not valid.
- [Get check-in details](https://docs.lifeknight.ai/reference/get_checkin-id.md): Retrieves details of a specific check-in owned by the authenticated user.
- [Update check-in (Snooze)](https://docs.lifeknight.ai/reference/put_checkin-id.md): Snoozes a check-in alarm by 15 minutes. No request body required. Validates that the new time does not overlap with other check-ins. Maximum of 10 snoozes allowed per check-in.
- [Delete a check-in](https://docs.lifeknight.ai/reference/delete_checkin-id.md): Dismisses and soft-deletes a check-in. Sets status to "dismissed" before deletion.
- [Escalate check-in to E911](https://docs.lifeknight.ai/reference/put_checkin-escalate-id.md): Escalates a check-in to E911 emergency services. Initiates an emergency call via the Fractel communicator with the user's location, sends E911 location data, and logs a panic record. Requires a DID number to be assigned to the user.
- [Snooze alarm](https://docs.lifeknight.ai/reference/post_snooze-alarm-checkinid.md): Snoozes a specific alarm for 15 minutes. Checks for time overlaps and enforces a maximum of 10 snoozes. Updates the check-in status, resets counters, and recalculates UTC datetime.
- [Get scheduled alarms](https://docs.lifeknight.ai/reference/get_scheduled-alarms.md): Retrieves all scheduled (active, non-dismissed/escalated/corrupted) alarms for the authenticated user, sorted by date and time. Includes snooze info and timezone-adjusted appointment times.
- [Get all check-ins (including past)](https://docs.lifeknight.ai/reference/get_all-checkins.md): Retrieves all check-ins for the authenticated user, including soft-deleted ones. Useful for viewing full history of check-ins.
- [Call user's emergency contact](https://docs.lifeknight.ai/reference/post_users-userid-call-emergency-contact.md): Initiates an emergency call to the user's designated emergency contact (the contact with `escalate_fired = 1`). No request body is needed — the user's address on file is used for location data.  Performs the following validations before calling: 1. User must exist 2. User must have a confirmed emergency contact (`escalate_fired = 1`, `is_confirmed = 1`) 3. User must have a DID/Caller ID assigned 4. User must have an address on file  On success, sends an SMS and initiates a call to the emergency contact via the Fractel communicator, and logs the event.  **Side Effects:** - Sends SMS to the emergency contact - Initiates call to emergency contact via FracTel - Creates `reminders` record - Creates `panic_logs` record
- [Initiate E911 emergency call](https://docs.lifeknight.ai/reference/post_users-userid-call-e911.md): Initiates an E911 emergency call for a user. Performs the following validations in order before placing the call:  1. User must exist 2. User must have a DID/Caller ID assigned 3. User must have an address on file 4. Address must have all required fields (city, state, street, streetnumber, zipcode) 5. Address must be E911 compatible (validated via FracTel E911VALIDATE2 API)  On success, sends the user's location to FracTel, initiates the emergency call, and logs the event to panic_logs.  **Side Effects:** - Registers E911 location with FracTel - Initiates emergency call via FracTel - Creates `panic_logs` record
- [List contacts](https://docs.lifeknight.ai/reference/get_contacts.md): Retrieves all emergency contacts for the authenticated user, sorted alphabetically by name.
- [Create a contact](https://docs.lifeknight.ai/reference/post_contacts.md): Adds a new emergency contact. Sends an SMS verification message to the contact's phone. The contact must respond "yes{code}" to confirm. The contact's phone number must not match the user's own phone.
- [Get verified contacts](https://docs.lifeknight.ai/reference/get_contacts-verified.md): Returns only emergency contacts that have confirmed their SMS verification (is_confirmed = 1).
- [Get contact details](https://docs.lifeknight.ai/reference/get_contacts-id.md): Retrieves a specific emergency contact by ID. Only contacts belonging to the authenticated user are accessible.
- [Update a contact](https://docs.lifeknight.ai/reference/put_contacts-id.md): Updates an emergency contact's name and/or default escalation setting. Supports `default_option` flag to set/unset a contact as the default emergency escalation contact.
- [Delete a contact](https://docs.lifeknight.ai/reference/delete_contacts-id.md): Deletes an emergency contact. Fails if the contact is associated with future active check-ins (status: "waiting" or "snoozed"). Warns if the deleted contact was the default escalation contact.
- [Get check-in history](https://docs.lifeknight.ai/reference/get_history.md): Retrieves the check-in history for the authenticated user. Includes associated emergency contact details (name, phone) even if the contact has been soft-deleted.
- [Get panic history](https://docs.lifeknight.ai/reference/get_panic-history.md): Retrieves the panic/escalation history for the authenticated user. Returns records from the panic log ordered by most recent first.
- [Send location via SMS](https://docs.lifeknight.ai/reference/post_send-location.md): Sends the user's current location to a specified contact via SMS. The message includes the user's name, phone number, and full address.
- [Poll user phone verification](https://docs.lifeknight.ai/reference/get_poll-user-contact.md): Checks whether the user's phone number has been verified. Returns `success: true` when verified, `success: false` otherwise. Used by the app to poll until phone verification completes.
- [Poll emergency contact verification](https://docs.lifeknight.ai/reference/get_poll-emergency-contact.md): Checks for recent emergency contact verification updates (within last 5 seconds). Returns updated contacts and a `stop` flag indicating whether all contacts are confirmed (no more polling needed).
- [Poll check-in updates](https://docs.lifeknight.ai/reference/get_poll-check-in.md): Checks for check-in status changes within the last 10 seconds. Returns recently updated check-ins and a `stop` flag indicating whether there are still scheduled check-ins to monitor.
- [Poll phone change verification](https://docs.lifeknight.ai/reference/get_poll-user-phone-update.md): Checks whether a pending phone number change has been verified. Returns `success: true` when the new phone number (phone2) is verified.
- [List alerts](https://docs.lifeknight.ai/reference/get_alerts.md): Lists alerts with optional filtering. Requires admin or staff access. - System admins see all alerts - Organization admins/staff see alerts for users in their organization - Can filter by specific user_id, status, type, date range
- [Create a new alert](https://docs.lifeknight.ai/reference/post_alerts.md): Creates a new alert for a specified user. Requires admin or staff access. - System admins can create alerts for any user - Organization admins/staff can only create alerts for users in their organization
- [Get active alerts count](https://docs.lifeknight.ai/reference/get_alerts-active-count.md): Returns the count of active alerts, optionally broken down by type. - System admins see count for all alerts - Organization admins/staff see count for their organization's users
- [Get alert details](https://docs.lifeknight.ai/reference/get_alerts-id.md): Returns detailed information about a specific alert including user, geofence, and actions
- [Update an alert](https://docs.lifeknight.ai/reference/put_alerts-id.md): Updates alert properties. Status changes automatically set timestamps.
- [Delete an alert](https://docs.lifeknight.ai/reference/delete_alerts-id.md): Permanently deletes an alert
- [Acknowledge an alert](https://docs.lifeknight.ai/reference/post_alerts-id-acknowledge.md): Marks an alert as acknowledged. Sets `acknowledged_at` timestamp and changes status to "acknowledged". Cannot acknowledge already resolved or dismissed alerts. Logs the action in the alert actions table. Requires admin or staff access.
- [Resolve an alert](https://docs.lifeknight.ai/reference/post_alerts-id-resolve.md): Marks an alert as resolved. Sets `resolved_at` timestamp and changes status to "resolved". Cannot resolve already resolved or dismissed alerts. Logs the action. Requires admin or staff access.
- [Dismiss an alert](https://docs.lifeknight.ai/reference/post_alerts-id-dismiss.md): Dismisses an alert (marks as not requiring further action). Changes status to "dismissed". Cannot dismiss already resolved or dismissed alerts. Logs the action. Requires admin or staff access.
- [Escalate an alert](https://docs.lifeknight.ai/reference/post_alerts-id-escalate.md): Escalates an alert by setting its priority to "high". Cannot escalate resolved or dismissed alerts. Logs the escalation action. Requires admin or staff access.
- [Get alert actions (audit trail)](https://docs.lifeknight.ai/reference/get_alerts-id-actions.md): Retrieves the full action history (audit trail) for an alert, including who performed each action and when. Requires admin or staff access.
- [Add alert action](https://docs.lifeknight.ai/reference/post_alerts-id-actions.md): Adds a custom action record to an alert's history. If the action type is "resolved", "dismissed", or "acknowledged", the alert status is automatically updated accordingly. Requires admin or staff access.
- [List geofences](https://docs.lifeknight.ai/reference/get_geofences.md): Lists geofences for the authenticated user or a specified user (with authorization). - Users can view their own geofences - System admins can view any user's geofences - Organization admins/staff can view geofences for users in their organization
- [Create a new geofence](https://docs.lifeknight.ai/reference/post_geofences.md): Creates a new geofence for the authenticated user (or target `user_id`). - **Circle** type requires `center_latitude`, `center_longitude`, and `radius`. - **Polygon** type requires `coordinates` array with a minimum of 3 points.
- [Get geofence details](https://docs.lifeknight.ai/reference/get_geofences-id.md): Returns detailed information about a specific geofence
- [Update a geofence](https://docs.lifeknight.ai/reference/put_geofences-id.md): Updates geofence properties. All fields are optional. - When `type` is `circle`, providing `center_latitude`, `center_longitude`, or `radius` will validate them. - When `type` is `polygon`, providing `coordinates` will validate the array (min 3 points).
- [Delete a geofence](https://docs.lifeknight.ai/reference/delete_geofences-id.md): Permanently deletes a geofence
- [Toggle geofence status](https://docs.lifeknight.ai/reference/post_geofences-id-toggle-status.md): Toggles the geofence status between active and inactive
- [Check if point is inside geofences](https://docs.lifeknight.ai/reference/post_geofences-check-point.md): Checks if a given latitude/longitude point is inside any of the user's active geofences
- [Bulk delete geofences](https://docs.lifeknight.ai/reference/post_geofences-bulk-delete.md): Deletes multiple geofences at once
- [Get organization](https://docs.lifeknight.ai/reference/get_organizations-id.md): Retrieves detailed information about an organization including all member users (id, name, email, phone, access_type, tag, status). Accessible by system admins or members of the organization.
- [List organization users](https://docs.lifeknight.ai/reference/get_organizations-id-users.md): Lists all users in an organization. Requires system admin or staff-level access within the organization.
- [Add user to organization](https://docs.lifeknight.ai/reference/post_organizations-id-users.md): Adds an existing user to an organization with a specified access level. Fails if the user is already a member of a different organization. Requires system admin or organization admin access.
- [Update user access](https://docs.lifeknight.ai/reference/put_organizations-id-users-userid.md): Updates a user's access type within an organization. Prevents demoting the last remaining admin. Requires system admin or organization admin access.
- [Remove user from organization](https://docs.lifeknight.ai/reference/delete_organizations-id-users-userid.md): Removes a user from an organization (sets organization_id and access_type to null). Does not delete the user account. Prevents removing the last remaining admin.
- [Agent 1 – Anomaly Detection](https://docs.lifeknight.ai/reference/post_agents-agent1.md): Sends a heart rate value to the LifeKnight AI anomaly detection agent. Returns whether the reading is anomalous along with a confidence score.
- [Agent 2 – Severity Assessment](https://docs.lifeknight.ai/reference/post_agents-agent2.md): Accepts anomaly detection results (heart_rate, anomaly flag, confidence_score) and returns a severity explanation with a severity level.
- [Agent 3 – Action Recommendation](https://docs.lifeknight.ai/reference/post_agents-agent3.md): Accepts heart_rate, explanation, and phonenumber and returns a recommended action (e.g. call hospital) along with a severity score and explanation.