Zum Inhalt springen
Leadtime
Deutsch
EnglishDeutschNicht übersetzt
Esc
↑↓navigieren↵öffnen⌘Jvorschau

Create employee

Creates a new employee in the workspace with automatic user account creation and team assignments.

How employee creation works:

  1. A new employee record is created with the provided information
  2. If canLogin is true, a user account is automatically created:
    • User status is set to Active
    • In ready workspaces, an invitation email is sent to the employee
    • During initial workspace setup, invitation email delivery is deferred until setup is finished
    • The user is assigned the specified role
  3. If an existing HelpdeskUser with the same email exists, it will be upgraded to Employee type
  4. Teams are assigned if provided in the teams array
  5. Employee data is automatically synced with the user account

Required fields:

  • firstName: Employee first name
  • lastName: Employee last name
  • email: Unique email address (must not exist in the workspace)
  • roleId: Role ID to assign to the user account

Optional fields:

  • position: Job title/position
  • canLogin: Whether employee can login (default: false)
  • teams: Array of team IDs to assign the employee to
  • avatarId: File ID from POST /workspace/upload endpoint

Custom fields: Employees do not support custom fields through this API.

Avatar upload process:

  1. First, upload the avatar file using POST /workspace/upload
  2. Get the file ID from the upload response
  3. Use that file ID in the avatarId field when creating the employee

Note: The email address must be unique within the workspace. If canLogin is false, no user account is created initially, but one can be created later by updating the employee. To list or verify employees after creation, use GET /employees/grid if you have Employees.manage permission, or GET /workspace/users for the user list. There is no GET /employees list endpoint.

POST/employees
Authorization
AuthorizationOAuth2 access token · headerrequired
Scopes:api:write
or
AuthorizationBearer token (JWT) · headerrequired
Query parameters
fieldsToReturnstring

Comma-separated list of top-level response fields to return. Overrides the endpoint compact default unless responseShape=full is used.

responseShapestring

Advanced override. Omit for the endpoint compact default. Use full only when you need the complete endpoint response, including nested fields that are not selectable with fieldsToReturn.

Allowed:compactfull
Header parameters
LT-Response-Shapestring

Advanced override. Set to full only when you need the complete endpoint response, including nested fields that are not selectable with fieldsToReturn.

Allowed:full
Request body
requiredapplication/json
avatarConfigobject

Generated avatar configuration. If provided, it takes precedence over avatarId.

avatarIdstring | null

Avatar configuration ID. During the transition, an image file ID from POST /workspace/upload is also accepted and converted to an uploaded avatar configuration. Omit to create the default generated avatar.

canLoginboolean

Whether the employee can login to the system. If true, a user account will be created automatically with Active status. In ready workspaces, an invitation email is sent immediately. During initial workspace setup, invitation emails are suppressed until setup is finished. If false, no user account is created initially (but can be created later via update).

default: false
emailstringrequired

Email address of the employee. Must be unique within the workspace. If canLogin is true, this will be the login email. If a HelpdeskUser with this email exists, it will be upgraded to Employee type.

employmentModestring

Employment mode classification (e.g., FullTime, PartTime, Contract, Temporary, Freelance). Omit to use the default FullTime. This is metadata only and does not change working hours, schedule, capacity, or availability.

Allowed:FullTimePartTimeContractTemporaryFreelance
firstNamestringrequired

First name of the employee. This will be synced to the user account if canLogin is true.

lastNamestringrequired

Last name of the employee. This will be synced to the user account if canLogin is true.

positionstring

Job title or position of the employee (e.g., "Software Engineer", "Product Manager", "Sales Director").

roleIdstringrequired

Role ID to assign to the employee user account. The role determines what permissions the employee has when they log in. Use GET /administration/roles to retrieve available role IDs.

teamsstring[]

Array of team IDs to assign the employee to. Use GET /teams to retrieve available teams. Teams are used for organizational structure and permissions. Provide an empty array or omit to create an employee without team assignments.

Responses
200
addressCityobject | nullrequired

City name. Null if address is not set.

addressCountryobject | nullrequired

Country code in ISO 3166-1 alpha-2 format (e.g., "DE", "US"). Null if address is not set.

addressHouseNumberobject | nullrequired

House or building number. Null if address is not set.

addressStreetobject | nullrequired

Street name (without house number). Null if address is not set.

addressZipobject | nullrequired

ZIP or postal code. Null if address is not set.

avatarIdobject | nullrequired

Avatar configuration ID. Use /api/avatars/public/{avatarId}.svg to render it.

avatarUrlobject | nullrequired

Full URL to the employee's avatar image. Generated from the avatar file ID. Null if employee has no avatar. Use this URL to display the avatar in your application.

birthDateobject | nullrequired

Birth date in ISO 8601 date format (YYYY-MM-DD). Null if not set.

canLoginbooleanrequired

Whether the employee can login to the system. If true, the employee has an active user account and can access the system.

chargeableHoursDayGoalobject | nullrequired

Chargeable (billable) hours per day goal. Null if not set.

createdAtstringrequired

Timestamp when the employee record was created, in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ).

degreeobject | nullrequired

Academic degree (e.g., "B.Sc.", "M.Sc.", "Ph.D."). Null if not set.

emailstringrequired

Email address of the employee. This is also the login email if canLogin is true.

employmentModeobject | nullrequired

Employment mode indicating the type of employment (e.g., "FullTime", "PartTime", "Contract", "Temporary", "Freelance"). Null if not set.

entryDateobject | nullrequired

Date when the employee joined the company, in ISO 8601 date format (YYYY-MM-DD). Null if not set.

exitDateobject | nullrequired

Date when the employee left the company, in ISO 8601 date format (YYYY-MM-DD). Null if employee is still active. Used to calculate isActive status.

firstNamestringrequired

First name of the employee

idstringrequired

Unique identifier of the employee (UUID format)

incomeTaxClassobject | nullrequired

Income tax class (typically used in German tax system, values like "1", "2", "3", etc.). Null if not set.

isActivebooleanrequired

Whether the employee is currently active. Calculated as: exitDate is null OR exitDate is in the future. Active employees appear in employee lists and can be assigned to teams/projects.

lastNamestringrequired

Last name of the employee

phoneobject | nullrequired

Phone number in the format stored in the system. Null if not provided.

positionobject | nullrequired

Job title or position of the employee. Null if not set.

roleIdstringrequired

Role ID assigned to the employee user account. The role determines what permissions the employee has when they log in.

salariesobject[]

Array of salary entries for the employee. Each entry defines a salary amount that applies from a specific date.

teamIdsstring[]required

Array of team IDs the employee is assigned to. Teams are used for organizational structure and permissions. Empty array if employee is not assigned to any teams.

titleobject | nullrequired

Title prefix (e.g., "Mr.", "Mrs.", "Dr.", "Prof."). Null if not set.

updatedAtstringrequired

Timestamp when the employee record was last updated, in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ).

userIdstringrequired

ID of the associated user account. This links the employee record to the user account that handles authentication and permissions.

vacationDaysobject[]

Array of vacation days entries for the employee. Each entry defines vacation days per year that apply from a specific date.

weeklyWorkingTimeobject[]

Array of weekly working time entries for the employee. Each entry defines working days and hours that apply from a specific date. The active entry for a given date is the one with the most recent dateFrom that is still on or before that date.

400

Validation errors

errorsobject
messagestring
statusCodenumber
401

Unauthorized - Invalid or missing authentication token

403

Forbidden - Insufficient API scopes or permissions

Try it
Server
Authorization
Parameters
Bodyapplication/json
Request
curl -X POST "https://leadtime.app/api/public/employees" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "avatarConfig": {
    "options": {
      "seed": "Jane Doe"
    },
    "style": "initials"
  },
  "avatarId": "123e4567-e89b-12d3-a456-426614174000",
  "canLogin": false,
  "email": "john.doe@company.com",
  "employmentMode": "PartTime",
  "firstName": "John",
  "lastName": "Doe",
  "position": "Software Engineer",
  "roleId": "ws_abc_role_123",
  "teams": [
    "team_1",
    "team_2"
  ]
}'
Response
{
  "addressCity": "Berlin",
  "addressCountry": "DE",
  "addressHouseNumber": "42",
  "addressStreet": "Main Street",
  "addressZip": "12345",
  "avatarId": "123e4567-e89b-12d3-a456-426614174000",
  "avatarUrl": "https://workc.example.com/api/avatars/public/avatar_123.svg",
  "birthDate": "1990-01-15",
  "canLogin": true,
  "chargeableHoursDayGoal": 6.5,
  "createdAt": "2020-01-15T10:00:00Z",
  "degree": "M.Sc.",
  "email": "john.doe@company.com",
  "employmentMode": "FullTime",
  "entryDate": "2020-01-15",
  "exitDate": null,
  "firstName": "John",
  "id": "emp_123",
  "incomeTaxClass": "1",
  "isActive": true,
  "lastName": "Doe",
  "phone": "+1234567890",
  "position": "Software Engineer",
  "roleId": "ws_abc_role_123",
  "salaries": [
    {
      "dateFrom": "2021-01-01",
      "id": "sal_123",
      "salary": 5000
    }
  ],
  "teamIds": [
    "team_1",
    "team_2"
  ],
  "title": "Mr.",
  "updatedAt": "2020-01-15T10:00:00Z",
  "userId": "user_123",
  "vacationDays": [
    {
      "dateFrom": "2021-01-01",
      "days": 30,
      "id": "vac_123"
    }
  ],
  "weeklyWorkingTime": [
    {
      "dateFrom": "2021-01-01",
      "id": "wwt_123",
      "weeklyWorkingHours": 40,
      "workingDays": [
        1,
        1,
        1,
        1,
        1,
        0,
        0
      ]
    }
  ]
}