Krow/Krow-workspace
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d3159bc2ae7592bbd99bc51ba72f3a48492786a3
Krow-workspace/docs/BACKEND/API_GUIDES/mobile-backend-api-specification.md

37 KiB
Raw Blame History

KROW Mobile Backend API Specification

Generated: 2026-03-12

Client Application

Feature: Authentication

API - 1

API Type: POST Description: Signs in a client user using email and password. Authenticates the user against the identity provider and returns a session token.

Inputs:

  • Email address of the user.
  • Password of the user.

Returns:

  • Authenticated user profile (identifier, name, email, role).
  • Session token for subsequent authenticated requests.

API - 2

API Type: POST Description: Registers a new client user and creates an associated business entity. The backend creates the identity record, the user record, and a business entity in a single transactional flow. Rolls back all created resources if any step fails.

Inputs:

  • Company name for the new business.
  • Email address of the user.
  • Password for the new account.

Returns:

  • Authenticated user profile (identifier, name, email, role).
  • Newly created business identifier.
  • Session token for subsequent authenticated requests.

API - 3

API Type: POST Description: Signs out the currently authenticated client user. Invalidates the active session and clears any server-side session state.

Inputs:

  • Session token (via authorization header).

Returns:

  • Confirmation of successful sign-out.

Feature: Billing

API - 1

API Type: GET Description: Returns all bank accounts associated with the client's business.

Inputs:

  • Business identifier (derived from authenticated session).

Returns:

  • List of bank accounts, each containing: account identifier, bank name, account number (masked), routing number, account type, and primary status.

API - 2

API Type: GET Description: Returns all pending invoices (open or disputed) for the business.

Inputs:

  • Business identifier (derived from authenticated session).

Returns:

  • List of pending invoices, each containing: invoice identifier, amount, status (open/disputed), due date, and associated vendor information.

API - 3

API Type: GET Description: Returns the full invoice history for the business, including paid and completed invoices.

Inputs:

  • Business identifier (derived from authenticated session).

Returns:

  • List of historical invoices, each containing: invoice identifier, amount, status, payment date, and associated vendor information.

API - 4

API Type: GET Description: Returns the current outstanding bill amount for the active billing period (specific time period).

Inputs:

  • Business identifier (derived from authenticated session).

Returns:

  • Current bill amount as a monetary value.

API - 5

API Type: GET Description: Returns the total savings amount accumulated by the business.

Inputs:

  • Business identifier (derived from authenticated session).

Returns:

  • Savings amount as a monetary value.

API - 6

API Type: GET Description: Returns a detailed spending breakdown for a given billing period, grouped by role and industry.

Inputs:

  • Business identifier (derived from authenticated session).
  • Billing period (specific time period).

Returns:

  • List of spending line items, each containing: category name, amount, and percentage of total spend.

API - 7

API Type: POST Description: Approves a pending invoice, marking it as accepted for payment.

Inputs:

  • Invoice identifier.

Returns:

  • Updated invoice status (approved).

API - 8

API Type: POST Description: Disputes an invoice, recording the dispute reason and changing its status.

Inputs:

  • Invoice identifier.
  • Reason for the dispute.

Returns:

  • Updated invoice status (disputed).

Feature: Client Coverage

API - 1

API Type: GET Description: Returns all shift coverage information for a specific date. Includes shift details along with assigned worker status (confirmed, checked-in, en route, late).

Inputs:

  • Business identifier (derived from authenticated session).
  • Date for which to retrieve coverage.

Returns:

  • List of coverage shifts, each containing: shift identifier, role name, time range, required worker count, and list of assigned workers with their current status and check-in times.

API - 2

API Type: GET Description: Returns aggregated coverage statistics for a specific date. Provides summary counts of staffing needs vs. fulfillment.

Inputs:

  • Business identifier (derived from authenticated session).
  • Date for which to retrieve statistics.

Returns:

  • Total coverage percentage.
  • Total positions needed.
  • Total positions confirmed.
  • Total workers checked in.
  • Total workers en route.
  • Total workers late.

API - 3

API Type: POST Description: Rate a worker.

Inputs:

  • worker id.
  • Number of starts of a user.
  • Mark as favourite
  • Issue flags.
  • Feedback

Returns:

  • return those exact values, that we updated.

API - 4

API Type: POST Description: Cancel a worker who's running late.

Inputs:

  • worker id.
  • order details and shift details if required.

Returns:

Note:

  • Also, by doing this the system need to automatically prompts to search the workers for the shift.

API - 5

API Type: GET Description: View the workers of the core team.

Feature: Home (Client Dashboard)

API - 1

API Type: GET Description: Returns aggregated dashboard data for the client's business, including spending summaries and shift statistics for the current and upcoming week.

Inputs:

  • Business identifier (derived from authenticated session).

Returns:

  • Spending oversights
  • Weekly spending amount.
  • Next 7 days projected spending.
  • Coverage.
  • Today's needed workers
  • Today's filled workers
  • Today's position opend
  • Live activity
  • Today's worker's running late
  • Avg. today's cost
  • Checked in
  • Today's position opend

API - 2

API Type: GET Description: Returns user session data including the business name and user profile information for dashboard display.

Inputs:

  • User identifier (derived from authenticated session).

Returns:

  • User name.
  • Business name.
  • Business identifier.

API - 3

API Type: GET Description: Returns a list of recent orders that are eligible for reordering.

Inputs:

  • Business identifier (derived from authenticated session).

Returns:

  • List of recent reorder items, each containing: order identifier, order title, date, hub name, and number of positions, order type.

Feature: Hubs

API - 1

API Type: GET Description: Returns all team hubs belonging to the client's business.

Inputs:

  • Business identifier (derived from authenticated session).

Returns:

  • List of hubs, each containing: hub identifier, name, full address, coordinates (latitude/longitude), city, state, zip code, associated cost center, and NFC tag identifier if assigned.

API - 2

API Type: GET Description: Returns all cost centers (departments) available for the business.

Inputs:

  • Business identifier (derived from authenticated session).

Returns:

  • List of cost centers, each containing: cost center identifier and name.

API - 3

API Type: POST Description: Creates a new team hub for the business. Geocodes the provided address and creates associated team and cost center records as needed.

Inputs:

  • Hub name.
  • Full address string.
  • Google Place ID (optional, for geocoding).
  • Latitude and longitude (optional, derived if place ID provided).
  • City, state, street, country, zip code (optional).
  • Cost center identifier (optional).

Returns:

  • Newly created hub with full details including: hub identifier, name, resolved address, coordinates, and associated cost center.

API - 4

API Type: PUT Description: Updates an existing team hub's information.

Inputs:

  • Hub identifier.
  • Updated hub name (optional).
  • Updated address and location fields (optional).
  • Updated cost center identifier (optional).

Returns:

  • Updated hub with full details.

API - 5

API Type: DELETE Description: Deletes a team hub. Validates that no active orders reference the hub before deletion.

Inputs:

  • Hub identifier.

Returns:

  • Confirmation of successful deletion (cannot delete if alreaddy order's are assigned to it)

API - 6

API Type: POST Description: Assigns an NFC tag to a team hub for contactless check-in support.

Inputs:

  • Hub identifier.
  • NFC tag identifier.

Returns:

  • Confirmation of successful assignment.

Feature: Orders — Create Order

API - 1

API Type: GET Description: Returns the list of vendors available to the client's business for order creation.

Inputs:

  • Business identifier (derived from authenticated session).

Returns:

  • List of vendors, each containing: vendor identifier and vendor name.

API - 2

API Type: GET Description: Returns the list of worker roles available from a specific vendor.

Inputs:

  • Vendor identifier.

Returns:

  • List of roles, each containing: role identifier, role name, and hourly rate.

API - 3

API Type: GET Description: Returns the list of hubs owned by the authenticated business for selection during order creation.

Inputs:

  • Business identifier (derived from authenticated session).

Returns:

  • List of hubs, each containing: hub identifier and hub name.

API - 4

API Type: GET Description: Returns the list of managers assigned to a specific hub for order assignment.

Inputs:

  • Hub identifier.

Returns:

  • List of managers, each containing: manager identifier and manager name.

API - 4

API Type: POST Description: Create a new manager for the hub from the team memebers of the business

Inputs:

  • Hub identifier.
  • team memeber id

Returns:

API - 5

API Type: POST Description: Creates a new one-time order with one or more positions. This is a transactional operation that creates the order record, an associated shift, and individual shift role entries for each requested position. Updates the order with shift references upon completion.

Inputs:

  • Hub identifier.
  • Vendor identifier.
  • Event name.
  • Order date.
  • List of positions, each containing:
    • Role identifier.
    • Number of workers needed.
    • Start time.
    • End time.
    • Lunch break duration and whether it is paid.
    • Hourly rate.

Returns:

  • Created order identifier.
  • Created shift identifier.
  • Order status (posted).

API - 6

API Type: POST Description: Creates a new recurring order that repeats on a defined schedule with specified positions.

Inputs:

  • Hub identifier.
  • Vendor identifier (optional).
  • Event name (optional).
  • Start date and end date defining the recurrence window.
  • Recurrence pattern (e.g., days of week).
  • List of positions with role, count, time range, break, and rate details.

Returns:

  • Created order identifier.
  • Order status (posted).

API - 7

API Type: POST Description: Creates a new permanent staffing order for ongoing coverage at a hub.

Inputs:

  • Hub identifier.
  • Vendor identifier (optional).
  • Start date.
  • List of positions with role, count, time range, break, and rate details.

Returns:

  • Created order identifier.
  • Order status (posted).

API - 9

API Type: POST Description: Edit an existing past order/shift.

  • need one for each type (one-time, recurring and permanent)

Inputs:

  • Original order identifier.
  • This gets the details for each order

Returns:

  • Newly created order identifier.
  • Order status (posted).

Note:

  • Need to verify if whether we are changing the only the current shift or the entire order when editing.

API - 10

API Type: GET Description: Returns the full details of a previous order for reorder preview purposes.

Inputs:

  • Order identifier.

Returns:

  • Order details including: hub, vendor, event name, positions (role, count, times, rates), and original date.

Feature: Orders — View Orders

API - 1

API Type: GET Description: Returns all shift roles (order line items) for a given date range, grouped by day. Each item represents a specific role on a specific shift within an order.

Inputs:

  • Business identifier (derived from authenticated session).
  • Start date of the range.
  • End date of the range.

Returns:

  • List of order items, each containing: item identifier, order identifier, order type (one-time/recurring/permanent), role name, date, start and end times, required worker count, filled count, hourly rate, total cost, location name, current status and lists of accepted worker details, each containing: application identifier, worker name, role, and confirmation status.

Feature: Reports

API - 1

API Type: GET Description: Returns a summary across all report categories for a given date range. Provides top-level metrics for the reports dashboard.

Inputs:

  • Business identifier (derived from authenticated session).
  • Start date of the report period.
  • End date of the report period.

Returns:

  • Total shifts.
  • Total spend.
  • Average coverage percentage.
  • Average performance score.
  • No-show count.
  • Forecast accuracy percentage.

API - 2

API Type: GET Description: Returns the daily operations report for a specific date. Includes shift-level metrics broken down by role and status.

Inputs:

  • Business identifier (derived from authenticated session).
  • Report date.

Returns:

  • Total shifts for the day.
  • Total workers deployed.
  • Total hours worked.
  • On-time arrival percentage.
  • List of shifts with role, status, worker count, start and end times.

API - 3

API Type: GET Description: Returns the spending report for a date range. Includes spend grouped by time period and by industry/role.

Inputs:

  • Business identifier (derived from authenticated session).
  • Start date of the report period.
  • End date of the report period.

Returns:

  • Total spend for the period.
  • Spend grouped by day or week (for charting).
  • Spend breakdown by role and industry category.

API - 4

API Type: GET Description: Returns the coverage report for a date range. Shows how well staffing needs were met over time.

Inputs:

  • Business identifier (derived from authenticated session).
  • Start date of the report period.
  • End date of the report period.

Returns:

  • Average coverage percentage for the period
  • Filled workers for the period
  • Need workers for the period.
  • Daily coverage rates (for charting) for each day in the period

API - 5

API Type: GET Description: Returns the forecast report for a date range. Projects future staffing needs based on historical patterns.

Inputs:

  • Business identifier (derived from authenticated session).
  • Start date of the report period.
  • End date of the report period.

Returns:

  • Forecast spend for the period
  • Average weekly for the period.
  • Total shifts for the period.
  • Total worker hours for the period.
  • Spending forecast for each week in the period (for charting).
  • Weekly breakdown
    • no. of shifts
    • total no. of worker hours.
    • avg/shift cost

API - 6

API Type: GET Description: Returns the performance report for a date range. Includes worker and shift quality metrics.

Inputs:

  • Business identifier (derived from authenticated session).
  • Start date of the report period.
  • End date of the report period.

Returns:

  • Average performance score (whether excellent or not)
  • Fill Rate (with met or not).
  • Completion rate (with met or not).
  • On-time rate (with met or not).
  • Avg. Fill Time (with met or not).
  • Total Shifts covered.
  • No-show rate

API - 7

API Type: GET Description: Returns the no-show report for a date range. Tracks workers who failed to appear for assigned shifts.

Inputs:

  • Business identifier (derived from authenticated session).
  • Start date of the report period.
  • End date of the report period.

Returns:

  • Total no-show count.
  • No-show rate as a percentage.
  • No. of workers who no-showed.
  • List of workers who no-showed.
    • Risk status of whether they would it do it again
    • List of no-show incidents with shift, role, date for each worker

Feature: Settings

API - 1

API Type: POST Description: Signs out the currently authenticated client user and clears all server-side session data.

Inputs:

  • Session token (via authorization header).

Returns:

  • Confirmation of successful sign-out.

Staff Application

Feature: Authentication

API - 1

API Type: POST Description: Initiates phone-based authentication by sending an OTP to the provided phone number.

Inputs:

  • Phone number of the staff user.

Returns:

  • Verification identifier to be used when submitting the OTP code.

API - 2

API Type: POST Description: Verifies the OTP code submitted by the staff user. If the user account does not exist, creates a new user record. Returns authentication session and user profile.

Inputs:

  • Verification identifier (from the phone-initiation step).
  • OTP code entered by the user.
  • Authentication mode (sign-in or sign-up).

Returns:

  • Authenticated user profile (identifier, name, phone, role).
  • Session token for subsequent authenticated requests.
  • Flag indicating if this is a new user (profile setup required).

API - 3

API Type: POST Description: Signs out the currently authenticated staff user and clears server-side session state.

Inputs:

  • Session token (via authorization header).

Returns:

  • Confirmation of successful sign-out.

API - 4

API Type: POST Description: Submits the initial profile setup for a newly registered staff user. Creates the staff record with personal details, preferences, and skills.

Inputs:

  • Full name of the staff member.
  • Bio (optional).
  • Phone number
  • List of preferred work locations (cities saved with Lat and Long).
  • Maximum commute distance in miles.
  • List of preferred industries.
  • List of skills.

Returns:

  • Created staff profile identifier.
  • Confirmation of successful profile creation.

Feature: Availability

API - 1

API Type: GET Description: Returns the weekly availability schedule for the staff member over a given date range. The backend maps recurring weekly slots to specific dates in the requested range.

Inputs:

  • Staff identifier (derived from authenticated session).
  • Start date of the range.
  • End date of the range (typically start + 6 days).

Returns:

  • List of day availability entries, each containing: date, day of week, availability status (available/unavailable/partial), and time slots with start and end times.

API - 2

API Type: PUT Description: Updates the recurring availability for a specific day of the week. Sets or modifies the time slots during which the staff member is available to work.

Inputs:

  • Staff identifier (derived from authenticated session).
  • Day of week.
  • Availability status (available/unavailable/partial).
  • List of time slots with start and end times (for partial availability).

Returns:

  • Updated day availability entry with resolved slots.

API - 3

API Type: POST Description: Applies a quick-set availability template across a date range. Supports preset patterns such as "available all days", "weekdays only", "weekends only", or "clear all".

Inputs:

  • Staff identifier (derived from authenticated session).
  • Start date of the range.
  • End date of the range.
  • Quick-set type (all/weekdays/weekends/clear).

Returns:

  • Updated list of day availability entries for the full range.

Feature: Clock In

API - 1

API Type: GET Description: Returns all shifts the staff member is assigned to for the current day, ordered by proximity to the current time.

Inputs:

  • Staff identifier (derived from authenticated session).

Returns:

  • List of today's shifts, each containing: shift identifier, role name, location, start time, end time, and current attendance status.

API - 2

API Type: GET Description: Returns the current attendance status of the staff member (e.g., not clocked in, clocked in, on break, clocked out).

Inputs:

  • Staff identifier (derived from authenticated session).

Returns:

  • Current attendance status.
  • Active shift identifier (if clocked in).
  • Clock-in timestamp (if clocked in).

API - 3

API Type: POST Description: Records a clock-in event for the staff member on a specific shift. Validates that the shift is assigned to the user and within the allowed clock-in window.

Inputs:

  • Staff identifier (derived from authenticated session).
  • Shift identifier.
  • Notes (optional).

Returns:

  • Updated attendance status (clocked in).
  • Clock-in timestamp.

API - 4

API Type: POST Description: Records a clock-out event for the staff member. Captures total break time and optional notes.

Inputs:

  • Staff identifier (derived from authenticated session).
  • Notes (optional).
  • Break time in minutes (optional).
  • Application identifier (optional, for specific shift tracking).

Returns:

  • Updated attendance status (clocked out).
  • Clock-out timestamp.
  • Total hours worked.

Feature: Home (Staff Dashboard)

APIs

API Type: GET Description: Returns the staff member's dashboard data including today's shifts, tomorrow's shifts, recommended shifts, and benefits.

Inputs:

  • Staff identifier (derived from authenticated session).

Returns:

  • If possible create seperate endpoint for each of the following
    • Staff member's name.
    • List of today's confirmed shifts.
    • List of tomorrow's confirmed shifts.
    • List of recommended open shifts.
    • List of active benefits with hours tracking.

API - 2

API Type: GET Description: Returns the status of the worker profile completion status.

Inputs:

  • Workr id.

Returns:

  • If the worker profile is fully completed (if not they cannot apply to shifts and not show the clock-in, my shifts and assigned shifts). The profile is complete when the worker has properly filled
    • First name
    • Last name
    • email
    • phone nubmer
    • preffered locations
    • skills
    • industries
    • emergency contact

Feature: Payments

API - 1

API Type: GET Description: Returns the payment summary for the staff member, for the given period.

Inputs:

  • Staff identifier (derived from authenticated session).

Returns:

  • Total Earnings for the given period.

API - 2

API Type: GET Description: Returns the payment history for the staff member filtered by time period.

Inputs:

  • Staff identifier (derived from authenticated session).
  • Period filter (for the given period)

Returns:

  • List of payment entries, each containing: payment identifier, amount, date, status (paid/pending), associated shift name, location, hourly rate, and hours worked.

API - 3

API Type: GET Description: Charting details (for the amount that the worker recieved) for the given period.

Inputs:

  • Staff identifier (derived from authenticated session).
  • Period filter (for the given period)

Returns:

  • For each (Day/week/month: this value can depend on the period) the amount recieved.

Feature: Shifts

API - 1

API Type: GET Description: Returns shifts assigned to the staff member within a date range (confirmed, request-swap and upcoming shifts).

Inputs:

  • Staff identifier (derived from authenticated session).
  • Start date.
  • End date.

Returns:

  • List of assigned shifts, each containing: shift identifier, role name, location, date, start time, end time, hourly rate, order type (one-time/recurring/permanent), and current status.

API - 2

API Type: GET Description: Returns available open shifts that the staff member can apply for. Supports search and filtering by type.

Inputs:

  • Staff identifier (derived from authenticated session).
  • Search query (optional).
  • Shift type filter (optional).
    • Worker location's [List]
    • Radius from each location that user's like to work (ex: 20km from each preffered location)

Returns:

  • List of available shifts, each containing: shift identifier, role name, location, date, start time, end time, hourly rate, order type, instant book availability, and required worker count.
  • These shifts should automatically filtered according to the user's preferneces provided (location, experiences etc.)

API - 3

API Type: GET Description: Returns pending shift assignments awaiting the staff member's response (accept or decline).

Inputs:

  • Staff identifier (derived from authenticated session).

Returns:

  • List of pending shifts with full shift details and response deadline.

API - 4

API Type: GET Description: Returns detailed information about a specific shift, including role-specific details.

Inputs:

  • Staff identifier (derived from authenticated session).
  • Shift identifier.
  • Role identifier (optional, for role-specific view).

Returns:

  • Complete shift details: shift identifier, title, description, location with address, date, start and end times, hourly rate, break policy, order type, required count, confirmed count, and the staff member's application status for this shift.

API - 5

API Type: POST Description: Submits an application for an open shift. Supports instant booking where the application is immediately confirmed. For recurring and permanent orders, creates applications for all matching days.

Inputs:

  • Staff identifier (derived from authenticated session).
  • Shift identifier.
  • Role identifier (optional, to apply for a specific role on the shift).
  • Instant book flag (true if the shift supports immediate confirmation).

Returns:

  • Application identifier.
  • Application status (pending or confirmed if instant book).

API - 6

API Type: POST Description: Accepts a pending shift assignment offered to the staff member.

Inputs:

  • Staff identifier (derived from authenticated session).
  • Shift identifier.

Returns:

  • Updated application status (confirmed).

API - 7

API Type: POST Description: Declines a pending shift assignment offered to the staff member.

Inputs:

  • Staff identifier (derived from authenticated session).
  • Shift identifier.

Returns:

  • Updated application status (declined).

API - 8

API Type: GET Description: Returns shifts that were previously assigned to the staff member but have been cancelled.

Inputs:

  • Staff identifier (derived from authenticated session).

Returns:

  • List of cancelled shifts with shift details and cancellation reason.

API - 9

API Type: GET Description: Returns the staff member's completed shift history.

Inputs:

  • Staff identifier (derived from authenticated session).

Returns:

  • List of historical shifts with shift details, hours worked, and payment status.

API - 10

API Type: GET Description: To use the "Request swap" feature, where the shift status is switched to an intermedidate state (not canceled) but it's starts to show on other workers find shift

Inputs:

  • Staff identifier (derived from authenticated session).

Returns:

Feature: Profile Sections

API - 1

API Type: GET Description: Returns the status of each of the following section

  • worker personal info completion status.
  • worker emergency contact completion status
  • worker's experiences completion status.
  • worker's attire section completion status.
  • worker's tax form's completion status.

Inputs:

  • Workr id.

Returns:

  • Map of each section completion status.

    • The worker's personal info is complete when the worker has properly filled
      • First name
      • Last name
      • email
      • phone nubmer
      • preffered locations
    • If the worker has added at least one emergency contact.
    • The worker's experiences section is complete when the worker has properly filled
      • skills
      • industries
    • The worker's attire section is marked completed when they have uploaded all the required attire options.
    • The worker's tax form section is marked completed when they have uploaded all the required attire items.

Feature: Profile Sections — Personal Info

API - 1

API Type: GET Description: Returns the worker personal info

Inputs:

  • Workr id.

Returns:

  • Fields : first name, last name, bio, preferred locations, max distance, industries, skills.

API - 2

API Type: PUT Description: Updates the staff member's profile information. Supports partial updates where only provided fields are modified.

Inputs:

  • Staff identifier.
  • Updated fields (all optional): first name, last name, bio, preferred locations, email, phone number

Returns:

  • Updated fields.

API - 3

API Type: POST Description: Uploads a new profile photo for the staff member.

Inputs:

  • Staff identifier (derived from authenticated session).
  • Photo file.

Returns:

  • URL of the uploaded profile photo.

API - 4

API Type: PUT Description: Updates the staff member's preferred locations.

Inputs:

  • Staff identifier.

Returns:

  • Updated fields : first name, last name, bio, preferred locations, email, phone number.

Feature: Profile Sections — Experience

API - 1

API Type: GET Description: Returns the staff member's selected industries.

Inputs:

  • Staff identifier (derived from authenticated session).

Returns:

  • List of industry names.

API - 2

API Type: GET Description: Returns the staff member's selected skills.

Inputs:

  • Staff identifier (derived from authenticated session).

Returns:

  • List of skill names.

API - 3

API Type: PUT Description: Updates the staff member's industry and skill selections.

Inputs:

  • Staff identifier (derived from authenticated session).
  • List of selected industries.
  • List of selected skills.

Returns:

  • Confirmation of successful update.

Feature: Profile Sections — Emergency Contact

API - 1

API Type: GET Description: Returns all emergency contacts for the staff member.

Inputs:

  • Staff identifier (derived from authenticated session).

Returns:

  • List of emergency contacts, each containing: contact identifier, full name, phone number, and relationship type.

API - 2

API Type: PUT Description: Edit an existing emergency contact

Inputs:

  • Staff identifier (derived from authenticated session).
  • Updated fields: full name, phone number, and relationship type.

Returns:

  • Updated list of emergency contacts with assigned identifiers.

API - 2

API Type: POST Description: Create a new emergency contact

Inputs:

  • Staff identifier (derived from authenticated session).
  • Fields: full name, phone number, and relationship type.

Returns:

  • Updated list of emergency contacts with assigned identifiers.

Feature: Profile Sections — Tax Forms

API - 1

API Type: GET Description: Returns all tax forms (I-9 and W-4) for the staff member. Auto-creates blank forms if none exist.

Inputs:

  • Staff identifier (derived from authenticated session).

Returns:

  • List of tax forms, each containing: form type (I-9 or W-4), form status (not started/in progress/submitted), and all form-specific fields.

API - 2

API Type: PUT Description: Saves a partial update to the I-9 tax form (draft state, not submitted).

Inputs:

  • Staff identifier (derived from authenticated session).
  • I-9 form fields (all optional): citizenship status, document type, document number, alien/admission numbers, date of birth, Social Security Number, address fields.

Returns:

  • Updated I-9 form with current values and status.

API - 3

API Type: POST Description: Submits the completed I-9 tax form. Changes the form status to submitted and validates all required fields.

Inputs:

  • Staff identifier (derived from authenticated session).
  • Complete I-9 form data with all required fields.

Returns:

  • Submitted I-9 form with updated status.

API - 4

API Type: PUT Description: Saves a partial update to the W-4 tax form (draft state, not submitted).

Inputs:

  • Staff identifier (derived from authenticated session).
  • W-4 form fields (all optional): filing status, multiple jobs flag, dependent amounts, other income, deductions, extra withholding, exempt status.

Returns:

  • Updated W-4 form with current values and status.

API - 5

API Type: POST Description: Submits the completed W-4 tax form. Changes the form status to submitted and validates all required fields.

Inputs:

  • Staff identifier (derived from authenticated session).
  • Complete W-4 form data with all required fields.

Returns:

  • Submitted W-4 form with updated status.

Feature: Profile Sections — Certificates

API - 1

API Type: GET Description: Returns all certificates (compliance documents) for the staff member.

Inputs:

  • Staff identifier (derived from authenticated session).

Returns:

  • List of certificates, each containing: certification type, name, status (pending/verified/expired), file URL, expiry date, issuer, certificate number, and validation status.

API - 2

API Type: POST Description: Uploads a new certificate file and initiates automated verification. The backend stores the file, generates a signed URL, creates a verification request, and persists the certificate record.

Inputs:

  • Staff identifier (derived from authenticated session).
  • Certification type (e.g., food handler, CPR, guard card).
  • Certificate name.
  • Certificate file.
  • Expiry date (optional).
  • Issuer (optional).
  • Certificate number (optional).

Returns:

  • Created certificate record with: assigned identifier, file URL, initial verification status, and all submitted metadata.

API - 3

API Type: DELETE Description: Deletes a certificate record by compliance type.

Inputs:

  • Staff identifier (derived from authenticated session).
  • Certification type to delete.

Returns:

  • Confirmation of successful deletion.

Feature: Profile Sections — Documents

API - 1

API Type: GET Description: Returns all required documents and their current status for the staff member (e.g., government ID).

Inputs:

  • Staff identifier (derived from authenticated session).

Returns:

  • List of documents, each containing: document identifier, document type, status (not uploaded/pending/verified/rejected), and file URL if uploaded.

API - 2

API Type: POST Description: Uploads a document file and initiates automated verification. The backend stores the file, generates a signed URL, creates a verification request, and updates the document record.

Inputs:

  • Staff identifier (derived from authenticated session).
  • Document identifier (the specific required document slot).
  • Document file.

Returns:

  • Updated document record with: file URL, initial verification status, and document metadata.

Feature: Profile Sections — Attire

API - 1

API Type: GET Description: Returns the attire checklist options and the staff member's current photo status for each item.

Inputs:

  • Staff identifier (derived from authenticated session).

Returns:

  • List of attire items, each containing: item identifier, item name, description, whether it is mandatory, photo URL if uploaded, and verification status (pending/approved/rejected).

API - 2

API Type: POST Description: Uploads a photo for a specific attire item and initiates automated verification. The backend stores the photo, generates a signed URL, creates a verification request, polls for verification result, and updates the attire record.

Inputs:

  • Staff identifier (derived from authenticated session).
  • Attire item identifier.
  • Photo file.

Returns:

  • Updated attire item with: photo URL, verification status, and verification result details.

Feature: Profile Sections — Bank Account

API - 1

API Type: GET Description: Returns all bank accounts on file for the staff member.

Inputs:

  • Staff identifier (derived from authenticated session).

Returns:

  • List of bank accounts, each containing: account identifier, bank name, last four digits, account type (checking/savings), routing number, and whether it is the primary account.

API - 2

API Type: POST Description: Adds a new bank account for the staff member. The first account added is automatically set as the primary account.

Inputs:

  • Staff identifier (derived from authenticated session).
  • Bank name.
  • Account number.
  • Routing number.
  • Account type (checking or savings).

Returns:

  • Created bank account record with: assigned identifier, masked account number, and primary status.

Feature: Profile Sections — Time Card

API - 1

API Type: GET Description: Returns time card entries for the staff member for a specific month. Each entry represents a completed shift with calculated hours and pay.

Inputs:

  • Staff identifier (derived from authenticated session).
  • Month and year.

Returns:

  • List of time card entries, each containing: date, shift name, location, clock-in time, clock-out time, total hours worked, hourly rate, and total pay for the entry.

Feature: Profile Sections — Privacy & Security

API - 1

API Type: GET Description: Returns the current profile visibility setting for the staff member.

Inputs:

  • Staff identifier (derived from authenticated session).

Returns:

  • Profile visibility flag (true if profile is visible to potential employers).

API - 2

API Type: PUT Description: Updates the profile visibility setting for the staff member.

Inputs:

  • Staff identifier (derived from authenticated session).
  • Visibility flag (true or false).

Returns:

  • Updated visibility status.

Feature: Profile Sections — FAQs

API - 1

API Type: GET Description: Returns all FAQ categories and their questions/answers.

Inputs:

  • None (static content).

Returns:

  • List of FAQ categories, each containing: category name and list of FAQ entries (question and answer pairs).

API - 2

API Type: GET Description: Searches FAQs by keyword, matching against both questions and answers.

Inputs:

  • Search query string.

Returns:

  • Filtered list of FAQ categories containing only entries that match the search query.
Reference in New Issue View Git Blame Copy Permalink