Krow-workspace/docs/API_documentation.md

KROW Workforce Platform - API Documentation

Version: 2.0 Last Updated: 2025-11-11 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

---

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";

---

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", // Custom role field
  "created_date": "timestamp",
  "updated_date": "timestamp",
  // ... custom fields
}

---

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

JSON Schema:

{
  "type": "object",
  "properties": {
    "email": {"type": "string", "format": "email"},
    "full_name": {"type": "string"},
    "role": {"type": "string", "enum": ["admin", "user"]},
    "user_role": {"type": "string"}
  }
}

Security Rules:

• Only admin users can list, update, or delete other users
• Regular users can only view and update their own user record
• These rules are automatically enforced

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_recurring	boolean	Whether event recurs	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
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
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
notes	string	Additional notes	Optional
requested	number	Total staff requested	Optional
assigned_staff	array	Array of assigned staff	Optional
created_date	timestamp	Creation date	Auto-generated
updated_date	timestamp	Last update	Auto-updated
created_by	string	Creator email	Auto-populated

Shifts Structure:

{
  "shift_name": "string",
  "shift_contact": "string",
  "location_address": "string",
  "roles": [
    {
      "role": "string",
      "department": "string",
      "count": "number",
      "start_time": "string",
      "end_time": "string",
      "hours": "number",
      "uniform": "string",
      "break_minutes": "number",
      "cost_per_hour": "number",
      "total_value": "number",
      "vendor_name": "string",
      "vendor_id": "string"
    }
  ]
}

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
phone	string	Additional phone	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
event_location	string	Event location	Optional
address	string	Employee address	Optional
city	string	City	Optional
position	string	Primary job position/skill	Optional
position_2	string	Secondary 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"
english_required	boolean	English required	Optional
rating	number	Performance rating	Min: 0, Max: 5
shift_coverage_percentage	number	Shift coverage %	Min: 0, Max: 100
cancellation_count	number	Number of cancellations	Min: 0
no_show_count	number	Number of no-shows	Min: 0
total_shifts	number	Total shifts assigned	Min: 0
reliability_score	number	Reliability score	Min: 0, Max: 100
background_check_status	string	Background check status	Enum: "pending", "cleared", "failed", "expired", "not_required"
background_check_date	date	Last background check date	Optional
certifications	array	List of certifications	Optional
created_date	timestamp	Creation date	Auto-generated
updated_date	timestamp	Last update	Auto-updated
created_by	string	Creator email	Auto-populated

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
doing_business_as	string	DBA/Trade name	Optional
region	string	Geographic region	Enum: "National", "Bay Area", "Southern California", "Northern California", "West", "East", "Midwest", "South"
state	string	Primary state	Optional
city	string	Primary city	Optional
service_specialty	string	Service specialty	Optional
workforce_count	number	Total workforce count	Optional
platform_type	string	Technology integration level	Enum: "Full Platform", "Building platform (KROW)", "Partial Tech", "Traditional"
tax_id	string	Federal Tax ID/EIN	Optional
business_type	string	Business entity type	Enum: "Corporation", "LLC", "Partnership", "Sole Proprietorship"
primary_contact_name	string	Primary contact	Optional
primary_contact_email	string	Primary email	Required, Email format
primary_contact_phone	string	Primary phone	Optional
billing_address	string	Billing address	Optional
service_address	string	Service/office address	Optional
coverage_regions	array	Geographic coverage	Array of strings
eligible_roles	array	Roles/positions provided	Array of strings
insurance_certificate	string	URL to insurance cert	Optional
insurance_expiry	date	Insurance expiration	Optional
w9_document	string	URL to W9 form	Optional
coi_document	string	URL to COI	Optional
approval_status	string	Vendor approval status	Enum: "pending", "approved", "suspended", "terminated"
approved_date	date	Approval date	Optional
approved_by	string	Approver	Optional
is_active	boolean	Active status	Default: true
notes	string	Internal notes	Optional
created_date	timestamp	Creation date	Auto-generated
updated_date	timestamp	Last update	Auto-updated

5. VendorRate Entity

Description: Vendor pricing and rate management.

Field Name	Type	Description	Validation
id	string	Unique rate identifier	Auto-generated
vendor_id	string	Vendor ID	Optional
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
is_active	boolean	Active status	Default: true
minimum_wage_compliance	boolean	Meets minimum wage	Optional
pricing_status	string	Pricing analysis	Enum: "optimal", "underpriced", "overpriced", "competitive"
market_average	number	Market average rate	Optional
notes	string	Additional notes	Optional
available_to_clients	array	Client IDs with access	Array of strings
client_visibility	string	Visibility setting	Enum: "all", "specific", "none"
competitive_status	boolean	Competitive pricing	Default: false
csta_compliant	boolean	CA Staffing Agency compliant	Default: false
compliance_verified	boolean	Compliance verified	Default: false
created_date	timestamp	Creation date	Auto-generated
updated_date	timestamp	Last update	Auto-updated

6. 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
manager_name	string	Manager/client name	Optional
hub	string	Hub location	Optional
cost_center	string	Cost center/department	Optional
event_id	string	Related event ID	Optional
event_name	string	Event name	Optional
business_name	string	Client/Business name	Required
vendor_name	string	Vendor name	Optional
amount	number	Invoice amount	Required, Min: 0
item_count	number	Number of items	Min: 0
status	string	Invoice status	Enum: "Open", "Disputed", "Resolved", "Verified", "Overdue", "Reconciled", "Paid", "Confirmed", "Pending"
issue_date	date	Invoice issue date	Required
due_date	date	Payment due date	Required
paid_date	date	Payment received date	Optional
payment_method	string	Payment method	Enum: "Credit Card", "ACH", "Wire Transfer", "Check", "Cash"
notes	string	Additional notes	Optional
created_date	timestamp	Creation date	Auto-generated
updated_date	timestamp	Last update	Auto-updated

7. 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
company_logo	string	URL to company logo	Optional
contact_name	string	Primary contact person	Required
email	string	Business email	Email format
phone	string	Business phone	Optional
hub_building	string	Hub/building name	Optional
address	string	Street address	Optional
city	string	City	Optional
area	string	Geographic area	Enum: "Bay Area", "Southern California", "Northern California", "Central Valley", "Other"
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"
notes	string	Additional notes	Optional
created_date	timestamp	Creation date	Auto-generated
updated_date	timestamp	Last update	Auto-updated

8. Certification Entity

Description: Employee certification and compliance tracking.

Field Name	Type	Description	Validation
id	string	Unique certification ID	Auto-generated
employee_id	string	Staff member ID	Optional
employee_name	string	Staff member name	Required
vendor_id	string	Vendor ID	Optional
vendor_name	string	Vendor name	Optional
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"
issue_date	date	Issue date	Optional
expiry_date	date	Expiration date	Required
issuer	string	Issuing authority	Optional
certificate_number	string	Certificate ID	Optional
document_url	string	Uploaded certificate URL	Optional
validation_status	string	Validation status	Enum: "approved", "pending_expert_review", "rejected", "ai_verified", "ai_flagged", "manual_review_needed"
ai_validation_result	object	AI validation results	Optional
validated_by	string	Validator	Optional
validated_date	date	Validation date	Optional
is_required_for_role	boolean	Required for role	Default: false
days_until_expiry	number	Auto-calculated days	Optional
alert_sent	boolean	Expiry alert sent	Default: false
notes	string	Additional notes	Optional
created_date	timestamp	Creation date	Auto-generated
updated_date	timestamp	Last update	Auto-updated

9. Team Entity

Description: Team and organization management.

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"
company_logo	string	URL to company logo	Optional
full_name	string	Primary contact name	Optional
email	string	Contact email	Email format
phone	string	Contact phone	Optional
address	string	Company address	Optional
city	string	City	Optional
zip_code	string	ZIP code	Optional
vendor_id	string	Vendor ID if applicable	Optional
departments	array	Available departments	Array of strings
total_members	number	Total team members	Default: 0
active_members	number	Active members	Default: 0
total_hubs	number	Total hubs	Default: 0
favorite_staff_count	number	Favorite staff count	Default: 0
blocked_staff_count	number	Blocked staff count	Default: 0
created_date	timestamp	Creation date	Auto-generated
updated_date	timestamp	Last update	Auto-updated

10. Conversation Entity

Description: Messaging and communication management.

Field Name	Type	Description	Validation
id	string	Unique conversation ID	Auto-generated
participants	array	Array of participant objects	Required
conversation_type	string	Type of conversation	Required, Enum: "client-vendor", "staff-client", "staff-admin", "vendor-admin", "client-admin", "group-staff", "group-event-staff"
is_group	boolean	Is group conversation	Default: false
group_name	string	Group name	Optional
related_to	string	Related entity ID	Optional
related_type	string	Related entity type	Enum: "event", "staff", "business", "general"
subject	string	Conversation subject	Optional
last_message	string	Preview of last message	Optional
last_message_at	timestamp	Last message timestamp	Optional
unread_count	number	Unread message count	Default: 0
status	string	Conversation status	Enum: "active", "archived", "closed"
created_date	timestamp	Creation date	Auto-generated
updated_date	timestamp	Last update	Auto-updated

11. Message Entity

Description: Individual messages within conversations.

Field Name	Type	Description	Validation
id	string	Unique message identifier	Auto-generated
conversation_id	string	Conversation ID	Required
sender_id	string	Sender ID	Optional
sender_name	string	Sender name	Required
sender_role	string	Sender role	Enum: "client", "vendor", "staff", "admin"
content	string	Message content	Required
read_by	array	User IDs who read	Array of strings
attachments	array	Attached files	Array of objects
created_date	timestamp	Creation date	Auto-generated
updated_date	timestamp	Last update	Auto-updated

12. 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", "event_rescheduled", "event_canceled", "staff_assigned", "staff_removed", "invoice_paid", "invoice_created", "message_received", "order_created", "order_updated"
related_entity_type	string	Related entity type	Enum: "event", "staff", "invoice", "message", "order", "user"
related_entity_id	string	Related entity ID	Optional
action_link	string	Link to related item	Optional
action_label	string	Action button label	Optional
user_id	string	User this is for	Required
is_read	boolean	Read status	Default: false
icon_type	string	Icon to display	Enum: "calendar", "user", "invoice", "message", "alert", "check"
icon_color	string	Icon color theme	Enum: "blue", "red", "green", "yellow", "purple"
created_date	timestamp	Creation date	Auto-generated
updated_date	timestamp	Last update	Auto-updated

13. Enterprise Entity

Description: Enterprise organization management.

Field Name	Type	Description	Validation
id	string	Unique enterprise ID	Auto-generated
enterprise_number	string	Enterprise Number (EN-####)	Required, Pattern: ^EN-[0-9]{4}$
enterprise_name	string	Enterprise name	Required
enterprise_code	string	Short code identifier	Required
brand_family	array	Brands under enterprise	Array of strings
headquarters_address	string	HQ address	Optional
global_policies	object	Global policies	Optional
sector_registry	array	Sector IDs	Array of strings
rate_guardrails	object	Rate limits	Optional
primary_contact_name	string	Contact name	Optional
primary_contact_email	string	Contact email	Email format
is_active	boolean	Active status	Default: true
created_date	timestamp	Creation date	Auto-generated
updated_date	timestamp	Last update	Auto-updated

14. Sector Entity

Description: Sector/branch management.

Field Name	Type	Description	Validation
id	string	Unique sector identifier	Auto-generated
sector_number	string	Sector Number (SN-####)	Required, Pattern: ^SN-[0-9]{4}$
sector_name	string	Sector/brand name	Required
sector_code	string	Short code identifier	Required
parent_enterprise_id	string	Parent enterprise ID	Optional
parent_enterprise_name	string	Parent enterprise name	Optional
sector_type	string	Sector business type	Enum: "Food Service", "Facilities", "Healthcare", "Education", "Corporate", "Sports & Entertainment"
client_portfolio	array	Partner/client IDs	Array of strings
sector_policies	object	Sector-specific policies	Optional
approved_vendors	array	Approved vendor IDs	Array of strings
is_active	boolean	Active status	Default: true
created_date	timestamp	Creation date	Auto-generated
updated_date	timestamp	Last update	Auto-updated

15. 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 (PN-####)	Required, Pattern: ^PN-[0-9]{4}$
partner_type	string	Partner type	Enum: "Corporate", "Education", "Healthcare", "Sports & Entertainment", "Government"
sector_id	string	Sector ID	Optional
sector_name	string	Sector name	Optional
primary_contact_name	string	Primary contact	Optional
primary_contact_email	string	Primary email	Email format
primary_contact_phone	string	Primary phone	Optional
billing_address	string	Billing address	Optional
sites	array	Partner sites/locations	Array of objects
allowed_vendors	array	Allowed vendor IDs	Array of strings
rate_exceptions	array	Rate exceptions	Array of objects
cost_centers	array	Cost centers/PO numbers	Array of strings
payment_terms	string	Payment terms	Default: "Net 30"
is_active	boolean	Active status	Default: true
created_date	timestamp	Creation date	Auto-generated
updated_date	timestamp	Last update	Auto-updated

16. Order Entity

Description: Order management system.

Field Name	Type	Description	Validation
id	string	Unique order identifier	Auto-generated
order_number	string	Order Number (ORD-####)	Required, Pattern: ^ORD-[0-9]{4,6}$
partner_id	string	Partner/Client ID	Required
partner_name	string	Partner/Client name	Optional
site_id	string	Site/location ID	Optional
site_name	string	Site/location name	Optional
site_address	string	Event/site address	Optional
sector_id	string	Sector ID	Optional
enterprise_id	string	Enterprise ID	Optional
order_type	string	Type of order	Enum: "Standard", "Last Minute", "Emergency", "Recurring"
cost_center	string	Cost center	Optional
po_number	string	Purchase order number	Optional
roles_requested	array	Roles and headcount	Array of objects
tags	array	Order tags/labels	Array of strings
point_of_contact	object	On-site contact	Optional
sla_targets	object	SLA targets	Optional
order_status	string	Order status	Enum: "Draft", "Submitted", "Confirmed", "In Progress", "Completed", "Cancelled"
submitted_date	timestamp	Submission date	Optional
confirmed_date	timestamp	Confirmation date	Optional
special_instructions	string	Special instructions	Optional
total_estimated_cost	number	Estimated total cost	Optional
created_date	timestamp	Creation date	Auto-generated
updated_date	timestamp	Last update	Auto-updated

17. Shift Entity

Description: Shift scheduling and management.

Field Name	Type	Description	Validation
id	string	Unique shift identifier	Auto-generated
event_id	string	Associated event ID	Optional
shift_name	string	Name of the shift	Required
manager_id	string	Manager staff ID	Optional
manager_name	string	Manager name	Optional
location	string	Shift location	Optional
start_date	timestamp	Shift start date/time	Required
end_date	timestamp	Shift end date/time	Optional
unpaid_break	number	Unpaid break in minutes	Optional
count	number	Number of staff needed	Optional
assigned	number	Number of staff assigned	Optional
uniform_type	string	Required uniform type	Optional
price	number	Price per staff member	Optional
amount	number	Total amount for shift	Optional
assigned_staff	array	List of assigned staff	Array of objects
role	string	Role for this shift	Optional
department	string	Department	Optional
created_date	timestamp	Creation date	Auto-generated
updated_date	timestamp	Last update	Auto-updated

---

SDK Operations

Standard Entity Operations

All entities support the following base operations:

List All Records

// 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');

// List with sorting and limit
const records = await base44.entities.EntityName.list('-created_date', 20);

Filter Records

// Filter by single field
const records = await base44.entities.EntityName.filter({
  status: 'Active'
});

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

// Filter with sorting and limit
const records = await base44.entities.EntityName.filter(
  { status: 'Active' },
  '-created_date',
  10
);

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

Create Record

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

// Returns created record with id

Bulk Create Records

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

// Returns array of created records

Update Record

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

// Returns updated record

Delete Record

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

Get Entity Schema

// Get JSON schema (without built-in fields)
const schema = await base44.entities.EntityName.schema();

// Useful for dynamic form generation

Entity-Specific Examples

Event Operations

// List recent events
const events = await base44.entities.Event.list('-date', 50);

// Filter vendor's events
const myEvents = await base44.entities.Event.filter({
  vendor_id: user.id,
  status: 'Active'
}, '-date', 20);

// Create new event
const newEvent = await base44.entities.Event.create({
  event_name: 'Corporate Luncheon',
  business_name: 'Acme Corp',
  date: '2025-12-01',
  status: 'Draft',
  requested: 15
});

// Update event status
await base44.entities.Event.update(eventId, {
  status: 'Confirmed'
});

Staff Operations

// List all active staff
const staff = await base44.entities.Staff.list('-created_date');

// Filter by vendor
const vendorStaff = await base44.entities.Staff.filter({
  vendor_id: vendorId
});

// Filter by rating
const topStaff = await base44.entities.Staff.filter({
  rating: { $gte: 4.5 }
}, '-rating', 10);

// Create staff member
const newStaff = await base44.entities.Staff.create({
  employee_name: 'John Doe',
  vendor_name: 'ABC Staffing',
  position: 'Server',
  employment_type: 'Part Time'
});

// Update staff rating
await base44.entities.Staff.update(staffId, {
  rating: 4.8,
  reliability_score: 95
});

Invoice Operations

// List unpaid invoices
const unpaid = await base44.entities.Invoice.filter({
  status: 'Open'
}, '-due_date');

// Get client's invoices
const clientInvoices = await base44.entities.Invoice.filter({
  business_name: clientName
});

// Create invoice
const invoice = await base44.entities.Invoice.create({
  invoice_number: 'INV-2025-001',
  business_name: 'Client Corp',
  amount: 5000,
  status: 'Open',
  issue_date: '2025-01-01',
  due_date: '2025-01-31'
});

// Mark as paid
await base44.entities.Invoice.update(invoiceId, {
  status: 'Paid',
  paid_date: new Date().toISOString()
});

Conversation & Message Operations

// List active conversations
const conversations = await base44.entities.Conversation.filter({
  status: 'active',
  participants: { $contains: userId }
}, '-last_message_at');

// Create conversation
const conversation = await base44.entities.Conversation.create({
  participants: [
    { id: user1Id, name: user1Name, role: 'client' },
    { id: user2Id, name: user2Name, role: 'vendor' }
  ],
  conversation_type: 'client-vendor',
  subject: 'Event #123 Discussion',
  status: 'active'
});

// Send message
const message = await base44.entities.Message.create({
  conversation_id: conversationId,
  sender_id: userId,
  sender_name: userName,
  sender_role: 'client',
  content: 'Hello, can we discuss the event details?'
});

// Mark as read
await base44.entities.Message.update(messageId, {
  read_by: [...existingReadBy, userId]
});

---

Core Integrations

Integration: InvokeLLM

Description: Generate responses from an LLM with optional web context or file attachments.

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 (default: false)
response_json_schema	object	No	JSON schema for structured output
file_urls	string[]	No	Array of file URLs for additional context

Returns:

• If response_json_schema specified: object (parsed JSON)
• Otherwise: string

Examples:

// Simple text response
const response = await base44.integrations.Core.InvokeLLM({
  prompt: "Summarize the top 3 benefits of workforce automation"
});

// Structured JSON response
const data = await base44.integrations.Core.InvokeLLM({
  prompt: "Extract key information about Apple Inc.",
  add_context_from_internet: true,
  response_json_schema: {
    type: "object",
    properties: {
      stock_price: { type: "number" },
      ceo: { type: "string" },
      headquarters: { type: "string" },
      recent_news: {
        type: "array",
        items: { type: "string" }
      }
    }
  }
});

// With file context
const analysis = await base44.integrations.Core.InvokeLLM({
  prompt: "Analyze this invoice and extract line items",
  file_urls: [invoiceFileUrl],
  response_json_schema: {
    type: "object",
    properties: {
      line_items: {
        type: "array",
        items: {
          type: "object",
          properties: {
            description: { type: "string" },
            quantity: { type: "number" },
            rate: { type: "number" },
            amount: { type: "number" }
          }
        }
      },
      total: { type: "number" }
    }
  }
});

Integration: SendEmail

Description: 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 (defaults to app name)

Returns: void

Example:

await base44.integrations.Core.SendEmail({
  to: 'client@example.com',
  subject: 'Your Event Has Been Confirmed',
  body: `
    <h2>Event Confirmation</h2>
    <p>Hello ${clientName},</p>
    <p>Your event "${eventName}" has been confirmed for ${eventDate}.</p>
    <p>Staff assigned: ${staffCount}</p>
    <p>Thank you for using KROW Workforce!</p>
  `,
  from_name: 'KROW Workforce Team'
});

Integration: UploadFile

Description: Upload a file to public storage.

Parameter	Type	Required	Description
file	File	Yes	File object to upload

Returns:

{
  "file_url": "string"  // Public URL to the uploaded file
}

Example:

// From file input
const fileInput = document.querySelector('input[type="file"]');
const file = fileInput.files[0];

const { file_url } = await base44.integrations.Core.UploadFile({
  file: file
});

// Use the URL
await base44.entities.Staff.update(staffId, {
  profile_picture: file_url
});

Integration: UploadPrivateFile

Description: Upload a file to private storage (requires signed URL for access).

Parameter	Type	Required	Description
file	File	Yes	File object to upload

Returns:

{
  "file_uri": "string"  // Private file URI (not directly accessible)
}

Example:

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

// Store the URI
await base44.entities.Vendor.update(vendorId, {
  w9_document: file_uri
});

// Later, create signed URL for access
const { signed_url } = await base44.integrations.Core.CreateFileSignedUrl({
  file_uri: file_uri,
  expires_in: 3600  // 1 hour
});

Integration: CreateFileSignedUrl

Description: Create a temporary signed URL for accessing a private file.

Parameter	Type	Required	Description
file_uri	string	Yes	Private file URI
expires_in	number	No	Expiration time in seconds (default: 300)

Returns:

{
  "signed_url": "string"  // Temporary URL for file access
}

Example:

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

// Use signed URL
window.open(signed_url, '_blank');

Integration: ExtractDataFromUploadedFile

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

Parameter	Type	Required	Description
file_url	string	Yes	URL to uploaded file
json_schema	object	Yes	JSON schema defining expected data structure

Returns:

{
  "status": ""success" | "error"",
  "details": "string | null",  // Error details if status is error
  "output": "object[] | object | null"  // Extracted data if successful
}

Example:

// Upload CSV of staff members
const { file_url } = await base44.integrations.Core.UploadFile({
  file: csvFile
});

// Extract data
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" },
        position: { type: "string" },
        department: { type: "string" },
        phone: { type: "string" }
      }
    }
  }
});

if (result.status === "success") {
  // Bulk create staff from extracted data
  await base44.entities.Staff.bulkCreate(result.output);
}

Integration: GenerateImage

Description: Generate an AI image from a text prompt.

Parameter	Type	Required	Description
prompt	string	Yes	Detailed image description

Returns:

{
  "url": "string"  // URL to generated image
}

Example:

// Generate event banner
const { url } = await base44.integrations.Core.GenerateImage({
  prompt: "Professional corporate event banner with elegant food service theme, blue and white color scheme, modern minimalist design"
});

// Use the generated image
await base44.entities.Event.update(eventId, {
  banner_image: url
});

---

Data Models Reference

Complete Event Object Example

{
  "id": "evt_1234567890",
  "event_name": "Google Campus Lunch Service",
  "is_recurring": true,
  "recurrence_type": "date_range",
  "recurrence_start_date": "2025-01-01",
  "recurrence_end_date": "2025-12-31",
  "business_id": "bus_0987654321",
  "business_name": "Google",
  "vendor_id": "vnd_1122334455",
  "vendor_name": "Elite Staffing Solutions",
  "hub": "Mountain View Campus",
  "contract_type": "W2",
  "po_reference": "PO-2025-001",
  "status": "Active",
  "date": "2025-01-15",
  "shifts": [
    {
      "shift_name": "Lunch Shift",
      "shift_contact": "John Manager",
      "location_address": "1600 Amphitheatre Parkway",
      "roles": [
        {
          "role": "Server",
          "department": "Food Service",
          "count": 10,
          "start_time": "11:00",
          "end_time": "15:00",
          "hours": 4,
          "uniform": "White shirt, black pants",
          "break_minutes": 30,
          "cost_per_hour": 25,
          "total_value": 1000,
          "vendor_name": "Elite Staffing Solutions",
          "vendor_id": "vnd_1122334455"
        },
        {
          "role": "Cook",
          "department": "Kitchen",
          "count": 5,
          "start_time": "10:00",
          "end_time": "16:00",
          "hours": 6,
          "uniform": "Chef whites",
          "break_minutes": 30,
          "cost_per_hour": 30,
          "total_value": 900,
          "vendor_name": "Elite Staffing Solutions",
          "vendor_id": "vnd_1122334455"
        }
      ]
    }
  ],
  "addons": {
    "goal": {
      "enabled": true,
      "text": "Maintain 95% customer satisfaction"
    },
    "portal_access": true,
    "meal_provided": true,
    "travel_time": false,
    "tips": {
      "enabled": true,
      "amount": "pooled"
    }
  },
  "total": 1900,
  "requested": 15,
  "assigned_staff": [
    {
      "staff_id": "stf_111",
      "staff_name": "Maria Garcia",
      "role": "Server",
      "confirmed": true
    },
    {
      "staff_id": "stf_222",
      "staff_name": "John Smith",
      "role": "Cook",
      "confirmed": true
    }
  ],
  "client_name": "Sarah Johnson",
  "client_email": "sarah.johnson@google.com",
  "client_phone": "(650) 555-0123",
  "notes": "Ensure all staff arrive 15 minutes early",
  "created_date": "2025-01-01T10:00:00Z",
  "updated_date": "2025-01-10T14:30:00Z",
  "created_by": "admin@krow.com"
}

Complete Staff Object Example

{
  "id": "stf_9876543210",
  "employee_name": "Maria Garcia",
  "vendor_id": "vnd_1122334455",
  "vendor_name": "Elite Staffing Solutions",
  "manager": "Fernando Lopez",
  "contact_number": "(415) 555-0199",
  "phone": "(415) 555-0200",
  "email": "maria.garcia@email.com",
  "department": "Operations",
  "hub_location": "San Francisco Bay Area",
  "event_location": "Various",
  "address": "123 Main St, Apt 4B",
  "city": "San Francisco",
  "position": "Server",
  "position_2": "Bartender",
  "initial": "MG",
  "profile_type": "Skilled",
  "employment_type": "Part Time",
  "english": "Fluent",
  "english_required": true,
  "check_in": "2025-01-15",
  "rating": 4.8,
  "shift_coverage_percentage": 95,
  "cancellation_count": 2,
  "no_show_count": 0,
  "total_shifts": 47,
  "reliability_score": 96,
  "background_check_status": "cleared",
  "background_check_date": "2024-06-15",
  "certifications": [
    {
      "name": "Food Handler Certificate",
      "issued_date": "2024-06-01",
      "expiry_date": "2026-06-01",
      "issuer": "ServSafe"
    },
    {
      "name": "Alcohol Service Permit",
      "issued_date": "2024-07-01",
      "expiry_date": "2025-07-01",
      "issuer": "CA ABC"
    }
  ],
  "notes": "Excellent customer service skills. Prefers weekend shifts.",
  "created_date": "2024-01-10T09:00:00Z",
  "updated_date": "2025-01-15T16:45:00Z",
  "created_by": "vendor@elitestaffing.com"
}

Complete Vendor Object Example

{
  "id": "vnd_1122334455",
  "vendor_number": "VN-0042",
  "legal_name": "Elite Staffing Solutions Inc.",
  "doing_business_as": "Elite Staffing",
  "region": "Bay Area",
  "state": "California",
  "city": "San Francisco",
  "service_specialty": "Event Staffing & Hospitality Services",
  "workforce_count": 250,
  "platform_type": "Full Platform",
  "tax_id": "12-3456789",
  "business_type": "Corporation",
  "primary_contact_name": "Robert Chen",
  "primary_contact_email": "robert.chen@elitestaffing.com",
  "primary_contact_phone": "(415) 555-0100",
  "billing_address": "456 Business Plaza, Suite 200, San Francisco, CA 94102",
  "service_address": "456 Business Plaza, Suite 200, San Francisco, CA 94102",
  "coverage_regions": [
    "San Francisco",
    "Oakland",
    "San Jose",
    "Peninsula",
    "East Bay"
  ],
  "eligible_roles": [
    "Server",
    "Bartender",
    "Cook",
    "Dishwasher",
    "Event Manager",
    "Catering Staff"
  ],
  "insurance_certificate": "https://storage.example.com/certs/elite-insurance.pdf",
  "insurance_expiry": "2025-12-31",
  "w9_document": "https://storage.example.com/docs/elite-w9.pdf",
  "coi_document": "https://storage.example.com/docs/elite-coi.pdf",
  "approval_status": "approved",
  "approved_date": "2024-01-15",
  "approved_by": "admin@krow.com",
  "is_active": true,
  "notes": "Preferred vendor for tech company events. Excellent track record.",
  "created_date": "2024-01-10T10:00:00Z",
  "updated_date": "2025-01-05T11:20:00Z"
}

---

Code Examples

Example 1: Create Event with Staff Assignment

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

async function createEventAndAssignStaff() {
  // Get current user
  const user = await base44.auth.me();
  
  // Create new event
  const event = await base44.entities.Event.create({
    event_name: "Corporate Holiday Party",
    business_name: "Acme Corporation",
    date: "2025-12-20",
    hub: "Downtown Office",
    status: "Draft",
    requested: 20,
    shifts: [
      {
        shift_name: "Evening Service",
        location_address: "123 Corporate Plaza",
        roles: [
          {
            role: "Server",
            department: "Food Service",
            count: 15,
            start_time: "18:00",
            end_time: "23:00",
            hours: 5,
            cost_per_hour: 28,
            total_value: 2100
          },
          {
            role: "Bartender",
            department: "Bar Service",
            count: 5,
            start_time: "17:30",
            end_time: "23:30",
            hours: 6,
            cost_per_hour: 32,
            total_value: 960
          }
        ]
      }
    ],
    total: 3060,
    client_name: user.full_name,
    client_email: user.email
  });
  
  // Find available staff
  const availableStaff = await base44.entities.Staff.filter({
    position: "Server",
    rating: { $gte: 4.5 },
    employment_type: { $in: ["Part Time", "Full Time"] }
  }, '-rating', 15);
  
  // Assign staff to event
  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"
  });
  
  // Create activity log
  await base44.entities.ActivityLog.create({
    title: "Event Created",
    description: `New event "${event.event_name}" created and staff assigned`,
    activity_type: "event_created",
    related_entity_type: "event",
    related_entity_id: event.id,
    user_id: user.id,
    is_read: false,
    icon_type: "calendar",
    icon_color: "blue"
  });
  
  return event;
}

Example 2: Send Invoice Reminder Emails

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

async function sendInvoiceReminders() {
  // Get overdue invoices
  const today = new Date();
  const overdueInvoices = await base44.entities.Invoice.filter({
    status: { $in: ["Open", "Overdue"] },
    due_date: { $lt: today.toISOString().split('T')[0] }
  });
  
  // Send reminder for each
  for (const invoice of overdueInvoices) {
    // Update status
    await base44.entities.Invoice.update(invoice.id, {
      status: "Overdue"
    });
    
    // Get business contact
    const business = await base44.entities.Business.filter({
      business_name: invoice.business_name
    });
    
    if (business.length > 0) {
      const contact = business[0];
      
      // Send email
      await base44.integrations.Core.SendEmail({
        to: contact.email,
        subject: `Payment Reminder: Invoice ${invoice.invoice_number}`,
        body: `
          <h2>Payment Reminder</h2>
          <p>Dear ${contact.contact_name},</p>
          <p>This is a friendly reminder that invoice <strong>${invoice.invoice_number}</strong> 
          for <strong>$${invoice.amount.toLocaleString()}</strong> is now overdue.</p>
          <p><strong>Due Date:</strong> ${invoice.due_date}</p>
          <p><strong>Amount:</strong> $${invoice.amount.toLocaleString()}</p>
          <p>Please process payment at your earliest convenience.</p>
          <p>Thank you,<br>KROW Workforce Team</p>
        `,
        from_name: "KROW Accounts Receivable"
      });
      
      // Log activity
      await base44.entities.ActivityLog.create({
        title: "Invoice Reminder Sent",
        description: `Reminder sent for invoice ${invoice.invoice_number}`,
        activity_type: "invoice_created",
        related_entity_type: "invoice",
        related_entity_id: invoice.id,
        user_id: contact.id || "system",
        icon_type: "invoice",
        icon_color: "yellow"
      });
    }
  }
  
  return overdueInvoices.length;
}

Example 3: AI-Powered Staff Recommendation

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

async function getStaffRecommendations(eventId) {
  // Get event details
  const events = await base44.entities.Event.filter({ id: eventId });
  const event = events[0];
  
  // Get all available staff
  const allStaff = await base44.entities.Staff.list();
  
  // Use AI to analyze and recommend
  const recommendations = await base44.integrations.Core.InvokeLLM({
    prompt: `
      Analyze this event and recommend the best staff members.
      
      Event Details:
      - Name: ${event.event_name}
      - Date: ${event.date}
      - Location: ${event.hub}
      - Roles Needed: ${JSON.stringify(event.shifts)}
      
      Available Staff:
      ${JSON.stringify(allStaff.map(s => ({
        id: s.id,
        name: s.employee_name,
        position: s.position,
        rating: s.rating,
        reliability: s.reliability_score,
        experience: s.total_shifts
      })))}
      
      Recommend the top staff for each role based on:
      1. Position match
      2. Rating and reliability
      3. Experience level
      4. Availability patterns
      
      Provide reasoning for each recommendation.
    `,
    response_json_schema: {
      type: "object",
      properties: {
        recommendations: {
          type: "array",
          items: {
            type: "object",
            properties: {
              staff_id: { type: "string" },
              staff_name: { type: "string" },
              role: { type: "string" },
              score: { type: "number" },
              reasoning: { type: "string" }
            }
          }
        },
        overall_analysis: { type: "string" }
      }
    }
  });
  
  return recommendations;
}

Example 4: Bulk Import Staff from CSV

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

async function importStaffFromCSV(file) {
  // Upload file
  const { file_url } = await base44.integrations.Core.UploadFile({
    file: file
  });
  
  // Extract data
  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" },
          phone: { type: "string" },
          position: { type: "string" },
          department: { type: "string" },
          employment_type: { type: "string" },
          vendor_name: { type: "string" }
        },
        required: ["employee_name"]
      }
    }
  });
  
  if (result.status === "error") {
    throw new Error(result.details);
  }
  
  // Bulk create staff
  const createdStaff = await base44.entities.Staff.bulkCreate(
    result.output.map(staff => ({
      ...staff,
      rating: 0,
      reliability_score: 0,
      total_shifts: 0,
      background_check_status: "pending"
    }))
  );
  
  // Create activity logs
  await base44.entities.ActivityLog.create({
    title: "Bulk Staff Import",
    description: `${createdStaff.length} staff members imported from CSV`,
    activity_type: "staff_assigned",
    user_id: (await base44.auth.me()).id,
    icon_type: "user",
    icon_color: "green"
  });
  
  return createdStaff;
}

Example 5: Generate Performance Report

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

async function generateVendorPerformanceReport(vendorId) {
  // Get vendor details
  const vendors = await base44.entities.Vendor.filter({ id: vendorId });
  const vendor = vendors[0];
  
  // Get vendor's staff
  const staff = await base44.entities.Staff.filter({
    vendor_id: vendorId
  });
  
  // Get vendor's events
  const events = await base44.entities.Event.filter({
    vendor_id: vendorId,
    status: "Completed"
  });
  
  // Calculate metrics
  const totalStaff = staff.length;
  const avgRating = staff.reduce((sum, s) => sum + (s.rating || 0), 0) / totalStaff;
  const avgReliability = staff.reduce((sum, s) => sum + (s.reliability_score || 0), 0) / totalStaff;
  const totalEvents = events.length;
  const totalRevenue = events.reduce((sum, e) => sum + (e.total || 0), 0);
  
  // Use AI to generate insights
  const report = await base44.integrations.Core.InvokeLLM({
    prompt: `
      Generate a comprehensive performance report for this vendor:
      
      Vendor: ${vendor.legal_name}
      Workforce Size: ${totalStaff}
      Average Staff Rating: ${avgRating.toFixed(2)}/5.0
      Average Reliability: ${avgReliability.toFixed(1)}%
      Events Completed: ${totalEvents}
      Total Revenue: $${totalRevenue.toLocaleString()}
      
      Staff Performance Distribution:
      ${JSON.stringify(staff.map(s => ({
        name: s.employee_name,
        rating: s.rating,
        reliability: s.reliability_score,
        shifts: s.total_shifts
      })))}
      
      Provide:
      1. Overall performance summary
      2. Key strengths
      3. Areas for improvement
      4. Specific recommendations
      5. Comparison to industry benchmarks
    `,
    response_json_schema: {
      type: "object",
      properties: {
        summary: { type: "string" },
        grade: { type: "string" },
        strengths: {
          type: "array",
          items: { type: "string" }
        },
        improvements: {
          type: "array",
          items: { type: "string" }
        },
        recommendations: {
          type: "array",
          items: { type: "string" }
        },
        benchmark_comparison: { type: "string" }
      }
    }
  });
  
  return {
    vendor,
    metrics: {
      totalStaff,
      avgRating,
      avgReliability,
      totalEvents,
      totalRevenue
    },
    analysis: report
  };
}

---

Best Practices

1. Error Handling

try {
  const event = await base44.entities.Event.create(eventData);
  // Success handling
} catch (error) {
  console.error("Failed to create event:", error);
  // Show user-friendly error message
  toast({
    title: "❌ Error",
    description: "Failed to create event. Please try again.",
    variant: "destructive"
  });
}

2. Query Optimization

// ❌ Bad: Fetch all then filter in memory
const allEvents = await base44.entities.Event.list();
const vendorEvents = allEvents.filter(e => e.vendor_id === vendorId);

// ✅ Good: Filter at database level
const vendorEvents = await base44.entities.Event.filter({
  vendor_id: vendorId
});

3. Pagination

// Fetch in batches
const pageSize = 50;
let page = 0;
let allRecords = [];

while (true) {
  const batch = await base44.entities.Event.list(
    '-created_date',
    pageSize,
    page * pageSize
  );
  
  if (batch.length === 0) break;
  
  allRecords = [...allRecords, ...batch];
  page++;
}

4. Caching with React Query

import { useQuery } from "@tanstack/react-query";

function useEvents() {
  return useQuery({
    queryKey: ['events'],
    queryFn: () => base44.entities.Event.list('-date'),
    initialData: [],
    staleTime: 5 * 60 * 1000,  // 5 minutes
    cacheTime: 10 * 60 * 1000  // 10 minutes
  });
}

5. Batch Operations

// ❌ Bad: Multiple sequential creates
for (const staff of staffList) {
  await base44.entities.Staff.create(staff);
}

// ✅ Good: Single bulk create
await base44.entities.Staff.bulkCreate(staffList);

---

Security Considerations

1. User Entity Access Control

• Only admin users can access other users' data
• Regular users can only view/update their own records
• Built-in security rules are automatically enforced

2. Private Files

• Use UploadPrivateFile for sensitive documents
• Always use signed URLs with appropriate expiration
• Never expose private file URIs directly

3. Email Validation

• Always validate email formats before sending
• Use proper HTML escaping in email bodies
• Consider rate limiting for bulk emails

4. Data Validation

• Validate all input data before entity operations
• Use enum constraints where applicable
• Implement client-side validation before API calls

---

Rate Limits & Quotas

Standard Limits

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

Best Practices for Limits

• Implement exponential backoff for retries
• Cache frequently accessed data
• Use bulk operations when possible
• Monitor usage via activity logs

---

Changelog

Version 2.0 (2025-01-11)

• Complete entity schema documentation
• Added 17 entity schemas with full field specifications
• Comprehensive SDK operation examples
• Core integration specifications
• Advanced code examples
• Best practices and security guidelines

Version 1.0 (2024-12-01)

• Initial API documentation
• Basic entity schemas
• Core integration endpoints

---

Support & Resources

• Documentation
  • Platform Docs: https://docs.base44.com
  • API Reference: https://api.base44.com/docs
  • Community Forum: https://community.base44.com
• Contact
  • Technical Support: support@krow.com
  • Sales Inquiries: sales@krow.com
  • General Questions: info@krow.com

© 2025 KROW Workforce. All rights reserved.