Time Tracker Plus 360 API

Payroll & Time, Time Tracking
7 min read

Introduction to the API

The API is the backend web API that receives requests from the Time Tracker Plus browser app, mobile app, and related administrative tools. It sits between the client and the database. End users do not normally work directly with the database; instead, their requests are sent to the API, and the API performs the required validation, business logic, reporting, and database updates.

This help page is written for technical users: programmers, API integrators, consultants, power users, and advanced hobbyists who understand HTTP, JSON, endpoints, status codes, and backend configuration. The focus here is what the API can do, what it is useful for, and what its practical limits are.

What the API Does

Authenticates a user by PIN and returns the information needed to open the correct app screen.
Creates clock-in and clock-out transactions and writes the related records to the database.
Supplies work orders, topics, timecard data, time off history, GPS or device-data reports, and about or health information.
Stores and returns selected per-user settings, including consent, tracking, feature visibility, and report-column preferences.
Accepts telemetry and GPS data when tracking is enabled.
Provides administrative endpoints for device mappings and beacon zones.
Returns user-friendly troubleshooting information for many common database and connection failures.

Architecture and Request Flow

The API follows a client-server model. The browser client and the MAUI client communicate over HTTP or HTTPS with TimeClock.Api. The API then uses the active SQL Server connection string to work with the Aptora database. This means the clients never need a direct SQL connection string and should not connect directly to SQL Server.

At startup, the API can expose Swagger for developer inspection, configure CORS, load its active connection string through the database configuration service, add security headers to responses, and perform backward-compatibility checks that add certain missing columns to TimeClockUserSettings when SQL Server is the provider.

Security Features

Optional HTTPS-first behavior. HTTP is intended for development or controlled debugging only.
CORS policy support so only approved browser origins can call the API in production.
IP access-control evaluation, including allowed and blocked rules.
PIN rate limiting by device ID to slow repeated bad-login attempts.
Security headers such as X-Content-Type-Options, X-Frame-Options, Referrer-Policy, and Content-Security-Policy on HTML responses.
Optional API key, client version, and device-ID enforcement through configuration settings.
Detailed but user-friendly database error mapping for many SQL failure cases.

The codebase includes placeholders and configuration support for stronger API controls such as API-key validation and client version validation. It also includes a TODO note for JWT authentication, which means the current design is security-conscious but not yet a full token-based authentication platform.

Major Endpoint Groups

Endpoint group	Representative endpoints	Typical use
User access and basic session flow	UserCheck, Register, AcceptConsent, ChangePin	Validate a PIN, register a device, record consent, and change a user’s PIN.
Timekeeping operations	ClockIn, ClockOut, WorkOrders, Topics	Create time transactions and supply optional selection data used during clock-in or clock-out.
Reporting and self-service	WeeklyTimecards, GPSData, TimeOffHistory, SaveColumnPreferences, LoadColumnPreferences	Return report data and remember which report columns a user prefers to see.
Administration of user settings	UserSettings/List, UserSettings/{employeeId}, UserSettings/Save, UserSettings/ResetConsent	Load and save per-user options such as GPS collection, notes, work-order visibility, and report access.
Operational status	Health, About	Return server, database, version, compatibility, and general status information.
Advanced automation	BeaconZones, DeviceMappings, GetActiveBeaconZones, SubmitTelemetry	Support beacon-based or device-mapping scenarios and accept telemetry from continuously tracked clients.

Important Endpoints and What They Are For

Endpoint	Purpose	Notes
POST UserCheck	Validate the user’s PIN, enforce rate limiting, and return the employee record and settings.	Used from the sign-in page before the user page opens.
POST ClockIn	Create a clock-in transaction.	Can include work order, topic, notes, and mileage when those features are enabled.
POST ClockOut	Create a clock-out transaction.	Returns hours worked and closes the active timesheet.
GET WorkOrders/{employeeId}	Return the work orders available to the employee.	Supports work-order selection controls in the client.
GET Topics	Return available topics.	Supports note-topic selection.
POST WeeklyTimecards	Return timecard data grouped by pay period.	Used by timecard-report and weekly report screens.
POST GPSData	Return GPS and device telemetry records.	Can be used for the user-level or admin-level GPS report.
POST TimeOffHistory	Return PTO or time-off history.	Supports the Time Off History screen.
GET Health	Return API, machine, server, and database status.	One of the best first troubleshooting tools.
GET About	Return application and server information.	Used by About pages and status displays.
POST SaveColumnPreferences / LoadColumnPreferences	Persist report-column visibility preferences.	Lets users tailor report layouts without changing the report logic.
POST SubmitTelemetry	Accept telemetry while the app is running.	Most relevant to continuous tracking scenarios.
GET or POST Beacon and Device Mapping endpoints	Administer beacon zones and assign devices to employees.	These are higher-level technical features rather than ordinary employee features.

What the API Might Be Used For

Powering the standard Time Tracker Plus browser and mobile clients.
Driving a kiosk-type clock station where several employees use the same device.
Feeding a lightweight custom client or integration that needs to validate users, create time events, or read reports.
Supplying health and compatibility information to an administrator or monitoring page.
Supporting administrative tooling for device assignment, beacon zones, or user settings.

Practical Limitations

The API depends on the Aptora database structure. If required tables, columns, or stored procedures are missing, the API may respond with friendly error messages but it still cannot complete the requested work.
Some security features are configuration driven. For example, Swagger exposure, API-key enforcement, HTTP allowance, and allowed origins all depend on settings.
JWT authentication is not yet implemented in the code that was reviewed, so the API should not be described as a full modern token-auth platform yet.
Continuous tracking and richer device telemetry are more natural fits for native mobile clients than for standard web browsers.
The API is not the same thing as a public open platform. Some endpoints are clearly intended for controlled in-solution use rather than open third-party access.

Health Endpoint and Troubleshooting Value

The Health endpoint is unusually useful because it does more than return a simple alive signal. It reports API version, server time, machine name, operating-system description, process architecture, uptime, client IP, user agent, database name, server name, and, when the connection succeeds, SQL Server product details and database details such as compatibility level, recovery model, collation, file paths, last backup, max degree of parallelism, and max server memory.

When the database is not configured or the connection fails, the API returns troubleshooting tips tailored to the failure. Common mapped cases include timeout, server not found, login failed, cannot open database, missing column, missing table, and foreign-key problems. This is extremely helpful for both technicians and developers because it reduces guesswork.

Common Response Behavior

Behavior	What it means	Notes
Friendly success or failure messages	Most endpoints return a success flag and a message rather than assuming the caller will infer everything from HTTP status alone.	Makes the API easier to use from app screens and less technical clients.
Technical details field	Can include internal diagnostic detail when that option is enabled.	Usually best kept off in production end-user scenarios.
Troubleshooting tips collection	Many failures return practical next steps.	Especially useful for database and network failures.
Rate-limit information	UserCheck can return IsRateLimited and a delay in seconds.	This lets the client show a countdown instead of hammering the server.
403 with IP_DENIED	UserCheck and ClockIn explicitly evaluate IP rules and can refuse the request.	Useful in fixed-site or VPN-only deployments.

Configuration Concepts that Matter to Developers

Kestrel can listen on HTTP 5193 for development or on HTTPS 7240 when a local development certificate is configured.
Logging is written to a daily file under the application directory in a logs folder.
CORS can allow any origin in development but should be locked to specific origins in production.
The active database connection string is obtained through the database configuration service rather than hard-coded directly in every request path.
The startup sequence includes compatibility checks that can add missing columns such as LocationTrackingMode, IsAdmin, and AllowMileageEntry to TimeClockUserSettings when SQL Server is in use.

What is Not Covered Here

This help page intentionally does not tell an end user where the API URL is published or how the infrastructure is hosted in a particular customer environment. The purpose of this page is to explain capability and behavior, not deployment discovery.