Creating Employees

Overview

Creating an employee in SushiGo involves registering their profile information, assigning roles, and establishing their initial employment period. The system automatically creates a linked user account and sends welcome notifications.

Prerequisites

You must have manager or admin role to create employees
Branch must exist where employee will work
Employee code must be unique (system can suggest next available code)

Employee Code System

Code Structure

Employee codes follow a configurable pattern:

[PREFIX][NUMBER]

Examples:
EMP-001
EMP-002
EMP-015

Configuration

Located in config/employees.php:

'code_prefix' => env('EMPLOYEE_CODE_PREFIX', 'EMP-'),
'code_padding' => env('EMPLOYEE_CODE_PADDING', 3),

Getting Next Available Code

The system provides an endpoint to suggest the next available code:

curl -X GET "https://api.sushigo.local/api/v1/employees/next-code" \
  -H "Authorization: Bearer {token}"

Code Validation Rules

Uniqueness

Code must be unique across all employees, including soft-deleted records

Max Length

Maximum 20 characters

Case Handling

Automatically converted to uppercase

Format

No specific format required beyond uniqueness

Required Fields

Basic Information

Field	Type	Validation	Example
`code`	string	Required, unique, max 20 chars	`EMP-001`
`first_name`	string	Required, max 100 chars	`Juan`
`last_name`	string	Required, max 100 chars	`Pérez`
`roles`	array	Required, min 1 role	`["cook"]`

Contact Information

At least one contact method (email or phone) is required. Both can be provided.

Field	Type	Validation	Example	Notes
`email`	string	Email format, unique, max 255	`[email protected]`	Required if phone not provided
`phone`	string	10 digits, unique	`5512345678`	Required if email not provided

Phone Number Handling

Input format: 10-digit national number (no country code, no spaces/dashes)
System processing: Non-digit characters stripped automatically
Country code: Automatically added (+52 for Mexico) via config/employees.default_phone_country
Storage: Stored as digits only in users.phone, country in users.phone_country

Example: Phone Number Processing

User Input (all valid)

{
  "phone": "5512345678"      // ✓ Clean format
  "phone": "551-234-5678"    // ✓ System strips dashes
  "phone": "551 234 5678"    // ✓ System strips spaces
}

Stored in Database

{
  "phone": "5512345678",
  "phone_country": "+52"
}

Employment Information

Field	Type	Validation	Example	Notes
`branch_id`	integer	Required, must exist	`1`	Initial branch assignment
`start_date`	string	Required, ISO 8601 date	`2026-01-15`	Employment start date

Optional Fields

Field	Type	Validation	Example
`meta`	object	Optional JSON object	`{"notes": "..."}`

Role Assignment

Available Roles

Operational Roles
Administrative Roles

manager: Branch manager with oversight responsibilities
cook: Kitchen staff for food preparation
kitchen-assistant: Kitchen support staff
delivery-driver: Order delivery personnel
acting-manager: Temporary manager designation

Role Assignment Rules

Minimum requirement: At least one role must be assigned
Multiple roles: Employees can have multiple roles
Privilege restriction: Non-super-admins cannot assign super-admin role
Format: Roles provided as array of strings

{
  "roles": ["cook"]
}

Creating an Employee

API Request

curl -X POST "https://api.sushigo.local/api/v1/employees" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "EMP-005",
    "first_name": "Juan",
    "last_name": "Pérez",
    "email": "[email protected]",
    "phone": "5512345678",
    "roles": ["cook"],
    "branch_id": 1,
    "start_date": "2026-03-06"
  }'

Validation Errors

{
  "message": "The code has already been taken.",
  "errors": {
    "code": [
      "The code has already been taken."
    ]
  }
}

What Happens Behind the Scenes

When you create an employee, the system performs these operations in a database transaction:

Create User Account

System creates a User record with:

Full name (first_name + last_name)
Email and/or phone
Random password (32 characters)
Phone country code (+52)

Create Employee Profile

System creates an Employee record with:

Link to created user (user_id)
Employee code (uppercase)
First and last name
Active status (is_active = true)
Optional metadata

Assign Roles

System assigns roles to the User entity using Spatie Permission:

Validates roles against assignable list
Syncs roles to user account
Preserves any non-position roles

Create Employment Period

System creates initial EmploymentPeriod record with:

Link to employee
Branch assignment
Start date
Active status (is_active = true)
End date = NULL (currently employed)

Send Welcome Notification

System sends password setup link via:

Email (if provided): Welcome email with link
WhatsApp (if phone provided): Message with link
Failures logged but don’t block employee creation

The entire operation is wrapped in a database transaction. If any step fails, all changes are rolled back automatically.

Password Setup Flow

Employee Receives Notification

New employee receives welcome message via email or WhatsApp with password setup link

Employee Opens Link

Link directs to password creation form (valid for 24 hours)

Employee Sets Password

Employee creates their own secure password following system requirements

Employee Logs In

Employee can now log in to the system using their email/phone and chosen password

Common Scenarios

Scenario: Employee with Email Only

Request

{
  "code": "EMP-010",
  "first_name": "María",
  "last_name": "González",
  "email": "[email protected]",
  "roles": ["kitchen-assistant"],
  "branch_id": 2,
  "start_date": "2026-03-10"
}

Valid - Phone not required when email provided

Scenario: Employee with Phone Only

Request

{
  "code": "EMP-011",
  "first_name": "Carlos",
  "last_name": "Ramírez",
  "phone": "5587654321",
  "roles": ["delivery-driver"],
  "branch_id": 1,
  "start_date": "2026-03-11"
}

Valid - Email not required when phone provided. Welcome link sent via WhatsApp.

Scenario: Manager with Multiple Roles

Request

{
  "code": "EMP-012",
  "first_name": "Ana",
  "last_name": "López",
  "email": "[email protected]",
  "phone": "5543218765",
  "roles": ["manager", "admin"],
  "branch_id": 3,
  "start_date": "2026-03-01"
}

Valid - Multiple roles assigned. Employee has both operational (manager) and administrative (admin) permissions.

Scenario: Future Start Date

Request

{
  "code": "EMP-013",
  "first_name": "Luis",
  "last_name": "Hernández",
  "email": "[email protected]",
  "roles": ["cook"],
  "branch_id": 1,
  "start_date": "2026-04-01"
}

Valid - Employee can be registered before start date. They can log in and view their profile, but won’t appear in operational attendance views until start date.

Next Steps

After creating an employee, you’ll typically:

Assign or update roles - Modify role assignments
Create wage history - Set initial wage
Create employee schedule - Define working hours
Start tracking attendance - Daily check-in/check-out

Roles and Permissions

Learn about role management and permissions

Wage History

Set up employee wages and track changes

Employee Schedules

Define working hours and shifts

API Reference

Complete API documentation for employee creation

Get Started

Core Concepts

Inventory Management

Cash Management

Employee Management

Development

​Overview

​Prerequisites

​Employee Code System

​Code Structure

​Configuration

​Getting Next Available Code

​Code Validation Rules

Uniqueness

Max Length

Case Handling

Format

​Required Fields

​Basic Information

​Contact Information

​Phone Number Handling

​Employment Information

​Optional Fields

​Role Assignment

​Available Roles

​Role Assignment Rules

​Creating an Employee

​API Request

​Validation Errors

​What Happens Behind the Scenes

​Password Setup Flow

​Common Scenarios

​Scenario: Employee with Email Only

​Scenario: Employee with Phone Only

​Scenario: Manager with Multiple Roles

​Scenario: Future Start Date

​Next Steps

​Related Documentation

Roles and Permissions

Wage History

Employee Schedules

API Reference

Build docs developers (and LLMs) love

Overview

Prerequisites

Employee Code System

Code Structure

Configuration

Getting Next Available Code

Code Validation Rules

Required Fields

Basic Information

Contact Information

Phone Number Handling

Employment Information

Optional Fields

Role Assignment

Available Roles

Role Assignment Rules

Creating an Employee

API Request

Validation Errors

What Happens Behind the Scenes

Password Setup Flow

Common Scenarios

Scenario: Employee with Email Only

Scenario: Employee with Phone Only

Scenario: Manager with Multiple Roles

Scenario: Future Start Date

Next Steps

Related Documentation