Skip to main content
GET
/
api
/
v1
/
employees
List Employees
curl --request GET \
  --url https://api.example.com/api/v1/employees \
  --header 'Authorization: <authorization>'
{
  "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,
          "termination_reason": "<string>"
        }
      ],
      "active_employment_periods_count": 123,
      "meta": {},
      "created_at": "<string>",
      "updated_at": "<string>"
    }
  ],
  "meta": {
    "current_page": 123,
    "from": 123,
    "last_page": 123,
    "path": "<string>",
    "per_page": 123,
    "to": 123,
    "total": 123
  },
  "links": {
    "first": "<string>",
    "last": "<string>",
    "prev": "<string>",
    "next": "<string>"
  }
}

​
Overview

Returns a paginated list of all employees in the system. Supports filtering by active status, position role, and text search across code, first name, and last name. Results can be sorted by multiple fields.

​
Authentication

​
Authorization
string
required
Bearer token from OAuth2 authentication

​
Query Parameters

​
is_active
boolean
Filter by employee active status. When true, returns only active employees. When false, returns only inactive employees. Omit to return all employees regardless of status.
​
status
string
Special filter for employment status. Use "baja" to return only employees without an active employment period (terminated employees).
​
role
string
Filter by position role. Returns employees who have the specified role assigned.Allowed values: manager, cook, kitchen-assistant, delivery-driver, acting-manager, admin, super-admin
​
search
string
Search text to filter employees. Searches across:
  • Employee code (e.g., “EMP-001”)
  • First name
  • Last name
Search is case-insensitive and matches partial strings.
​
per_page
integer
default:15
Number of items per page. Must be between 1 and 100.
​
sort[]
array
Array of sort specifications in the format field:direction.Sortable fields: code, first_name, last_name, is_active, created_atDirection: asc or descExample: sort[]=code:asc&sort[]=last_name:ascDefault: Sorts by code:asc when no sort is specified

​
Response

​
status
integer
HTTP status code (200)
​
data
array
Array of employee objects
​
meta
object
Pagination metadata
​
links
object
Pagination links

​
Examples

curl -X GET "https://api.sushigo.local/api/v1/employees" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Response Example

{
  "status": 200,
  "data": [
    {
      "id": "01JKXYZ1234567890ABCDEFGH",
      "code": "EMP-001",
      "first_name": "Juan",
      "last_name": "Pérez",
      "is_active": true,
      "email": "[email protected]",
      "phone": "5512345678",
      "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,
          "termination_reason": null
        }
      ],
      "active_employment_periods_count": 1,
      "meta": null,
      "created_at": "2026-01-15T14:30:00+00:00",
      "updated_at": "2026-02-20T10:15:00+00:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "https://api.sushigo.local/api/v1/employees",
    "per_page": 15,
    "to": 1,
    "total": 1
  },
  "links": {
    "first": "https://api.sushigo.local/api/v1/employees?page=1",
    "last": "https://api.sushigo.local/api/v1/employees?page=1",
    "prev": null,
    "next": null
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us