KROW Workforce API Contracts
This document captures all API contracts used by the Staff and Client mobile applications. The application backend is powered by Firebase Data Connect (GraphQL), so traditional REST endpoints do not exist natively. For clarity and ease of reading for all engineering team members, the tables below formulate these GraphQL Data Connect queries and mutations into their Conceptual REST Endpoints alongside the actual Data Connect Operation Name.
Staff Application
Authentication / Onboarding Pages
(Pages: get_started_page.dart, intro_page.dart, phone_verification_page.dart, profile_setup_page.dart)
Setup / User Validation API
| Field |
Description |
| Conceptual Endpoint |
GET /users/{id} |
| Data Connect OP |
getUserById |
| Purpose |
Retrieves the base user profile to determine authentication status and role access (e.g., if the user is STAFF). |
| Operation |
Query |
| Inputs |
id: UUID! (Firebase UID) |
| Outputs |
User { id, email, phone, role } |
| Notes |
Required after OTP verification to route users appropriately. |
Create Default User API
| Field |
Description |
| Conceptual Endpoint |
POST /users |
| Data Connect OP |
createUser |
| Purpose |
Inserts a base user record into the system during initial signup. |
| Operation |
Mutation |
| Inputs |
id: UUID!, role: UserBaseRole |
| Outputs |
id of newly created User |
| Notes |
Used explicitly during the "Sign Up" flow if the user doesn't physically exist in the database. |
Get Staff Profile API
| Field |
Description |
| Conceptual Endpoint |
GET /staff/user/{userId} |
| Data Connect OP |
getStaffByUserId |
| Purpose |
Finds the specific Staff record associated with the base user ID. |
| Operation |
Query |
| Inputs |
userId: UUID! |
| Outputs |
Staffs { id, userId, fullName, email, phone, photoUrl, status } |
| Notes |
Needed to verify if a complete staff profile exists before allowing navigation to the main app dashboard. |
Update Staff Profile API
| Field |
Description |
| Conceptual Endpoint |
PUT /staff/{id} |
| Data Connect OP |
updateStaff |
| Purpose |
Saves onboarding data across Personal Info, Experience, and Preferred Locations pages. |
| Operation |
Mutation |
| Inputs |
id: UUID!, fullName, email, phone, address, etc. |
| Outputs |
id |
| Notes |
Called incrementally during the profile setup wizard as the user fills out step-by-step information. |
Home Page & Benefits Overview
(Pages: worker_home_page.dart, benefits_overview_page.dart)
Load Today/Tomorrow Shifts
| Field |
Description |
| Conceptual Endpoint |
GET /staff/{staffId}/applications |
| Data Connect OP |
getApplicationsByStaffId |
| Purpose |
Retrieves applications (shifts) assigned to the current staff member within a specific date range. |
| Operation |
Query |
| Inputs |
staffId: UUID!, dayStart: Timestamp, dayEnd: Timestamp |
| Outputs |
Applications { shift, shiftRole, status, createdAt } |
| Notes |
The frontend filters the query response for CONFIRMED applications to successfully display "Today's" and "Tomorrow's" shifts. |
List Recommended Shifts
| Field |
Description |
| Conceptual Endpoint |
GET /shifts/recommended |
| Data Connect OP |
listShifts |
| Purpose |
Fetches open shifts that are available for the staff to apply to. |
| Operation |
Query |
| Inputs |
None directly mapped on load, but fetches available items logically. |
| Outputs |
Shifts { id, title, orderId, cost, location, startTime, endTime, status } |
| Notes |
Limits output to 10 on the frontend. Should ideally rely on an active backend $status: OPEN parameter. |
Benefits Summary API
| Field |
Description |
| Conceptual Endpoint |
GET /staff/{staffId}/benefits |
| Data Connect OP |
listBenefitsDataByStaffId |
| Purpose |
Retrieves accrued benefits (e.g., Sick time, Vacation) to display gracefully on the home screen. |
| Operation |
Query |
| Inputs |
staffId: UUID! |
| Outputs |
BenefitsDatas { vendorBenefitPlan { title, total }, current } |
| Notes |
Used by benefits_overview_page.dart. Derives available metrics via usedHours = total - current. |
Find Shifts / Shift Details Pages
(Pages: shifts_page.dart, shift_details_page.dart)
List Available Shifts Filtered
| Field |
Description |
| Conceptual Endpoint |
GET /shifts |
| Data Connect OP |
filterShifts |
| Purpose |
Used to fetch Open Shifts in specific regions when the worker searches in the "Find Shifts" tab. |
| Operation |
Query |
| Inputs |
$status: ShiftStatus, $dateFrom: Timestamp, $dateTo: Timestamp |
| Outputs |
Shifts { id, title, location, cost, durationDays, order { business, vendor } } |
| Notes |
Main driver for discovering available work. |
Get Shift Details
| Field |
Description |
| Conceptual Endpoint |
GET /shifts/{id} |
| Data Connect OP |
getShiftById |
| Purpose |
Gets deeper details for a single shift including exact uniform requirements and managers. |
| Operation |
Query |
| Inputs |
id: UUID! |
| Outputs |
Shift { id, title, hours, cost, locationAddress, workersNeeded ... } |
| Notes |
Invoked when users click into a full shift_details_page.dart. |
Apply To Shift
| Field |
Description |
| Conceptual Endpoint |
POST /applications |
| Data Connect OP |
createApplication |
| Purpose |
Worker submits an intent to take an open shift (creates an application record). |
| Operation |
Mutation |
| Inputs |
shiftId: UUID!, staffId: UUID!, roleId: UUID!, status: ApplicationStatus! (e.g. PENDING or CONFIRMED), origin: ApplicationOrigin! (e.g. STAFF); optional: checkInTime, checkOutTime |
| Outputs |
application_insert.id (Application ID) |
| Notes |
The app uses status: CONFIRMED and origin: STAFF when claiming; backend also supports PENDING for admin review flows. After creation, shift-role assigned count and shift filled count are updated. |
Availability Page
(Pages: availability_page.dart)
Get Default Availability
| Field |
Description |
| Conceptual Endpoint |
GET /staff/{staffId}/availabilities |
| Data Connect OP |
listStaffAvailabilitiesByStaffId |
| Purpose |
Fetches the standard Mon-Sun recurring availability for a staff member. |
| Operation |
Query |
| Inputs |
staffId: UUID! |
| Outputs |
StaffAvailabilities { dayOfWeek, isAvailable, startTime, endTime } |
| Notes |
Bound to Monday through Sunday configuration. |
Update Availability
| Field |
Description |
| Conceptual Endpoint |
PUT /staff/availabilities/{id} |
| Data Connect OP |
updateStaffAvailability (or createStaffAvailability for new entries) |
| Purpose |
Upserts availability preferences. |
| Operation |
Mutation |
| Inputs |
staffId, dayOfWeek, isAvailable, startTime, endTime |
| Outputs |
id |
| Notes |
Called individually per day edited. |
Payments Page
(Pages: payments_page.dart, early_pay_page.dart)
Get Recent Payments
| Field |
Description |
| Conceptual Endpoint |
GET /staff/{staffId}/payments |
| Data Connect OP |
listRecentPaymentsByStaffId |
| Purpose |
Loads the history of earnings and timesheets completed by the staff. |
| Operation |
Query |
| Inputs |
staffId: UUID! |
| Outputs |
Payments { amount, processDate, shiftId, status } |
| Notes |
Displays historical metrics under the comprehensive Earnings tab. |
Compliance / Profiles
(Pages: certificates_page.dart, documents_page.dart, tax_forms_page.dart, form_i9_page.dart, form_w4_page.dart)
Get Tax Forms
| Field |
Description |
| Conceptual Endpoint |
GET /staff/{staffId}/tax-forms |
| Data Connect OP |
getTaxFormsByStaffId |
| Purpose |
Check the filing status and detailed inputs of I9 and W4 forms. |
| Operation |
Query |
| Inputs |
staffId: UUID! |
| Outputs |
TaxForms { formType, isCompleted, updatedDate } |
| Notes |
Crucial requirement for staff to be eligible to apply for highly regulated shifts. |
Update Tax Forms
| Field |
Description |
| Conceptual Endpoint |
PUT /tax-forms/{id} |
| Data Connect OP |
updateTaxForm |
| Purpose |
Submits state and filing for the given tax form type (W4/I9). |
| Operation |
Mutation |
| Inputs |
id, dataPoints... |
| Outputs |
id |
| Notes |
Modifies the core compliance state variables directly. |
Client Application
Authentication / Intro
(Pages: client_sign_in_page.dart, client_get_started_page.dart)
Client User Validation API
| Field |
Description |
| Conceptual Endpoint |
GET /users/{id} |
| Data Connect OP |
getUserById |
| Purpose |
Retrieves the base user profile to determine authentication status and role access (ensuring user is BUSINESS). |
| Operation |
Query |
| Inputs |
id: UUID! (Firebase UID) |
| Outputs |
User { id, email, phone, userRole } |
| Notes |
Validates against conditional statements checking userRole == BUSINESS or BOTH. |
Get Businesses By User API
| Field |
Description |
| Conceptual Endpoint |
GET /business/user/{userId} |
| Data Connect OP |
getBusinessesByUserId |
| Purpose |
Maps the authenticated user to their client business context. |
| Operation |
Query |
| Inputs |
userId: String! |
| Outputs |
Businesses { id, businessName, email, contactName } |
| Notes |
Dictates the working scopes (Business ID) across the entire application lifecycle and binds the user. |
Hubs Page
(Pages: client_hubs_page.dart, edit_hub_page.dart, hub_details_page.dart)
List Hubs by Team
| Field |
Description |
| Conceptual Endpoint |
GET /teams/{teamId}/hubs |
| Data Connect OP |
getTeamHubsByTeamId |
| Purpose |
Fetches the primary working sites (Hubs) for a client context by using Team mapping. |
| Operation |
Query |
| Inputs |
teamId: UUID! |
| Outputs |
TeamHubs { id, hubName, address, managerName, isActive } |
| Notes |
teamId is derived first from getTeamsByOwnerId(ownerId: businessId). |
Create / Update / Delete Hub
| Field |
Description |
| Conceptual Endpoint |
POST /team-hubs / PUT /team-hubs/{id} / DELETE /team-hubs/{id} |
| Data Connect OP |
createTeamHub / updateTeamHub / deleteTeamHub |
| Purpose |
Provisions, Edits details directly, or Removes a Team Hub location. |
| Operation |
Mutation |
| Inputs |
id: UUID!, optionally hubName, address, etc. |
| Outputs |
id |
| Notes |
Fired from edit_hub_page.dart mutations. |
Orders Page
(Pages: create_order_page.dart, view_orders_page.dart, recurring_order_page.dart)
Create Order
| Field |
Description |
| Conceptual Endpoint |
POST /orders |
| Data Connect OP |
createOrder |
| Purpose |
Submits a new request for temporary staff requirements. |
| Operation |
Mutation |
| Inputs |
businessId, eventName, orderType, status |
| Outputs |
id (Order ID) |
| Notes |
This explicitly invokes an order pipeline, meaning Shift instances are subsequently created through secondary mutations triggered after order instantiation. |
List Orders
| Field |
Description |
| Conceptual Endpoint |
GET /business/{businessId}/orders |
| Data Connect OP |
listOrdersByBusinessId |
| Purpose |
Retrieves all ongoing and past staff requests from the client. |
| Operation |
Query |
| Inputs |
businessId: UUID! |
| Outputs |
Orders { id, eventName } |
| Notes |
Populates the view_orders_page.dart. |
Billing Pages
(Pages: billing_page.dart, pending_invoices_page.dart, completion_review_page.dart)
List Invoices
| Field |
Description |
| Conceptual Endpoint |
GET /business/{businessId}/invoices |
| Data Connect OP |
listInvoicesByBusinessId |
| Purpose |
Fetches all invoices bound directly to the active business context (mapped directly in Firebase Schema). |
| Operation |
Query |
| Inputs |
businessId: UUID! |
| Outputs |
Invoices { id, amount, issueDate, status } |
| Notes |
Used massively across all Billing view tabs. |
Mark / Dispute Invoice
| Field |
Description |
| Conceptual Endpoint |
PUT /invoices/{id} |
| Data Connect OP |
updateInvoice |
| Purpose |
Actively marks an invoice as disputed or pays it directly (altering status). |
| Operation |
Mutation |
| Inputs |
id: UUID!, status: InvoiceStatus |
| Outputs |
id |
| Notes |
Disputing usually involves setting a disputeReason flag state dynamically via builder pattern. |
Reports Page
(Pages: reports_page.dart, coverage_report_page.dart, performance_report_page.dart)
Get Coverage Stats
| Field |
Description |
| Conceptual Endpoint |
GET /business/{businessId}/coverage |
| Data Connect OP |
listShiftsForCoverage |
| Purpose |
Provides data on Shifts grouped by Date for fulfillment calculations. |
| Operation |
Query |
| Inputs |
businessId: UUID!, startDate: Timestamp!, endDate: Timestamp! |
| Outputs |
Shifts { id, date, workersNeeded, filled, status } |
| Notes |
The frontend aggregates the raw backend rows to compose Coverage percentage natively. |
Get Daily Ops Stats
| Field |
Description |
| Conceptual Endpoint |
GET /business/{businessId}/dailyops |
| Data Connect OP |
listShiftsForDailyOpsByBusiness |
| Purpose |
Supplies current day operations and shift tracking progress. |
| Operation |
Query |
| Inputs |
businessId: UUID!, date: Timestamp! |
| Outputs |
Shifts { id, title, location, workersNeeded, filled } |
| Notes |
- |
Get Forecast Stats
| Field |
Description |
| Conceptual Endpoint |
GET /business/{businessId}/forecast |
| Data Connect OP |
listShiftsForForecastByBusiness |
| Purpose |
Retrieves scheduled future shifts to calculate financial run-rates. |
| Operation |
Query |
| Inputs |
businessId: UUID!, startDate: Timestamp!, endDate: Timestamp! |
| Outputs |
Shifts { id, date, workersNeeded, hours, cost } |
| Notes |
The App maps hours x cost to deliver Financial Dashboards. |
Get Performance KPIs
| Field |
Description |
| Conceptual Endpoint |
GET /business/{businessId}/performance |
| Data Connect OP |
listShiftsForPerformanceByBusiness |
| Purpose |
Fetches historical data allowing time-to-fill and completion-rate calculations. |
| Operation |
Query |
| Inputs |
businessId: UUID!, startDate: Timestamp!, endDate: Timestamp! |
| Outputs |
Shifts { id, workersNeeded, filled, createdAt, filledAt } |
| Notes |
Data Connect exposes timestamps so the App calculates avgFillTimeHours. |
Get No-Show Metrics
| Field |
Description |
| Conceptual Endpoint |
GET /business/{businessId}/noshows |
| Data Connect OP |
listShiftsForNoShowRangeByBusiness |
| Purpose |
Retrieves shifts where workers historically ghosted the platform. |
| Operation |
Query |
| Inputs |
businessId: UUID!, startDate: Timestamp!, endDate: Timestamp! |
| Outputs |
Shifts { id, date } |
| Notes |
Accompanies listApplicationsForNoShowRange cascading querying to generate full report. |
Get Spend Analytics
| Field |
Description |
| Conceptual Endpoint |
GET /business/{businessId}/spend |
| Data Connect OP |
listInvoicesForSpendByBusiness |
| Purpose |
Detailed invoice aggregates for Spend metrics filtering. |
| Operation |
Query |
| Inputs |
businessId: UUID!, startDate: Timestamp!, endDate: Timestamp! |
| Outputs |
Invoices { id, issueDate, dueDate, amount, status } |
| Notes |
Used explicitly under the "Spend Report" graphings. |
This document meticulously abstracts the underlying Data Connect Data-layer definitions implemented natively across the frontend. It maps the queries/mutations to recognizable REST equivalents for comprehensive and top-notch readability by external and internal developers alike.
