Staffjoy Suite

https://github.com/staffjoy/suite
Admin
Staffjoy Suite is an open-source workforce management software designed for large teams, providing...
Tokens:32,438
Snippets:112
Trust Score:7.4
License:MIT
Update:11 months ago
Show doc for...
Tokens:
Raw
### Location and Role Setup

Source: https://context7.com/staffjoy/suite/llms.txt

Set up locations and roles within an organization, defining scheduling constraints and worker assignments.

```APIDOC
## Location and Role Setup

### Description
Endpoints for creating and configuring locations and roles within an organization. This includes setting up scheduling constraints for roles and assigning workers with specific hour requirements.

### Method
- POST (Create Location)
- POST (Create Role)
- POST (Add Worker to Role)

### Endpoint
- `/organizations/{organization_id}/locations/` (POST)
- `/organizations/{organization_id}/locations/{location_id}/roles/` (POST)
- `/organizations/{organization_id}/locations/{location_id}/roles/{role_id}/users/` (POST)

### Parameters
#### Path Parameters
- **organization_id** (integer) - The ID of the organization.
- **location_id** (integer) - The ID of the location.
- **role_id** (integer) - The ID of the role.

#### Request Body (POST /organizations/{organization_id}/locations/)
- **name** (string) - Required - The name of the location.
- **timezone** (string) - Required - The timezone for the location (e.g., "America/New_York").

#### Request Body (POST /organizations/{organization_id}/locations/{location_id}/roles/)
- **name** (string) - Required - The name of the role.
- **enable_timeclock** (boolean) - Whether to enable timeclock for this role.
- **enable_time_off_requests** (boolean) - Whether to enable time off requests for this role.
- **min_hours_per_workday** (float) - Minimum hours required per workday.
- **max_hours_per_workday** (float) - Maximum hours allowed per workday.
- **min_hours_between_shifts** (float) - Minimum hours required between shifts.
- **max_consecutive_workdays** (integer) - Maximum consecutive workdays allowed.

#### Request Body (POST /organizations/{organization_id}/locations/{location_id}/roles/{role_id}/users/)
- **user_id** (integer) - Required - The ID of the user to assign to the role.
- **min_hours_per_workweek** (integer) - Minimum hours required per workweek.
- **max_hours_per_workweek** (integer) - Maximum hours allowed per workweek.
- **internal_id** (string) - An internal identifier for the user.
- **working_hours** (object) - A schedule of working hours for each day of the week.
  - **monday** (array) - Binary array representing hours (1 for working, 0 for not).
  - **tuesday** (array) - Binary array representing hours.
  - **wednesday** (array) - Binary array representing hours.
  - **thursday** (array) - Binary array representing hours.
  - **friday** (array) - Binary array representing hours.
  - **saturday** (array) - Binary array representing hours.
  - **sunday** (array) - Binary array representing hours.

### Request Example
```bash
# Create location
curl -X POST https://suite.staffjoy.com/api/v2/organizations/1/locations/ \
  -u TOKEN: \
  -H "Content-Type: application/json" \
  -d '{ 
    "name": "Downtown Store",
    "timezone": "America/New_York"
  }'

# Create role with scheduling constraints
curl -X POST https://suite.staffjoy.com/api/v2/organizations/1/locations/2/roles/ \
  -u TOKEN: \
  -H "Content-Type: application/json" \
  -d '{ 
    "name": "Barista",
    "enable_timeclock": true,
    "enable_time_off_requests": true,
    "min_hours_per_workday": 4.0,
    "max_hours_per_workday": 8.0,
    "min_hours_between_shifts": 12.0,
    "max_consecutive_workdays": 6
  }'

# Add worker to role with weekly hour constraints
curl -X POST https://suite.staffjoy.com/api/v2/organizations/1/locations/2/roles/5/users/ \
  -u TOKEN: \
  -H "Content-Type: application/json" \
  -d '{ 
    "user_id": 123,
    "min_hours_per_workweek": 20,
    "max_hours_per_workweek": 40,
    "internal_id": "EMP-001",
    "working_hours": { 
      "monday": [0,0,0,0,0,0,0,0,1,1,1,1,1,1,1,1,1,1,0,0,0,0,0,0],
      "tuesday": [0,0,0,0,0,0,0,0,1,1,1,1,1,1,1,1,1,1,0,0,0,0,0,0],
      "wednesday": [0,0,0,0,0,0,0,0,1,1,1,1,1,1,1,1,1,1,0,0,0,0,0,0],
      "thursday": [0,0,0,0,0,0,0,0,1,1,1,1,1,1,1,1,1,1,0,0,0,0,0,0],
      "friday": [0,0,0,0,0,0,0,0,1,1,1,1,1,1,1,1,1,1,0,0,0,0,0,0],
      "saturday": [0,0,0,0,0,0,0,0,0,0,1,1,1,1,1,1,1,0,0,0,0,0,0,0],
      "sunday": [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]
    }
  }'
```

### Response
#### Success Response (201 Created)
- **data** (object) - Details of the created location or role.
  - **id** (integer) - The unique identifier for the created resource.
  - **name** (string) - The name of the location or role.
  - **organization_id** (integer) - The ID of the parent organization.
  - **timezone** (string) - The timezone of the location (if creating a location).
  - **archived** (boolean) - Whether the location is archived (if creating a location).
  - **enable_timeclock** (boolean) - Timeclock enabled status (if creating a role).
  - **enable_time_off_requests** (boolean) - Time off requests enabled status (if creating a role).
  - **min_hours_per_workday** (float) - Min hours per workday (if creating a role).
  - **max_hours_per_workday** (float) - Max hours per workday (if creating a role).
  - **min_hours_between_shifts** (float) - Min hours between shifts (if creating a role).
  - **max_consecutive_workdays** (integer) - Max consecutive workdays (if creating a role).
  - **user_id** (integer) - The ID of the user assigned (if adding worker to role).
  - **min_hours_per_workweek** (integer) - Min hours per workweek (if adding worker to role).
  - **max_hours_per_workweek** (integer) - Max hours per workweek (if adding worker to role).
  - **internal_id** (string) - Internal ID of the user (if adding worker to role).
  - **working_hours** (object) - Working hours schedule (if adding worker to role).
- **resources** (array) - List of available sub-resources (e.g., "managers", "roles", "shifts", "timeclocks").

#### Response Example
```json
{
  "data": {
    "id": 2,
    "name": "Downtown Store",
    "organization_id": 1,
    "timezone": "America/New_York",
    "archived": false
  },
  "resources": ["managers", "roles", "shifts", "timeclocks"]
}
```
```

--------------------------------

### Create User Text File for Development Setup

Source: https://github.com/staffjoy/suite/blob/master/README.md

This command creates a user.txt file to auto-register a user as an administrator upon the first boot of the development server. Ensure you replace 'lenny@staffjoy.com' with your actual email address.

```shell
echo "lenny@staffjoy.com" > ./user.txt
```

--------------------------------

### Start Development Server with Make

Source: https://github.com/staffjoy/suite/blob/master/README.md

This command initiates the development server build process. The first launch may take a significant amount of time due to downloading base images. Subsequent launches will be faster as required packages and images are cached.

```shell
make dev
```

--------------------------------

### Location and Role Setup (Bash)

Source: https://context7.com/staffjoy/suite/llms.txt

Details the creation of locations and roles within an organization, including setting up scheduling constraints for roles and defining worker availability and hour limits for specific roles. This allows for granular control over staffing.

```bash
# Create location
curl -X POST https://suite.staffjoy.com/api/v2/organizations/1/locations/ \
  -u TOKEN: \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Downtown Store",
    "timezone": "America/New_York"
  }'

# Response
{
  "data": {
    "id": 2,
    "name": "Downtown Store",
    "organization_id": 1,
    "timezone": "America/New_York",
    "archived": false
  },
  "resources": ["managers", "roles", "shifts", "timeclocks"]
}

# Create role with scheduling constraints
curl -X POST https://suite.staffjoy.com/api/v2/organizations/1/locations/2/roles/ \
  -u TOKEN: \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Barista",
    "enable_timeclock": true,
    "enable_time_off_requests": true,
    "min_hours_per_workday": 4.0,
    "max_hours_per_workday": 8.0,
    "min_hours_between_shifts": 12.0,
    "max_consecutive_workdays": 6
  }'

# Add worker to role with weekly hour constraints
curl -X POST https://suite.staffjoy.com/api/v2/organizations/1/locations/2/roles/5/users/ \
  -u TOKEN: \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 123,
    "min_hours_per_workweek": 20,
    "max_hours_per_workweek": 40,
    "internal_id": "EMP-001",
    "working_hours": {
      "monday": [0,0,0,0,0,0,0,0,1,1,1,1,1,1,1,1,1,1,0,0,0,0,0,0],
      "tuesday": [0,0,0,0,0,0,0,0,1,1,1,1,1,1,1,1,1,1,0,0,0,0,0,0],
      "wednesday": [0,0,0,0,0,0,0,0,1,1,1,1,1,1,1,1,1,1,0,0,0,0,0,0],
      "thursday": [0,0,0,0,0,0,0,0,1,1,1,1,1,1,1,1,1,1,0,0,0,0,0,0],
      "friday": [0,0,0,0,0,0,0,0,1,1,1,1,1,1,1,1,1,1,0,0,0,0,0,0],
      "saturday": [0,0,0,0,0,0,0,0,0,0,1,1,1,1,1,1,1,0,0,0,0,0,0,0],
      "sunday": [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]
    }
  }'
```

--------------------------------

### Organization Management (Bash)

Source: https://context7.com/staffjoy/suite/llms.txt

Covers the creation and updating of organizations within the Staffjoy Suite. This includes setting organization-wide settings like the start of the week, plan type, and trial duration, as well as managing administrators.

```bash
# Create organization (sudo only)
curl -X POST https://suite.staffjoy.com/api/v2/organizations/ \
  -u TOKEN: \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Coffee Shops",
    "day_week_starts": "monday",
    "plan": "flex-v1",
    "trial_days": 14
  }'

# Response
{
  "data": {
    "id": 1,
    "name": "Acme Coffee Shops",
    "day_week_starts": "monday",
    "active": true,
    "plan": "flex-v1",
    "paid": true,
    "trial_days": 14,
    "shifts_assigned_days_before_start": 4,
    "enable_timeclock_default": true,
    "enable_time_off_requests_default": true,
    "created_at": "2025-10-24T10:00:00Z"
  },
  "resources": ["admins", "locations", "workers"]
}

# Update organization settings
curl -X PATCH https://suite.staffjoy.com/api/v2/organizations/1 \
  -u TOKEN: \
  -H "Content-Type: application/json" \
  -d '{
    "shifts_assigned_days_before_start": 7,
    "workers_can_claim_shifts_in_excess_of_max": true
  }'

# Add organization administrator
curl -X POST https://suite.staffjoy.com/api/v2/organizations/1/admins/ \
  -u TOKEN: \
  -H "Content-Type: application/json" \
  -d '{"user_id": 123}'
```

--------------------------------

### Access Development MySQL Database

Source: https://github.com/staffjoy/suite/blob/master/README.md

These shell commands guide you through accessing the development MySQL database. You will need to SSH into the Vagrant instance, navigate to the project directory, and then use the provided credentials to log in and select the 'dev' database.

```shell
vagrant ssh
<wait for login>
cd /vagrant
mysql -u root -p
<enter the password "bacon">
use dev;
```

--------------------------------

### Solve Linear Program with JuMP in Julia

Source: https://github.com/staffjoy/suite/blob/master/app/main/templates/bootstrap-demo.html

This snippet demonstrates how to define and solve a simple linear programming problem using the JuMP package in Julia. It includes defining variables, constraints, and the objective function, then printing the model and its solution. Requires the JuMP package to be installed.

```julia
# Solves a simple LP:
# max 5x + 3y
#  st 1x + 5y <= 3
#      0 <= x <= 2
#      0 <= y <= 20

using JuMP

m = Model()

@defVar(m, 0 <= x <= 2)
@defVar(m, 0 <= y <= 30)

@setObjective(m, Max, 5x + 3y)
@addConstraint(m, 1x + 5y <= 3.0)

print(m)

status = solve(m)

println("Objective value: ", getObjectiveValue(m))
println("x = ", getValue(x))
println("y = ", getValue(y))
```

--------------------------------

### Interact with Application Models via Shell

Source: https://github.com/staffjoy/suite/blob/master/README.md

This command launches an interactive Python shell within the application's context, allowing direct interaction with models and database operations. The example demonstrates creating a user, hashing its password, and verifying the password, followed by committing the changes.

```python
python manage.py shell
u = User()
u.password = 'cat'
u.password_hash # See hash
u.verify_password('cat')
u.verify_password('dog')
db.session.commit()
```

--------------------------------

### Get User Details with cURL

Source: https://context7.com/staffjoy/suite/llms.txt

This GET request retrieves detailed information about a specific user, including all their associated memberships. It requires the user's ID in the URL.

```bash
curl -X GET https://suite.staffjoy.com/api/v2/users/123 \
  -u TOKEN:
```

--------------------------------

### Resolve Database Heads using Python Script

Source: https://github.com/staffjoy/suite/blob/master/README.md

This example illustrates how to manage database heads using the project's Python script. It includes commands to list database heads and to merge two specified heads. This is a critical operation for resolving multi-head database states.

```python
python main.py db heads
# Using the two hashes
python main.py db merge <hash1> <hash2>
```

--------------------------------

### Create Recurring Shift Template with cURL

Source: https://context7.com/staffjoy/suite/llms.txt

This snippet demonstrates how to create a recurring shift template for a specific role within an organization and location. It requires user ID, start day, start hour, start minute, duration, and quantity. The template converts to actual shifts when the schedule state changes.

```bash
curl -X POST https://suite.staffjoy.com/api/v2/organizations/1/locations/2/roles/5/recurringshifts/ \
  -u TOKEN: \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 123,
    "start_day": "monday",
    "start_hour": 9,
    "start_minute": 0,
    "duration_minutes": 480,
    "quantity": 1
  }'
```

--------------------------------

### Worker Clock In with cURL

Source: https://context7.com/staffjoy/suite/llms.txt

This snippet demonstrates how a worker clocks in using the API. It's a POST request to the timeclocks endpoint, including the current time. The response includes the newly created timeclock entry with an ID and start time.

```bash
curl -X POST https://suite.staffjoy.com/api/v2/organizations/1/locations/2/roles/5/users/123/timeclocks/ \
  -u TOKEN: \
  -H "Content-Type: application/json" \
  -d '{"start": "2025-10-24T09:05:23-04:00"}'
```

--------------------------------

### Submit Time-Off Request with cURL

Source: https://context7.com/staffjoy/suite/llms.txt

This command demonstrates a worker submitting a time-off request. It's a POST request to the timeoffrequests endpoint, specifying the start and stop dates for the request.

```bash
curl -X POST https://suite.staffjoy.com/api/v2/organizations/1/locations/2/roles/5/users/123/timeoffrequests/ \
  -u TOKEN: \
  -H "Content-Type: application/json" \
  -d '{
    "start": "2025-10-27T00:00:00-04:00",
    "stop": "2025-10-29T00:00:00-04:00"
  }'
```

--------------------------------

### Create Schedule with Hourly Demand Forecast

Source: https://context7.com/staffjoy/suite/llms.txt

Creates a new schedule for a role within a location and organization, incorporating an hourly demand forecast. This API call requires the organization ID, location ID, role ID, and a JSON payload specifying the schedule's start and end times, shift length constraints, and hourly demand for each day of the week.

```bash
curl -X POST https://suite.staffjoy.com/api/v2/organizations/1/locations/2/roles/5/schedules/ \
  -u TOKEN: \
  -H "Content-Type: application/json" \
  -d '{
    "start": "2025-10-20T00:00:00-04:00",
    "stop": "2025-10-27T00:00:00-04:00",
    "state": "initial",
    "min_shift_length_hour": 4.0,
    "max_shift_length_hour": 8.0,
    "demand": {
      "monday": [2,2,2,2,2,3,4,5,5,4,4,3,3,3,4,5,6,6,5,4,3,2,2,2],
      "tuesday": [2,2,2,2,2,3,4,5,5,4,4,3,3,3,4,5,6,6,5,4,3,2,2,2],
      "wednesday": [2,2,2,2,2,3,4,5,5,4,4,3,3,3,4,5,6,6,5,4,3,2,2,2],
      "thursday": [2,2,2,2,2,3,4,5,5,4,4,3,3,3,4,5,6,6,5,4,3,2,2,2],
      "friday": [2,2,2,2,2,4,5,6,7,6,5,4,4,4,5,6,8,8,7,5,4,3,2,2],
      "saturday": [2,2,2,2,2,4,5,7,8,7,6,5,5,5,6,7,9,9,8,6,4,3,2,2],
      "sunday": [2,2,2,2,2,3,4,5,6,5,4,3,3,3,4,5,6,6,5,4,3,2,2,2]
    }
  }'
```

--------------------------------

### Get All Preferences for a Schedule

Source: https://context7.com/staffjoy/suite/llms.txt

Retrieves all worker availability preferences for a given schedule. This API call requires the organization ID, location ID, role ID, and schedule ID. The response includes a list of preference objects, each containing the user ID, schedule ID, and their availability preferences.

```bash
curl -X GET https://suite.staffjoy.com/api/v2/organizations/1/locations/2/roles/5/schedules/42/preferences/ \
  -u TOKEN:
```

--------------------------------

### Get Timeclocks for Date Range with cURL

Source: https://context7.com/staffjoy/suite/llms.txt

This GET request retrieves all timeclock entries for a specific user within a given date range. It requires 'start' and 'end' parameters in ISO 8601 format.

```bash
curl -X GET "https://suite.staffjoy.com/api/v2/organizations/1/locations/2/roles/5/users/123/timeclocks/?start=2025-10-01T00:00:00Z&end=2025-10-31T23:59:59Z" \
  -u TOKEN:
```

--------------------------------

### Get Time-Off Requests for Location with cURL

Source: https://context7.com/staffjoy/suite/llms.txt

This GET request retrieves all time-off requests for a specific location within a given date range. It requires 'start' and 'end' parameters in ISO 8601 format and supports filtering by available states.

```bash
curl -X GET "https://suite.staffjoy.com/api/v2/organizations/1/locations/2/timeoffrequests/?start=2025-10-01T00:00:00Z&end=2025-10-31T23:59:59Z" \
  -u TOKEN:
```

--------------------------------

### Quickly Launch Built Development Server with Vagrant

Source: https://github.com/staffjoy/suite/blob/master/README.md

These commands provide a shortcut to launch an already built development server using Vagrant. It is recommended to occasionally run `make dev` to ensure packages and stylesheets are up-to-date.

```shell
vagrant up
vagrant ssh
cd /vagrant
make dev-server
```

--------------------------------

### Get Location Attendance Report with cURL

Source: https://context7.com/staffjoy/suite/llms.txt

This GET request retrieves an attendance report for a specific location within a given date range. The response aggregates scheduled vs. actual hours worked per user and provides a summary for the location.

```bash
curl -X GET "https://suite.staffjoy.com/api/v2/organizations/1/locations/2/attendance/?start=2025-10-20T00:00:00Z&end=2025-10-27T00:00:00Z" \
  -u TOKEN:
```

--------------------------------

### Get Cached Value - Staffjoy API

Source: https://context7.com/staffjoy/suite/llms.txt

Retrieves the value associated with a specific cache key. Requires an authentication token and the cache key as part of the URL.

```bash
curl -X GET https://suite.staffjoy.com/api/v2/internal/caches/schedule:42:shifts \
  -u TOKEN:
```

--------------------------------

### Generate and Deploy Database Migrations

Source: https://github.com/staffjoy/suite/blob/master/README.md

This sequence outlines the process for managing database schema changes. First, modify the models in `app/models.py`. Then, generate a migration script using `make db-migrate`. Finally, apply the changes to the database with `make db-deploy`. Remember to commit the migration files after generation.

```shell
make db-migrate
make db-deploy
```

--------------------------------

### List Recurring Shifts for a Role with cURL

Source: https://context7.com/staffjoy/suite/llms.txt

This cURL command retrieves a list of all recurring shift templates associated with a specific role within an organization and location. It is a GET request and requires authentication.

```bash
curl -X GET https://suite.staffjoy.com/api/v2/organizations/1/locations/2/roles/5/recurringshifts/ \
  -u TOKEN:
```

--------------------------------

### Create and Grant Sudo Access in Development Environment

Source: https://github.com/staffjoy/suite/blob/master/README.md

This sequence outlines the steps to create a sudo account in the development environment. After creating a Staffjoy account, you SSH into the Vagrant instance, access the shell context, and then use Python commands to find the user by ID, set their sudo attribute to True, and commit the changes.

```shell
vagrant ssh
cd /vagrant
make shell
```

--------------------------------

### Access Shell Context for User Management

Source: https://github.com/staffjoy/suite/blob/master/README.md

This Python script demonstrates how to interact with the application's database models through the shell context. It shows how to retrieve all users, fetch a specific user by ID, grant sudo privileges, and commit the changes to the database. Be cautious when querying all users in a production environment.

```python
print User.query.get_all() # To find users - don't do this in prod where there are lots of user :-)
u = User.query.get(<id>)
u.sudo = True
db.session.commit()
```

--------------------------------

### Wipe and Recreate Development Database

Source: https://github.com/staffjoy/suite/blob/master/README.md

If database issues arise, this command sequence provides a method to reset the development database. It involves dropping the existing 'dev' database and then recreating it. After this, you will need to re-run `make db-deploy` and create a new sudo user.

```shell
drop database dev;
create database dev;
```

--------------------------------

### Query Shifts with Filters

Source: https://context7.com/staffjoy/suite/llms.txt

Retrieves shifts based on specified filters, such as a date range and a specific user ID. This requires the organization ID, location ID, role ID, and query parameters for 'start', 'end', and 'user_id'.

```bash
curl -X GET "https://suite.staffjoy.com/api/v2/organizations/1/locations/2/roles/5/shifts/?start=2025-10-20T00:00:00Z&end=2025-10-27T00:00:00Z&user_id=123" \
  -u TOKEN:
```

--------------------------------

### API Authentication with Tokens and Keys (Bash)

Source: https://context7.com/staffjoy/suite/llms.txt

Demonstrates how to obtain and use API tokens for temporary access and create persistent API keys for long-term integration with the Staffjoy Suite API. Tokens have a 12-hour expiration. API keys require a trailing colon when used in curl commands.

```bash
# Get API token (12-hour expiration)
curl -X GET https://suite.staffjoy.com/auth/api-token \
  -H "Cookie: session=<your-session-cookie>"

# Use token in API requests (note the trailing colon)
curl -u TOKEN: https://suite.staffjoy.com/api/v2/

# Create persistent API key
curl -X POST https://suite.staffjoy.com/api/v2/users/123/apikeys/ \
  -u TOKEN: \
  -H "Content-Type: application/json" \
  -d '{"name": "My Integration"}'

# Response includes key value (shown only once)
{
  "data": {
    "id": 456,
    "name": "My Integration",
    "key": "sk_live_abc123def456...",
    "created_at": "2025-10-24T10:30:00Z"
  }
}

# Use API key for requests
curl -u sk_live_abc123def456...: https://suite.staffjoy.com/api/v2/organizations/
```

--------------------------------

### Create User Account with cURL

Source: https://context7.com/staffjoy/suite/llms.txt

This snippet demonstrates how to create a new user account. It's a POST request to the /users/ endpoint and requires user details such as email, name, username, and phone number. This action is typically restricted to sudo users.

```bash
curl -X POST https://suite.staffjoy.com/api/v2/users/ \
  -u TOKEN: \
  -H "Content-Type: application/json" \
  -d '{
    "email": "worker@example.com",
    "name": "John Doe",
    "username": "johndoe",
    "phone_number": "+12125551234"
  }'
```

--------------------------------

### User Management API

Source: https://context7.com/staffjoy/suite/llms.txt

Endpoints for creating and retrieving user account information.

```APIDOC
## POST /api/v2/users/

### Description
Creates a new user account. This endpoint is typically restricted to administrative privileges (sudo only).

### Method
POST

### Endpoint
/api/v2/users/

### Parameters
#### Request Body
- **email** (string) - Required - The email address of the user.
- **name** (string) - Required - The full name of the user.
- **username** (string) - Required - The username for the user's account.
- **phone_number** (string) - Optional - The phone number of the user.

### Request Example
```json
{
  "email": "worker@example.com",
  "name": "John Doe",
  "username": "johndoe",
  "phone_number": "+12125551234"
}
```

## GET /api/v2/users/{user_id}

### Description
Retrieves details for a specific user, including all their associated memberships and roles.

### Method
GET

### Endpoint
/api/v2/users/{user_id}

### Parameters
#### Path Parameters
- **user_id** (integer) - Required - The ID of the user to retrieve.

### Response
(Response structure not detailed in the provided text, but would typically include user profile information and their organizational affiliations.)
```

--------------------------------

### API Authentication

Source: https://context7.com/staffjoy/suite/llms.txt

This section details how to authenticate with the Staffjoy Suite API using HTTP Basic Authentication with API tokens or keys. It covers obtaining temporary API tokens and creating persistent API keys for integration.

```APIDOC
## API Authentication

### Description
Authenticate with the Staffjoy Suite API using HTTP Basic Authentication with API Tokens or Keys. Temporary tokens are valid for 12 hours, while API keys can be persistent.

### Method
- GET (for API token)
- POST (for API key)

### Endpoint
- `/auth/api-token` (GET)
- `/users/{user_id}/apikeys/` (POST)

### Parameters
#### Header (for API token request)
- `Cookie`: `session=<your-session-cookie>`

#### Path Parameters (for API key request)
- **user_id** (integer) - The ID of the user for whom to create an API key.

#### Request Body (for API key request)
- **name** (string) - Required - A name for the API key (e.g., "My Integration").

### Request Example
```bash
# Get API token (12-hour expiration)
curl -X GET https://suite.staffjoy.com/auth/api-token \
  -H "Cookie: session=<your-session-cookie>"

# Use token in API requests (note the trailing colon)
curl -u TOKEN: https://suite.staffjoy.com/api/v2/

# Create persistent API key
curl -X POST https://suite.staffjoy.com/api/v2/users/123/apikeys/ \
  -u TOKEN: \
  -H "Content-Type: application/json" \
  -d '{"name": "My Integration"}'
```

### Response
#### Success Response (200 for API token, 201 for API key)
- **token** (string) - The obtained API token (for GET /auth/api-token).
- **data** (object) - Details of the created API key (for POST /users/{user_id}/apikeys/).
  - **id** (integer) - The unique identifier for the API key.
  - **name** (string) - The name of the API key.
  - **key** (string) - The generated API key value.
  - **created_at** (string) - The timestamp when the API key was created.

#### Response Example
```json
{
  "data": {
    "id": 456,
    "name": "My Integration",
    "key": "sk_live_abc123def456...",
    "created_at": "2025-10-24T10:30:00Z"
  }
}
```

### Usage with API Key
```bash
# Use API key for requests
curl -u sk_live_abc123def456...: https://suite.staffjoy.com/api/v2/organizations/
```
```

--------------------------------

### Manager Edits Timeclock Entry with cURL

Source: https://context7.com/staffjoy/suite/llms.txt

This snippet allows a manager to edit a timeclock entry, specifying both start and stop times. It's a PATCH request to the specific timeclock ID. The system may send an email notification to the worker about the edit.

```bash
curl -X PATCH https://suite.staffjoy.com/api/v2/organizations/1/locations/2/roles/5/users/123/timeclocks/456 \
  -u TOKEN: \
  -H "Content-Type: application/json" \
  -d '{
    "start": "2025-10-24T09:00:00-04:00",
    "stop": "2025-10-24T17:00:00-04:00"
  }'
```

--------------------------------

### Shift Management API

Source: https://context7.com/staffjoy/suite/llms.txt

Provides endpoints for creating, assigning, claiming, and querying individual shifts within a role.

```APIDOC
## Shift Management

### Description
This section details the API endpoints for managing individual shifts, including creation by managers, claiming by workers, unassigning shifts, and retrieving lists of eligible workers for shifts.

### Manager creates shift

#### POST /api/v2/organizations/{org_id}/locations/{location_id}/roles/{role_id}/shifts/

##### Description
Allows a manager to create a new shift. The system performs validations to ensure the shift complies with various constraints such as user availability, role hours, and weekly hour caps.

##### Method
POST

##### Endpoint
`/api/v2/organizations/{org_id}/locations/{location_id}/roles/{role_id}/shifts/`

##### Parameters
###### Path Parameters
- **org_id** (integer) - Required - The ID of the organization.
- **location_id** (integer) - Required - The ID of the location.
- **role_id** (integer) - Required - The ID of the role.

###### Request Body
- **start** (string) - Required - The start date and time of the shift in ISO 8601 format.
- **stop** (string) - Required - The end date and time of the shift in ISO 8601 format.
- **user_id** (integer) - Optional - The ID of the user to assign the shift to. If 0 or omitted, the shift is unassigned.
- **published** (boolean) - Optional - Whether the shift is published and visible to workers (defaults to false if assigned, true if unassigned).
- **description** (string) - Optional - A description for the shift.

##### Request Example
```json
{
  "start": "2025-10-24T09:00:00-04:00",
  "stop": "2025-10-24T17:00:00-04:00",
  "user_id": 123,
  "published": true,
  "description": "Opening shift"
}
```

### Worker claims unassigned shift

#### PATCH /api/v2/organizations/{org_id}/locations/{location_id}/roles/{role_id}/shifts/{shift_id}

##### Description
Allows a worker to claim an unassigned shift. The system will validate if the worker is eligible to claim the shift.

##### Method
PATCH

##### Endpoint
`/api/v2/organizations/{org_id}/locations/{location_id}/roles/{role_id}/shifts/{shift_id}`

##### Parameters
###### Path Parameters
- **org_id** (integer) - Required - The ID of the organization.
- **location_id** (integer) - Required - The ID of the location.
- **role_id** (integer) - Required - The ID of the role.
- **shift_id** (integer) - Required - The ID of the shift to claim.

###### Request Body
- **user_id** (integer) - Required - The ID of the worker claiming the shift.

##### Request Example
```json
{
  "user_id": 123
}
```

### Manager unassigns shift (makes available to claim)

#### PATCH /api/v2/organizations/{org_id}/locations/{location_id}/roles/{role_id}/shifts/{shift_id}

##### Description
Allows a manager to unassign a shift, making it available for other workers to claim. Setting `user_id` to 0 unassigns the shift.

##### Method
PATCH

##### Endpoint
`/api/v2/organizations/{org_id}/locations/{location_id}/roles/{role_id}/shifts/{shift_id}`

##### Parameters
###### Path Parameters
- **org_id** (integer) - Required - The ID of the organization.
- **location_id** (integer) - Required - The ID of the location.
- **role_id** (integer) - Required - The ID of the role.
- **shift_id** (integer) - Required - The ID of the shift to unassign.

###### Request Body
- **user_id** (integer) - Required - Set to 0 to unassign the shift.

##### Request Example
```json
{
  "user_id": 0
}
```

### Get eligible workers for a shift

#### GET /api/v2/organizations/{org_id}/locations/{location_id}/roles/{role_id}/shifts/{shift_id}/users/

##### Description
Retrieves a list of workers eligible to take a specific shift, categorized by whether they exceed weekly hour caps or not.

##### Method
GET

##### Endpoint
`/api/v2/organizations/{org_id}/locations/{location_id}/roles/{role_id}/shifts/{shift_id}/users/`

##### Parameters
###### Path Parameters
- **org_id** (integer) - Required - The ID of the organization.
- **location_id** (integer) - Required - The ID of the location.
- **role_id** (integer) - Required - The ID of the role.
- **shift_id** (integer) - Required - The ID of the shift.

##### Response
###### Success Response (200)
- **data** (object)
  - **within_caps** (array[object]) - Workers who are within weekly hour caps.
    - **id** (integer) - Worker's ID.
    - **name** (string) - Worker's name.
    - **email** (string) - Worker's email.
  - **exceeds_caps** (array[object]) - Workers who would exceed weekly hour caps.
    - **id** (integer) - Worker's ID.
    - **name** (string) - Worker's name.
    - **email** (string) - Worker's email.

###### Response Example
```json
{
  "data": {
    "within_caps": [
      {"id": 123, "name": "John Doe", "email": "john@example.com"},
      {"id": 124, "name": "Jane Smith", "email": "jane@example.com"}
    ],
    "exceeds_caps": [
      {"id": 125, "name": "Bob Wilson", "email": "bob@example.com"}
    ]
  }
}
```

### Query shifts with filters

#### GET /api/v2/organizations/{org_id}/locations/{location_id}/roles/{role_id}/shifts/

##### Description
Retrieves a list of shifts, with the ability to filter by time range and assigned user.

##### Method
GET

##### Endpoint
`/api/v2/organizations/{org_id}/locations/{location_id}/roles/{role_id}/shifts/`

##### Parameters
###### Path Parameters
- **org_id** (integer) - Required - The ID of the organization.
- **location_id** (integer) - Required - The ID of the location.
- **role_id** (integer) - Required - The ID of the role.

###### Query Parameters
- **start** (string) - Optional - The start of the time range for filtering shifts (ISO 8601 format).
- **end** (string) - Optional - The end of the time range for filtering shifts (ISO 8601 format).
- **user_id** (integer) - Optional - Filter shifts assigned to a specific user.

##### Request Example
`GET /api/v2/organizations/1/locations/2/roles/5/shifts/?start=2025-10-20T00:00:00Z&end=2025-10-27T00:00:00Z&user_id=123`
```

--------------------------------

### Access Current Environment Configuration

Source: https://github.com/staffjoy/suite/blob/master/README.md

This Python snippet retrieves and prints the current environment configuration (e.g., 'dev' or 'prod') from the Flask application. This is useful for debugging and understanding the active deployment settings.

```python
from flask import current_app
print current_app.config.get("ENV")
```

--------------------------------

### Get Eligible Workers for a Shift

Source: https://context7.com/staffjoy/suite/llms.txt

Retrieves a list of workers eligible to claim a specific shift, separated into those who are within weekly hour caps and those who exceed them. This API call requires the organization ID, location ID, role ID, and shift ID. The response includes lists of user objects with their IDs, names, and emails.

```bash
curl -X GET https://suite.staffjoy.com/api/v2/organizations/1/locations/2/roles/5/shifts/789/users/ \
  -u TOKEN:
```

--------------------------------

### Cache Management API

Source: https://context7.com/staffjoy/suite/llms.txt

Endpoints for managing the Redis cache, including listing keys and retrieving cached values.

```APIDOC
## GET /api/v2/internal/caches/

### Description
Lists all cache keys currently stored in the Redis cache. This endpoint is typically restricted to administrative or 'sudo' users.

### Method
GET

### Endpoint
`/api/v2/internal/caches/`

### Parameters
(No specific parameters are detailed for this endpoint.)

### Request Example
```bash
curl -X GET https://suite.staffjoy.com/api/v2/internal/caches/ \
  -u TOKEN:
```

### Response
#### Success Response (200)
- **data** (array) - A list of cache keys (strings).

#### Response Example
```json
{
  "data": [
    "schedule:42:shifts",
    "role:5:schedules",
    "session:123:abc123",
    "incidents:active"
  ]
}
```

## GET /api/v2/internal/caches/{cache_key}

### Description
Retrieves the value associated with a specific cache key from the Redis cache.

### Method
GET

### Endpoint
`/api/v2/internal/caches/{cache_key}`

### Parameters
#### Path Parameters
- **cache_key** (string) - Required - The key of the cached item to retrieve.

### Request Example
```bash
curl -X GET https://suite.staffjoy.com/api/v2/internal/caches/schedule:42:shifts \
  -u TOKEN:
```

### Response
#### Success Response (200)
(The response body contains the cached value associated with the provided `cache_key`. The format of the value depends on what was originally cached.)
```

--------------------------------

### Manager Creates a Shift

Source: https://context7.com/staffjoy/suite/llms.txt

Allows a manager to create a specific shift for a worker. This requires the organization ID, location ID, role ID, and a JSON payload including the shift's start and stop times, the assigned user ID, whether it's published, and an optional description. The system performs validations such as checking for overlapping shifts, adherence to role constraints, and weekly hour caps.

```bash
curl -X POST https://suite.staffjoy.com/api/v2/organizations/1/locations/2/roles/5/shifts/ \
  -u TOKEN: \
  -H "Content-Type: application/json" \
  -d '{
    "start": "2025-10-24T09:00:00-04:00",
    "stop": "2025-10-24T17:00:00-04:00",
    "user_id": 123,
    "published": true,
    "description": "Opening shift"
  }'
```

--------------------------------

### Jinja2 Macro for Quick Form Rendering

Source: https://github.com/staffjoy/suite/blob/master/app/templates/components/macros.html

This macro, better_quick_form, is a modified version of flask-bootstrap's quick_form. It renders a form, displaying field descriptions as placeholders instead of separate description elements. It utilizes the better_form_field macro for individual field rendering.

```jinja2
{# Modified version of flask-bootstrap quick_form, but shows #}
{# description as placeholders rather than a description. #}
{% macro better_quick_form(form, action="", method="post", extra_classes=None, role="form", form_type="basic", horizontal_columns=('lg', 2, 10), enctype=None, button_map={}, id="") -%}

{{ form.hidden_tag() }} {{ wtf.form_errors(form, hiddens='only') }}
{%- for field in form %} {% if not bootstrap_is_hidden_field(field) -%}
{{ better_form_field(field, form_type=form_type, horizontal_columns=horizontal_columns, default = '', placeholder=field.description) }}
{%- endif %} {%- endfor %}
{%- endmacro %}
```

--------------------------------

### List Cache Keys - Staffjoy API

Source: https://context7.com/staffjoy/suite/llms.txt

Retrieves a list of all active cache keys managed by the Staffjoy suite. This operation requires sudo privileges and an authentication token.

```bash
curl -X GET https://suite.staffjoy.com/api/v2/internal/caches/ \
  -u TOKEN:
```
Tokens:
Raw