KROW Workforce API Contracts
This document captures all API contracts used by the Staff and Client mobile applications. It serves as a single reference document to understand what each endpoint does, its expected inputs, returned outputs, and any non-obvious details.
Staff Application
Authentication / Onboarding Pages (Get Started, Intro, Phone Verification, Profile Setup, Personal Info)
Setup / User Validation API
| Field |
Description |
| Endpoint name |
/getUserById |
| Purpose |
Retrieves the base user profile to determine authentication status and role access (e.g., if user is STAFF). |
| Operation |
Query |
| Inputs |
id: UUID! (Firebase UID) |
| Outputs |
User { id, email, phone, role } |
| Notes |
Required after OTP verification to route users. |
Create Default User API
| Field |
Description |
| Endpoint name |
/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 exist. |
Get Staff Profile API
| Field |
Description |
| Endpoint name |
/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 fully authenticating. |
Update Staff Profile API
| Field |
Description |
| Endpoint name |
/updateStaff |
| Purpose |
Saves onboarding data across Personal Info, Experience, and Preferred Locations pages. |
| Operation |
Mutation |
| Inputs |
id: UUID!, fullName, email, phone, addres, etc. |
| Outputs |
id |
| Notes |
Called incrementally during profile setup wizard. |
Home Page (worker_home_page.dart) & Benefits Overview
Load Today/Tomorrow Shifts
| Field |
Description |
| Endpoint name |
/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 display "Today's" and "Tomorrow's" shifts. |
List Recommended Shifts
| Field |
Description |
| Endpoint name |
/listShifts |
| Purpose |
Fetches open shifts that are available for the staff to apply to. |
| Operation |
Query |
| Inputs |
None directly mapped, but filters OPEN shifts purely on the client side at the time. |
| Outputs |
Shifts { id, title, orderId, cost, location, startTime, endTime, status } |
| Notes |
Limits output to 10 on the frontend. Should ideally rely on a $status: OPEN parameter. |
Benefits Summary API
| Field |
Description |
| Endpoint name |
/listBenefitsDataByStaffId |
| Purpose |
Retrieves accrued benefits (e.g., Sick time, Vacation) to display on the home screen. |
| Operation |
Query |
| Inputs |
staffId: UUID! |
| Outputs |
BenefitsDatas { vendorBenefitPlan { title, total }, current } |
| Notes |
Calculates usedHours = total - current. |
Find Shifts / Shift Details Pages (shifts_page.dart)
List Available Shifts Filtered
| Field |
Description |
| Endpoint name |
/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 |
- |
Get Shift Details
| Field |
Description |
| Endpoint name |
/getShiftById |
| Purpose |
Gets deeper details for a single shift including exact uniform/managers needed. |
| Operation |
Query |
| Inputs |
id: UUID! |
| Outputs |
Shift { id, title, hours, cost, locationAddress, workersNeeded ... } |
| Notes |
- |
Apply To Shift
| Field |
Description |
| Endpoint name |
/createApplication |
| Purpose |
Worker submits an intent to take an open shift. |
| Operation |
Mutation |
| Inputs |
shiftId, staffId, status: APPLIED |
| Outputs |
Application ID |
| Notes |
A shift status will switch to CONFIRMED via admin approval. |
Availability Page (availability_page.dart)
Get Default Availability
| Field |
Description |
| Endpoint name |
/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 |
- |
Update Availability
| Field |
Description |
| Endpoint name |
/updateStaffAvailability (or createStaffAvailability) |
| Purpose |
Upserts availability preferences. |
| Operation |
Mutation |
| Inputs |
staffId, dayOfWeek, isAvailable, startTime, endTime |
| Outputs |
id |
| Notes |
Called individually per day edited. |
Payments Page (payments_page.dart)
Get Recent Payments
| Field |
Description |
| Endpoint name |
/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 Earnings tab. |
Compliance / Profiles (Agreements, W4, I9, Documents)
Get Tax Forms
| Field |
Description |
| Endpoint name |
/getTaxFormsByStaffId |
| Purpose |
Check the filing status of I9 and W4 forms. |
| Operation |
Query |
| Inputs |
staffId: UUID! |
| Outputs |
TaxForms { formType, isCompleted, updatedDate } |
| Notes |
Required for staff to be eligible for shifts. |
Update Tax Forms
| Field |
Description |
| Endpoint name |
/updateTaxForm |
| Purpose |
Submits state and filing for the given tax form type. |
| Operation |
Mutation |
| Inputs |
id, dataPoints... |
| Outputs |
id |
| Notes |
Updates compliance state. |
Client Application
Authentication / Intro (Sign In, Get Started)
Client User Validation API
| Field |
Description |
| Endpoint name |
/getUserById |
| Purpose |
Retrieves the base user profile to determine authentication status and role access (e.g., if user is BUSINESS). |
| Operation |
Query |
| Inputs |
id: UUID! (Firebase UID) |
| Outputs |
User { id, email, phone, userRole } |
| Notes |
Must check if userRole == BUSINESS or BOTH. |
Get Business Profile API
| Field |
Description |
| Endpoint name |
/getBusinessByUserId |
| Purpose |
Maps the authenticated user to their client business context. |
| Operation |
Query |
| Inputs |
userId: UUID! |
| Outputs |
Business { id, businessName, email, contactName } |
| Notes |
Used to set the working scopes (Business ID) across the entire app. |
Hubs Page (client_hubs_page.dart, edit_hub.dart)
List Hubs
| Field |
Description |
| Endpoint name |
/listTeamHubsByBusinessId |
| Purpose |
Fetches the primary working sites (Hubs) for a client. |
| Operation |
Query |
| Inputs |
businessId: UUID! |
| Outputs |
TeamHubs { id, hubName, address, contact, active } |
| Notes |
- |
Update / Delete Hub
| Field |
Description |
| Endpoint name |
/updateTeamHub / /deleteTeamHub |
| Purpose |
Edits or archives a Hub location. |
| Operation |
Mutation |
| Inputs |
id: UUID!, hubName, address, etc (for Update) |
| Outputs |
id |
| Notes |
- |
Orders Page (create_order, view_orders)
Create Order
| Field |
Description |
| Endpoint name |
/createOrder |
| Purpose |
The client submits a new request for temporary staff (can result in multiple Shifts generated on the backend). |
| Operation |
Mutation |
| Inputs |
businessId, eventName, orderType, status |
| Outputs |
id (Order ID) |
| Notes |
This creates an order. Shift instances are subsequently created through secondary mutations. |
List Orders
| Field |
Description |
| Endpoint name |
/getOrdersByBusinessId |
| Purpose |
Retrieves all ongoing and past staff requests from the client. |
| Operation |
Query |
| Inputs |
businessId: UUID! |
| Outputs |
Orders { id, eventName, shiftCount, status } |
| Notes |
- |
Billing Pages (billing_page.dart, pending_invoices)
List Invoices
| Field |
Description |
| Endpoint name |
/listInvoicesByBusinessId |
| Purpose |
Fetches "Pending", "Paid", and "Disputed" invoices for the client to review. |
| Operation |
Query |
| Inputs |
businessId: UUID! |
| Outputs |
Invoices { id, amountDue, issueDate, status } |
| Notes |
Used across all Billing view tabs. |
Mark Invoice
| Field |
Description |
| Endpoint name |
/updateInvoice |
| Purpose |
Marks an invoice as disputed or pays it (changes status). |
| Operation |
Mutation |
| Inputs |
id: UUID!, status: InvoiceStatus |
| Outputs |
id |
| Notes |
Disputing usually involves setting a memo or flag. |
Reports Page (reports_page.dart)
Get Coverage Stats
| Field |
Description |
| Endpoint name |
/getCoverageStatsByBusiness |
| Purpose |
Provides data on fulfillments rates vs actual requests. |
| Operation |
Query |
| Inputs |
businessId: UUID! |
| Outputs |
Stats { totalRequested, totalFilled, percentage } |
| Notes |
Driven mostly by aggregated backend views. |
This document reflects the current state of Data Connect definitions implemented across the frontend and mapped manually by reviewing Repository and UI logic.
