Skip to main content
POST
/
api
/
v1
/
employees
Create Employee
curl --request POST \
  --url https://api.example.com/api/v1/employees \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "code": "<string>",
  "first_name": "<string>",
  "last_name": "<string>",
  "roles": [
    {}
  ],
  "email": "<string>",
  "phone": "<string>",
  "branch_id": 123,
  "start_date": "<string>",
  "meta": {}
}
'
{
  "422": {},
  "status": 123,
  "data": {
    "id": "<string>",
    "code": "<string>",
    "first_name": "<string>",
    "last_name": "<string>",
    "is_active": true,
    "email": "<string>",
    "phone": "<string>",
    "roles": [
      {}
    ],
    "employment_periods": [
      {
        "id": "<string>",
        "branch_id": 123,
        "branch": {},
        "start_date": "<string>",
        "end_date": "<string>",
        "is_active": true
      }
    ],
    "meta": {},
    "created_at": "<string>",
    "updated_at": "<string>"
  }
}

​
Overview

Creates a new employee record with a linked user account and an initial employment period. The system automatically sends account setup instructions via email or WhatsApp (SMS) based on the contact information provided.
Either email or phone must be provided. When both are provided, the employee will have both contact methods available.

​
Authentication

​
Authorization
string
required
Bearer token from OAuth2 authentication

​
Body Parameters

​
code
string
required
Unique employee code (max 20 characters). Will be converted to uppercase automatically.Example: "EMP-001"
Use the Suggest Employee Code endpoint to get the next available code.
​
first_name
string
required
Employee first name (max 100 characters)Example: "Juan"
​
last_name
string
required
Employee last name (max 100 characters)Example: "Pérez"
​
roles
array
required
Array of position role names to assign to the employee. Must contain at least one role.Allowed values (for non-super-admins): manager, cook, kitchen-assistant, delivery-driver, acting-manager, adminSuper-admin only: super-admin role can only be assigned by users with the super-admin roleExample: ["cook", "kitchen-assistant"]
​
email
string
Employee email address. Required if phone is not provided. Must be unique across all users.Format: Valid email address (max 255 characters)Example: "[email protected]"
A welcome email with password setup link will be sent to this address.
​
phone
string
Employee phone number. Required if email is not provided. Must be unique across all users.Format: 10-digit national phone number without country code (spaces and dashes are automatically stripped)Example: "5512345678" or "55 1234 5678"
The country code (+52 for Mexico) is added automatically. A WhatsApp message with password setup link will be sent to this number.
​
branch_id
integer
required
ID of the branch where the employee will work. Creates the initial employment period linked to this branch.Example: 1
​
start_date
string
required
Start date for the initial employment period.Format: YYYY-MM-DDExample: "2026-01-15"
​
meta
object
Optional metadata object to store additional information about the employee.Example: {"emergency_contact": "555-9999", "notes": "Bilingual"}

​
Response

​
status
integer
HTTP status code (201 for created)
​
data
object
The created employee object

​
Errors

​
422
object
Validation errorCommon validation errors:
  • Employee code already exists
  • Email already in use by another user
  • Phone already in use by another user
  • At least one of email or phone is required
  • Invalid role (attempting to assign super-admin without permission)
  • Branch ID does not exist

​
Examples

curl -X POST "https://api.sushigo.local/api/v1/employees" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "EMP-001",
    "first_name": "Juan",
    "last_name": "Pérez",
    "roles": ["cook", "kitchen-assistant"],
    "email": "[email protected]",
    "branch_id": 1,
    "start_date": "2026-01-15"
  }'

​
Response Example

{
  "status": 201,
  "data": {
    "id": "01JKXYZ1234567890ABCDEFGH",
    "code": "EMP-001",
    "first_name": "Juan",
    "last_name": "Pérez",
    "is_active": true,
    "email": "[email protected]",
    "phone": null,
    "roles": ["cook", "kitchen-assistant"],
    "employment_periods": [
      {
        "id": "01JKXYZ9876543210ZYXWVUTS",
        "branch_id": 1,
        "branch": {
          "id": 1,
          "name": "SushiGo Centro",
          "code": "CENTRO"
        },
        "start_date": "2026-01-15",
        "end_date": null,
        "is_active": true
      }
    ],
    "meta": null,
    "created_at": "2026-01-15T14:30:00+00:00",
    "updated_at": "2026-01-15T14:30:00+00:00"
  }
}

​
Suggest Employee Code

Before creating an employee, you can request the next available employee code.

​
Endpoint

GET /api/v1/employees/next-code

​
Response

{
  "code": "EMP-006",
  "prefix": "EMP-"
}

​
Example

curl -X GET "https://api.sushigo.local/api/v1/employees/next-code" \
  -H "Authorization: Bearer YOUR_TOKEN"
The code suggestion is based on the configured prefix and existing employee codes. The system finds the highest numeric suffix and suggests the next number.

Build docs developers (and LLMs) love

Get started for freeTalk to us