Krow-workspace/docs/07-reference-base44-api-export-v3.md

KROW Workforce Platform - API Documentation

Version: 3.0 (Auto-Updated)
Last Updated: 2025-11-20
Project: KROW Workforce Control Tower

---

Table of Contents

1. Overview
2. Authentication
3. Entity Schemas
4. SDK Operations
5. Core Integrations
6. Data Models Reference
7. Code Examples
8. Best Practices
9. Security Considerations
10. Rate Limits & Quotas
11. Changelog
12. Support & Resources

---

1. Overview

KROW Workforce is a comprehensive workforce management platform built on Base44. This documentation provides complete API specifications for all entities, SDK methods, and integration endpoints.

Base44 Client Import

import { base44 } from "@/api/base44Client";

---

2. Authentication

User Authentication Methods

// Get current authenticated user
const user = await base44.auth.me();

// Update current user
await base44.auth.updateMe({
  full_name: "John Doe",
  custom_field: "value"
});

// Logout
base44.auth.logout(redirectUrl?: string);

// Redirect to login
base44.auth.redirectToLogin(nextUrl?: string);

// Check authentication status
const isAuthenticated = await base44.auth.isAuthenticated();

User Object Structure

{
  "id": "string",
  "email": "string",
  "full_name": "string",
  "role": "admin | user",
  "user_role": "string",
  "created_date": "timestamp",
  "updated_date": "timestamp"
}

---

3. Entity Schemas

1. User Entity (Built-in)

Description: Core user entity with authentication and role management.

Field Name	Type	Description	Validation
id	string	Unique user identifier	Auto-generated, unique
email	string	User email address	Required, unique, email format
full_name	string	User's full name	Required
role	string	Base role	Enum: "admin", "user"
user_role	string	Custom application role	Optional, custom values
created_date	timestamp	Account creation date	Auto-generated
updated_date	timestamp	Last update timestamp	Auto-updated

Security Rules:

• Only admin users can list, update, or delete other users.
• Regular users can only view and update their own user record.

2. Event Entity

Description: Core event/order management entity for workforce scheduling.

Field Name	Type	Description	Validation
id	string	Unique event identifier	Auto-generated
event_name	string	Name of the event	Required
is_rapid	boolean	RAPID/urgent order flag	Default: false
is_recurring	boolean	Whether event recurs	Default: false
is_multi_day	boolean	Multi-day event flag	Default: false
recurrence_type	string	Type of recurrence	Enum: "single", "date_range", "scatter"
recurrence_start_date	date	Start date for recurring events	Optional
recurrence_end_date	date	End date for recurring events	Optional
scatter_dates	array	Specific dates for scatter recurring	Array of date strings
multi_day_start_date	date	Multi-day start date	Optional
multi_day_end_date	date	Multi-day end date	Optional
buffer_time_before	number	Buffer time before (minutes)	Default: 0
buffer_time_after	number	Buffer time after (minutes)	Default: 0
conflict_detection_enabled	boolean	Enable conflict detection	Default: true
detected_conflicts	array	Array of detected conflicts	Array of conflict objects
business_id	string	Associated business ID	Optional
business_name	string	Business name	Optional
vendor_id	string	Vendor ID if created by vendor	Optional
vendor_name	string	Vendor name	Optional
hub	string	Hub location	Optional
event_location	string	Event location address	Optional
contract_type	string	Contract type	Enum: "W2", "1099", "Temp", "Contract"
po_reference	string	Purchase order reference	Optional
status	string	Event status	Enum: "Draft", "Active", "Pending", "Assigned", "Confirmed", "Completed", "Canceled"
date	date	Event date	Optional
shifts	array	Array of shift objects	Optional
addons	object	Additional services/features	Optional
total	number	Total cost	Optional
client_name	string	Client contact name	Optional
client_email	string	Client email	Optional
client_phone	string	Client phone	Optional
invoice_id	string	Associated invoice ID	Optional
notes	string	Additional notes	Optional
requested	number	Total staff requested	Default: 0
assigned_staff	array	Array of assigned staff	Optional

Detected Conflicts Structure:

{
  "conflict_type": "staff_overlap" | "venue_overlap" | "time_buffer",
  "severity": "low" | "medium" | "high" | "critical",
  "description": "string",
  "conflicting_event_id": "string",
  "staff_id": "string",
  "detected_at": "timestamp"
}

3. Staff Entity

Description: Employee/workforce member management.

Field Name	Type	Description	Validation
id	string	Unique staff identifier	Auto-generated
employee_name	string	Full name	Required
vendor_id	string	Associated vendor ID	Optional
vendor_name	string	Vendor company name	Optional
manager	string	Manager's name	Optional
contact_number	string	Primary contact number	Optional
email	string	Email address	Email format
department	string	Department	Enum: "Operations", "Sales", "HR", "Finance", "IT", "Marketing", "Customer Service", "Logistics"
hub_location	string	Hub/office location	Optional
track	string	Track information	Optional
position	string	Primary job position/skill	Optional
profile_type	string	Skill profile level	Enum: "Skilled", "Beginner", "Cross-Trained"
employment_type	string	Employment type	Enum: "Full Time", "Part Time", "On call", "Weekends", "Specific Days", "Seasonal", "Medical Leave"
english	string	English proficiency	Enum: "Fluent", "Intermediate", "Basic", "None"
rating	number	Staff performance rating (0-5 stars)	Min: 0, Max: 5
reliability_score	number	Overall reliability score (0-100)	Min: 0, Max: 100
background_check_status	string	Background check status	Enum: "pending", "cleared", "failed", "expired", "not_required"

4. Vendor Entity

Description: Vendor/supplier management and onboarding.

Field Name	Type	Description	Validation
id	string	Unique vendor identifier	Auto-generated
vendor_number	string	Vendor Number (VN-####)	Required, Pattern: ^VN-[0-9]{4}$
legal_name	string	Legal business name	Required
region	string	Geographic region	Enum: "National", "Bay Area", "Southern California", "Northern California", "West", "East", "Midwest", "South"
platform_type	string	Technology integration level	Enum: "Full Platform", "Building platform (KROW)", "Partial Tech", "Traditional"
primary_contact_email	string	Primary email	Required, Email format
approval_status	string	Vendor approval status	Enum: "pending", "approved", "suspended", "terminated"
is_active	boolean	Is vendor currently active	Default: true

5. VendorRate Entity

Description: Vendor pricing and rate management.

Field Name	Type	Description	Validation
id	string	Unique rate identifier	Auto-generated
vendor_name	string	Vendor name	Required
category	string	Service category	Enum: "Kitchen and Culinary", "Concessions", "Facilities", "Bartending", "Security", "Event Staff", "Management", "Technical", "Other"
role_name	string	Role/position name	Required
employee_wage	number	Employee base wage/hour	Required, Min: 0
markup_percentage	number	Markup percentage	Min: 0, Max: 100
vendor_fee_percentage	number	Vendor fee percentage	Min: 0, Max: 100
client_rate	number	Final rate to client	Required, Min: 0

6. VendorDefaultSettings Entity

Description: Default markup and fee settings for vendors.

Field Name	Type	Description	Validation
id	string	Unique settings identifier	Auto-generated
vendor_name	string	Name of the vendor	Required
default_markup_percentage	number	Default markup percentage	Required, Min: 0, Max: 100
default_vendor_fee_percentage	number	Default vendor fee percentage	Required, Min: 0, Max: 100

7. Invoice Entity

Description: Invoice and billing management.

Field Name	Type	Description	Validation
id	string	Unique invoice identifier	Auto-generated
invoice_number	string	Unique invoice number	Required
amount	number	Grand total invoice amount	Required, Min: 0
status	string	Current invoice status	Enum: "Draft", "Pending Review", "Approved", "Disputed", "Under Review", "Resolved", "Overdue", "Paid", "Reconciled", "Cancelled"
issue_date	date	Invoice issue date	Required
due_date	date	Payment due date	Required
disputed_items	array	List of disputed staff entry indices	Optional
is_auto_generated	boolean	Whether invoice was auto-generated	Default: false

8. Business Entity

Description: Client business/company management.

Field Name	Type	Description	Validation
id	string	Unique business identifier	Auto-generated
business_name	string	Business/client company name	Required
contact_name	string	Primary contact person	Required
email	string	Business email	Email format
sector	string	Sector/industry	Enum: "Bon Appétit", "Eurest", "Aramark", "Epicurean Group", "Chartwells", "Other"
rate_group	string	Pricing tier	Required, Enum: "Standard", "Premium", "Enterprise", "Custom"
status	string	Business status	Enum: "Active", "Inactive", "Pending"

9. Certification Entity

Description: Employee certification and compliance tracking.

Field Name	Type	Description	Validation
id	string	Unique certification ID	Auto-generated
employee_name	string	Staff member name	Required
certification_name	string	Certification name	Required
certification_type	string	Type of certification	Enum: "Legal", "Operational", "Safety", "Training", "License", "Other"
status	string	Current status	Enum: "current", "expiring_soon", "expired", "pending_validation"
expiry_date	date	Expiration date	Required
validation_status	string	Validation status	Enum: "approved", "pending_expert_review", "rejected", "ai_verified", "ai_flagged", "manual_review_needed"

10. Team Entity

Description: Team and organization management with role-based isolation.

Field Name	Type	Description	Validation
id	string	Unique team identifier	Auto-generated
team_name	string	Name of the team	Required
owner_id	string	Team owner user ID	Required
owner_name	string	Team owner name	Required
owner_role	string	Role of team owner	Required, Enum: "admin", "procurement", "operator", "sector", "client", "vendor", "workforce"
favorite_staff	array	Array of favorite staff	Array of objects
blocked_staff	array	Array of blocked staff	Array of objects

11. TeamMember Entity

Description: Team member management within teams.

Field Name	Type	Description	Validation
id	string	Unique member identifier	Auto-generated
team_id	string	ID of the team this member belongs to	Required
member_name	string	Name of the team member	Required
email	string	Member email	Required, Email format
role	string	Role in the team	Enum: "admin", "manager", "member", "viewer"
is_active	boolean	Whether the member is active	Default: true

12. TeamHub Entity

Description: Team hub/location management.

Field Name	Type	Description	Validation
id	string	Unique hub identifier	Auto-generated
team_id	string	ID of the team	Required
hub_name	string	Name of the hub/location	Required
departments	array	Departments within this hub	Array of objects with department_name, cost_center

13. TeamMemberInvite Entity

Description: Team member invitation management.

Field Name	Type	Description	Validation
id	string	Unique invite identifier	Auto-generated
team_id	string	Team ID	Required
invite_code	string	Unique invite code	Required
email	string	Invitee email	Required, Email format
invite_status	string	Invite status	Enum: "pending", "accepted", "expired", "cancelled"

14. Conversation Entity

Description: Messaging and communication management.

Field Name	Type	Description	Validation
id	string	Unique conversation ID	Auto-generated
participants	array	Array of participant IDs/emails	Required
conversation_type	string	Type of conversation	Required, Enum: "client-vendor", "staff-client", "staff-admin", "vendor-admin", "client-admin", "group-staff", "group-event-staff"
related_to	string	ID of related entity	Optional
status	string	Conversation status	Enum: "active", "archived", "closed"

15. Message Entity

Description: Individual messages within conversations.

Field Name	Type	Description	Validation
id	string	Unique message identifier	Auto-generated
conversation_id	string	ID of the conversation	Required
sender_name	string	Name of the sender	Required
content	string	Message content	Required
read_by	array	Array of user IDs who have read the message	Array of strings

16. ActivityLog Entity

Description: Activity and notification tracking.

Field Name	Type	Description	Validation
id	string	Unique activity identifier	Auto-generated
title	string	Notification title	Required
description	string	Detailed description	Required
activity_type	string	Type of activity	Required, Enum: "event_created", "event_updated", "staff_assigned", "invoice_paid", etc.
user_id	string	ID of the user this notification is for	Required
is_read	boolean	Whether the notification has been read	Default: false

17. Enterprise Entity

Description: Enterprise organization management.

Field Name	Type	Description	Validation
id	string	Unique enterprise ID	Auto-generated
enterprise_number	string	Enterprise Number format EN-####	Required, Pattern: ^EN-[0-9]{4}$
enterprise_name	string	Enterprise name (e.g., Compass)	Required
enterprise_code	string	Short code identifier	Required

18. Sector Entity

Description: Sector/branch management.

Field Name	Type	Description	Validation
id	string	Unique sector identifier	Auto-generated
sector_number	string	Sector Number format SN-####	Required, Pattern: ^SN-[0-9]{4}$
sector_name	string	Sector/brand name (e.g., Bon Appétit)	Required
sector_type	string	Sector business type	Enum: "Food Service", "Facilities", "Healthcare", "Education", "Corporate", "Sports & Entertainment"

19. Partner Entity

Description: Partner/client organization management.

Field Name	Type	Description	Validation
id	string	Unique partner identifier	Auto-generated
partner_name	string	Partner/client name	Required
partner_number	string	Partner Number format PN-####	Required, Pattern: ^PN-[0-9]{4}$
partner_type	string	Partner type	Enum: "Corporate", "Education", "Healthcare", "Sports & Entertainment", "Government"

20. Order Entity

Description: Order management system.

Field Name	Type	Description	Validation
id	string	Unique order identifier	Auto-generated
order_number	string	Order Number format ORD-####	Required, Pattern: ^ORD-[0-9]{4,6}$
partner_id	string	Partner/Client ID	Required
order_type	string	Type of order	Enum: "Standard", "Last Minute", "Emergency", "Recurring"
order_status	string	Order status	Enum: "Draft", "Submitted", "Confirmed", "In Progress", "Completed", "Cancelled"

21. Shift Entity

Description: Shift scheduling and management.

Field Name	Type	Description	Validation
id	string	Unique shift identifier	Auto-generated
shift_name	string	Name of the shift	Required
start_date	timestamp	Shift start date/time	Required
end_date	timestamp	Shift end date/time	Optional
assigned_staff	array	List of assigned staff	Array of objects

22. Assignment Entity

Description: Worker assignment and tracking.

Field Name	Type	Description	Validation
id	string	Unique assignment identifier	Auto-generated
assignment_number	string	Assignment Number format ASN-####	Pattern: ^ASN-[0-9]{4,6}$
order_id	string	Associated order ID	Required
workforce_id	string	Assigned worker ID	Required
vendor_id	string	Vendor providing the worker	Required
role	string	Role assigned	Required
assignment_status	string	Assignment status	Enum: "Pending", "Confirmed", "Checked In", "In Progress", "Completed", "Cancelled", "No Show"
scheduled_start	timestamp	Scheduled start time	Required

23. Workforce Entity

Description: Worker/contractor management.

Field Name	Type	Description	Validation
id	string	Unique workforce identifier	Auto-generated
workforce_number	string	Worker Number format WF-####	Required, Pattern: ^WF-[0-9]{4,6}$
vendor_id	string	Vendor who manages this worker	Required
first_name	string	Worker first name	Required
last_name	string	Worker last name	Required
employment_type	string	Employment classification	Enum: "W2", "1099", "Temporary", "Contract"

---

4. SDK Operations

All entities support the following base operations. Replace EntityName with the specific entity (e.g., Event, Staff, Invoice).

List & Filter

// List all records (default limit: 50)
const records = await base44.entities.EntityName.list();

// List with sorting (descending by created_date)
const records = await base44.entities.EntityName.list('-created_date');

// Filter with multiple conditions
const records = await base44.entities.EntityName.filter({
  status: 'Active',
  created_by: user.email
});

// Filter with operators ($gte, $lte, $in, $contains)
const records = await base44.entities.EntityName.filter({
  rating: { $gte: 4.5 },
  total: { $lte: 1000 }
});

CRUD Operations

// Create
const newRecord = await base44.entities.EntityName.create({
  field1: 'value1',
  field2: 'value2'
});

// Bulk Create
const newRecords = await base44.entities.EntityName.bulkCreate([
  { field1: 'value1' },
  { field1: 'value2' }
]);

// Update
const updatedRecord = await base44.entities.EntityName.update(recordId, {
  field1: 'new value'
});

// Delete
await base44.entities.EntityName.delete(recordId);

// Get Schema
const schema = await base44.entities.EntityName.schema();

---

5. Core Integrations

InvokeLLM

Generates a response from an LLM with a prompt.

Parameter	Type	Required	Description
prompt	string	Yes	The prompt to send to the LLM
add_context_from_internet	boolean	No	Fetch context from Google Search/Maps/News
response_json_schema	object	No	JSON schema for structured output
file_urls	string[]	No	Array of file URLs for context

const data = await base44.integrations.Core.InvokeLLM({
  prompt: "Give me data on Apple",
  add_context_from_internet: true,
  response_json_schema: {
    type: "object",
    properties: {
      stock_price: { type: "number" },
      ceo: { type: "string" }
    }
  }
});

SendEmail

Send an email to a user.

Parameter	Type	Required	Description
to	string	Yes	Recipient email address
subject	string	Yes	Email subject line
body	string	Yes	Email body (supports HTML)
from_name	string	No	Sender name

File Operations

• UploadFile: Upload a file to public storage.
• UploadPrivateFile: Upload a file to private storage (requires signed URL).
• CreateFileSignedUrl: Create a temporary signed URL for accessing a private file.

// Upload private document
const { file_uri } = await base44.integrations.Core.UploadPrivateFile({
  file: sensitiveDocument
});

// Create signed URL
const { signed_url } = await base44.integrations.Core.CreateFileSignedUrl({
  file_uri: file_uri,
  expires_in: 3600
});

ExtractDataFromUploadedFile

Extract structured data from uploaded files (CSV, PDF, images).

const result = await base44.integrations.Core.ExtractDataFromUploadedFile({
  file_url: file_url,
  json_schema: {
    type: "array",
    items: {
      type: "object",
      properties: {
        employee_name: { type: "string" },
        email: { type: "string" }
      }
    }
  }
});

---

6. Data Models Reference

Complete Event Object Example

{
  "id": "evt_1234567890",
  "event_name": "Google Campus Lunch Service",
  "is_recurring": true,
  "status": "Active",
  "date": "2025-01-15",
  "shifts": [
    {
      "shift_name": "Lunch Shift",
      "roles": [
        {
          "role": "Server",
          "count": 10,
          "hours": 4,
          "cost_per_hour": 25,
          "total_value": 1000
        }
      ]
    }
  ],
  "assigned_staff": [
    {
      "staff_id": "stf_111",
      "staff_name": "Maria Garcia",
      "confirmed": true
    }
  ]
}

---

7. Code Examples

Example: Create Event with Staff Assignment

import { base44 } from "@/api/base44Client";

async function createEventAndAssignStaff() {
  const user = await base44.auth.me();
  
  // 1. Create Event
  const event = await base44.entities.Event.create({
    event_name: "Corporate Holiday Party",
    date: "2025-12-20",
    status: "Draft",
    requested: 20,
    shifts: [{
        shift_name: "Evening Service",
        roles: [{ role: "Server", count: 15, cost_per_hour: 28 }]
    }],
    client_email: user.email
  });
  
  // 2. Find Staff
  const availableStaff = await base44.entities.Staff.filter({
    position: "Server",
    rating: { $gte: 4.5 }
  }, '-rating', 15);
  
  // 3. Assign Staff
  const assignedStaff = availableStaff.map(staff => ({
    staff_id: staff.id,
    staff_name: staff.employee_name,
    role: "Server",
    confirmed: false
  }));
  
  await base44.entities.Event.update(event.id, {
    assigned_staff: assignedStaff,
    status: "Pending"
  });
  
  return event;
}

Example: AI-Powered Staff Recommendation

import { base44 } from "@/api/base44Client";

async function getStaffRecommendations(eventId) {
  const events = await base44.entities.Event.filter({ id: eventId });
  const event = events[0];
  const allStaff = await base44.entities.Staff.list();
  
  const recommendations = await base44.integrations.Core.InvokeLLM({
    prompt: `Analyze this event (${event.event_name}) and recommend staff based on rating and reliability.`,
    response_json_schema: {
      type: "object",
      properties: {
        recommendations: {
          type: "array",
          items: {
            type: "object",
            properties: {
              staff_id: { type: "string" },
              score: { type: "number" },
              reasoning: { type: "string" }
            }
          }
        }
      }
    }
  });
  
  return recommendations;
}

---

8. Best Practices

1. Error Handling: Always wrap calls in try/catch blocks and provide user-friendly error messages.
2. Query Optimization: Filter data at the database level (using .filter()) rather than fetching all records and filtering in memory.
3. Pagination: Use the limit and offset parameters in .list() for large datasets to improve performance.
4. Caching: Use libraries like React Query to cache SDK responses and reduce API calls.
5. Batch Operations: Prefer bulkCreate over looping through single create calls.
6. Team Isolation: Rely on the built-in owner_id filtering. Do not attempt to bypass cross-layer visibility rules (e.g., Vendors should not see Procurement teams).

---

9. Security Considerations

• User Entity Access Control: Built-in rules enforce that only admins can modify other users. Regular users are restricted to their own records.
• Team Isolation: Complete data isolation across organizational layers (Vendor, Procurement, Operator, Client) is enforced via owner_id.
• Private Files: Always use UploadPrivateFile for sensitive documents (W9, Insurance, etc.) and generate temporary signed URLs for access.
• Input Validation: While the API performs validation, always validate email formats and required fields on the client side before making requests.

---

10. Rate Limits & Quotas

Operation	Limit
Entity Operations	1000 requests/minute
LLM Invocations	100 requests/minute
File Uploads	100 MB per file
Email Sending	1000 emails/day

Tip: Implement exponential backoff for retries if you hit these limits.

---

11. Changelog

Version 3.0 (2025-11-20)

• Added Team, TeamMember, TeamHub, TeamMemberInvite entities.
• Added Assignment and Workforce entities.
• Enhanced Invoice entity with dispute tracking.
• Updated Event entity (Conflict detection, Multi-day).

Version 2.0 (2025-01-11)

• Complete entity schema documentation.
• Core integration specifications.

---

12. Support & Resources

• Platform Docs: https://docs.base44.com
• API Reference: https://api.base44.com/docs
• Technical Support: support@krow.com

© 2025 KROW Workforce. All rights reserved.