Person Management

Overview

The Person API provides comprehensive user management capabilities for your Zou/Kitsu instance. This includes creating and managing user accounts, assigning roles and permissions, tracking time and presence, and managing user profiles.

User Roles

Zou supports the following user roles with different permission levels:

Admin (Studio Manager)

Full access to all resources and settings. Can manage users, projects, and system configuration.

Manager (Production Manager)

Can manage projects and view production data. Has access to time tracking and quota reports.

Supervisor

Can supervise specific departments and tasks. Limited to assigned projects and departments.

User (Artist)

Standard user with access to assigned tasks and projects. Can track their own time and view their assignments.

Client

External client with limited read-only access to approved content.

Vendor

External vendor with access to specific outsourced tasks.

Contract Types

Person records support various contract types:

open-ended: Permanent/open-ended contracts
fixed-term: Fixed-term contracts
short-term: Short-term contracts
freelance: Freelance workers
apprentice: Apprentices
internship: Interns

Person Fields

string

Unique identifier for the person

first_name

string

required

Person’s first name

last_name

string

required

Person’s last name

string

required

Person’s email address (unique for non-bot users)

phone

string

Phone number

role

string

default:"user"

User role: user, admin, supervisor, manager, client, or vendor

position

string

Position type: supervisor, lead, or artist

seniority

string

Seniority level: senior, mid, or junior

contract_type

string

default:"open-ended"

Contract type (see Contract Types section)

active

boolean

default:"true"

Whether the person is active in the system

archived

boolean

default:"false"

Whether the person is archived

departments

array

Array of department IDs the person belongs to

Desktop login username for LDAP/SSO integration

timezone

string

Person’s timezone (e.g., “America/New_York”)

locale

string

Person’s locale for language/localization (e.g., “en_US”)

daily_salary

integer

default:"0"

Daily salary in cents for budgeting calculations

has_avatar

boolean

default:"false"

Whether the person has an uploaded avatar

is_bot

boolean

default:"false"

Whether this is a bot/service account

expiration_date

string

Account expiration date (for temporary accounts)

last_presence

string

Last detected presence (based on time tracking or desktop login)

Two-Factor Authentication

Zou supports multiple 2FA methods:

TOTP: Time-based One-Time Password (e.g., Google Authenticator)
Email OTP: Email-based one-time passwords
FIDO: FIDO/WebAuthn hardware security keys

totp_enabled

boolean

Whether TOTP 2FA is enabled

email_otp_enabled

boolean

Whether email OTP is enabled

fido_enabled

boolean

Whether FIDO 2FA is enabled

preferred_two_factor_authentication

string

Preferred 2FA method: totp, email_otp, or fido

Notification Settings

notifications_enabled

boolean

default:"false"

Whether notifications are enabled

notifications_slack_enabled

boolean

default:"false"

Whether Slack notifications are enabled

notifications_slack_userid

string

Slack user ID for notifications

notifications_mattermost_enabled

boolean

default:"false"

Whether Mattermost notifications are enabled

notifications_mattermost_userid

string

Mattermost user ID

notifications_discord_enabled

boolean

default:"false"

Whether Discord notifications are enabled

notifications_discord_userid

string

Discord user ID

LDAP Integration

is_generated_from_ldap

boolean

default:"false"

Whether this user was created via LDAP sync

ldap_uid

string

LDAP unique identifier (unique across all users)

Time Tracking & Presence

Person records track time spent and presence data: Track when users log in from their desktop applications:

GET /api/data/persons/{person_id}/desktop-login-logs
POST /api/data/persons/{person_id}/desktop-login-logs

See Person Management Endpoints for details.

Time Spent

Track time spent on tasks by day, week, month, or year:

GET /api/data/persons/{person_id}/time-spents
GET /api/data/persons/{person_id}/time-spents/{date}
GET /api/data/persons/{person_id}/time-spents/year/{year}
GET /api/data/persons/{person_id}/time-spents/month/{year}/{month}
GET /api/data/persons/{person_id}/time-spents/week/{year}/{week}
GET /api/data/persons/{person_id}/time-spents/day/{year}/{month}/{day}

Day Offs

Manage vacation and time off:

GET /api/data/persons/{person_id}/day-offs
GET /api/data/persons/{person_id}/day-offs/{date}
GET /api/data/persons/{person_id}/day-offs/year/{year}
GET /api/data/persons/{person_id}/day-offs/month/{year}/{month}
GET /api/data/persons/{person_id}/day-offs/week/{year}/{week}

Quota Tracking

Track shot quotas (completed shots) for performance metrics:

GET /api/data/persons/{person_id}/quota-shots/month/{year}/{month}
GET /api/data/persons/{person_id}/quota-shots/week/{year}/{week}
GET /api/data/persons/{person_id}/quota-shots/day/{year}/{month}/{day}

Quota endpoints support a count_mode query parameter:

weighted: Count weighted shots (default)
weighteddone: Count weighted completed shots
feedback: Count shots with feedback
done: Count completed shots

Department Assignment

Users can be assigned to multiple departments:

# Add person to department
POST /api/actions/persons/{person_id}/departments/add
{
  "department_id": "dept-uuid"
}

# Remove person from department  
DELETE /api/actions/persons/{person_id}/departments/{department_id}

Password Management

Admins can change passwords for users:

POST /api/actions/persons/{person_id}/change-password
{
  "password": "newPassword123",
  "password_2": "newPassword123"
}

Admins cannot change passwords for other admin accounts or protected accounts. The system sends an email notification when a password is changed.

Protected Accounts

Accounts listed in the PROTECTED_ACCOUNTS configuration cannot:

Have their role changed
Be deactivated
Have their password changed by other admins (only by themselves)

This protects critical system accounts from accidental modification.

User Invitations

Invite new users via email:

GET /api/actions/persons/{person_id}/invite

Sends an invitation email with a registration link valid for 7 days.

Avatar Management

Clear a user’s avatar:

DELETE /api/actions/persons/{person_id}/clear-avatar

Bot Accounts

Bot accounts (is_bot: true) are special service accounts:

Can have null email addresses
Generate an access token on creation
Don’t count against user limits
Can have expiration dates

When creating a bot:

{
  "first_name": "API",
  "last_name": "Bot",
  "email": null,
  "is_bot": true,
  "role": "user"
}

Response includes an access_token for API authentication.

Permissions

Read Permissions

All authenticated users can view person lists
Admins see full details
Managers see safe serialization (no sensitive fields)
Regular users see minimal information

Create Permissions

Only admins can create persons
User limit is checked for active non-bot users

Update Permissions

Users can update their own profile (limited fields)
Admins can update any user
Protected accounts have restrictions
Some fields require admin permissions (role, active, departments)

Delete Permissions

Only admins can delete persons
Users cannot delete themselves

Examples

Create a New User

POST /api/data/persons

{
  "first_name": "Jane",
  "last_name": "Smith",
  "email": "jane.smith@studio.com",
  "role": "user",
  "contract_type": "open-ended",
  "departments": ["animation-dept-id"],
  "timezone": "America/Los_Angeles",
  "locale": "en_US"
}

Update User Role

PUT /api/data/persons/{person_id}

{
  "role": "supervisor",
  "position": "supervisor",
  "seniority": "senior"
}

Get User Time Spent for Month

GET /api/data/persons/{person_id}/time-spents/month/2024/3

{
  "total_duration": 173.5,
  "year": 2024,
  "month": 3
}

Assign User to Department

POST /api/actions/persons/{person_id}/departments/add

{
  "department_id": "modeling-dept-uuid"
}

Person Endpoints - Full API reference
Department Management - Department organization
Authentication - Login and authentication

Authentication

Projects

Assets

Shots & Sequences

Tasks

Files & Previews

People & Teams

Comments & Playlists

Events & Notifications

Overview

User Roles

Contract Types

Person Fields

Two-Factor Authentication

Notification Settings

LDAP Integration

Time Tracking & Presence

Time Spent

Day Offs

Quota Tracking

Department Assignment

Password Management

Protected Accounts

User Invitations

Avatar Management

Bot Accounts

Permissions

Read Permissions

Create Permissions

Update Permissions

Delete Permissions

Examples

Create a New User

Update User Role

Get User Time Spent for Month

Assign User to Department

Build docs developers (and LLMs) love

Authentication

Projects

Assets

Shots & Sequences

Tasks

Files & Previews

People & Teams

Comments & Playlists

Events & Notifications

Documentation Index

​Overview

​User Roles

​Contract Types

​Person Fields

​Two-Factor Authentication

​Notification Settings

​LDAP Integration

​Time Tracking & Presence

​Desktop Login Logs

​Time Spent

​Day Offs

​Quota Tracking

​Department Assignment

​Password Management

​Protected Accounts

​User Invitations

​Avatar Management

​Bot Accounts

​Permissions

​Read Permissions

​Create Permissions

​Update Permissions

​Delete Permissions

​Examples

​Create a New User

​Update User Role

​Get User Time Spent for Month

​Assign User to Department

​Related Resources

Build docs developers (and LLMs) love

Overview

User Roles

Contract Types

Person Fields

Two-Factor Authentication

Notification Settings

LDAP Integration

Time Tracking & Presence

Desktop Login Logs

Time Spent

Day Offs

Quota Tracking

Department Assignment

Password Management

Protected Accounts

User Invitations

Avatar Management

Bot Accounts

Permissions

Read Permissions

Create Permissions

Update Permissions

Delete Permissions

Examples

Create a New User

Update User Role

Get User Time Spent for Month

Assign User to Department

Related Resources