Zum Inhalt springen
Leadtime
Deutsch
EnglishDeutschNicht übersetzt
Esc
↑↓navigate↵open⌘Jpreview

Update employee

Partially updates an existing employee. Only the fields you provide will be updated; all other fields remain unchanged.

How updates work:

  • Personal information (firstName, lastName, email, phone, address, birth date, title, degree, position):
    • Updates the employee record
    • If email, firstName, or lastName changes, the associated user account is automatically synced
  • Access settings (canLogin, roleId):
    • Updates the user account permissions
    • If canLogin changes from false to true:
      • User account is created if it doesn’t exist
      • User status becomes Active
      • In ready workspaces, an invitation email is sent automatically
      • During initial workspace setup, invitation email delivery is deferred until setup is finished
    • If email is changed and a HelpdeskUser with that email exists, it will be upgraded to Employee type
  • Team assignments (teams):
    • Replaces the entire team assignment list
    • Provide an empty array to remove all team assignments
    • Omit teams to leave team assignments unchanged
  • Avatar (avatarId):
    • Set to a file ID from POST /workspace/upload to update the avatar
    • Set to null to remove the avatar
  • Working conditions (chargeableHoursDayGoal):
    • Updates the chargeable (billable) hours per day goal
    • Used for time tracking targets and notifications
    • Set to null to remove the goal

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

Update process:

  1. Verify the employee exists (returns 404 if not found)
  2. Update personal information if provided
  3. Update access settings if provided
  4. Update team assignments if provided
  5. Update working conditions if provided
  6. Return the updated employee with all current data

Note: All updates are validated and will fail if validation rules are violated (e.g., email must be unique). The response includes the complete updated employee record.

PATCH/employees/{id}
Authorization
AuthorizationOAuth2 access token · headerrequired
Scopes:api:write
or
AuthorizationBearer token (JWT) · headerrequired
Path parameters
idstringrequired
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
addressCityobject | null
City name. Set to null to clear the city.
addressCountryobject | null
Country code in ISO 3166-1 alpha-2 format (e.g., "DE" for Germany, "US" for United States). Set to null to clear the country.
addressHouseNumberobject | null
House or building number. Set to null to clear the house number.
addressStreetobject | null
Street name (without house number). Set to null to clear the street address.
addressZipobject | null
ZIP or postal code. Set to null to clear the ZIP code.
avatarConfigobject
Generated avatar configuration. If provided, it takes precedence over avatarId.
avatarIdobject | 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. Set to null to remove the avatar.
birthDateobject | null
Birth date in ISO 8601 date format (YYYY-MM-DD). Set to null to remove the birth date.
canLoginboolean
Whether the employee can login to the system. When changed from false to true: user account is created (if it doesn't exist), and user status becomes Active. In ready workspaces, an invitation email is sent automatically. During initial workspace setup, invitation emails are suppressed until setup is finished.
chargeableHoursDayGoalobject | null
Chargeable (billable) hours per day goal. Used for time tracking targets and notifications.
degreeobject | null
Academic degree (e.g., "B.Sc.", "M.Sc.", "Ph.D.", "MBA"). Set to null to remove the degree.
emailstring
Email address of the employee. Must be unique within the workspace. If changed, the associated user account will be synced. If a HelpdeskUser with the new email exists, it will be upgraded to Employee type.
employmentModestring
Employment mode classification (e.g., FullTime, PartTime, Contract, Temporary, Freelance). This is metadata only and does not change working hours, schedule, capacity, or availability.
Allowed:FullTimePartTimeContractTemporaryFreelance
firstNamestring
First name of the employee. If changed, the associated user account will be automatically synced.
lastNamestring
Last name of the employee. If changed, the associated user account will be automatically synced.
phoneobject | null
Phone number in any format. Set to null to remove the phone number.
positionstring
Job title or position of the employee (e.g., "Senior Software Engineer", "Product Manager").
roleIdstring
Role ID to assign to the employee user account. The role determines permissions. Must be a valid role ID from your workspace.
teamsstring[]
Array of team IDs to assign the employee to. This replaces the entire team assignment list. Provide an empty array to remove all team assignments. Omit this field to keep existing team assignments unchanged.
titleobject | null
Title prefix (e.g., "Mr.", "Mrs.", "Ms.", "Dr.", "Prof."). Set to null to remove the title.
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.
401Unauthorized - Invalid or missing authentication token
403Forbidden - Insufficient API scopes or permissions
Request
curl -X PATCH "https://leadtime.app/api/public/employees/string" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "addressCity": "Berlin",
  "addressCountry": "DE",
  "addressHouseNumber": "42",
  "addressStreet": "Main Street",
  "addressZip": "12345",
  "avatarConfig": {
    "options": {
      "seed": "Jane Doe"
    },
    "style": "initials"
  },
  "avatarId": "123e4567-e89b-12d3-a456-426614174000",
  "birthDate": "1990-01-15",
  "canLogin": true,
  "chargeableHoursDayGoal": 6.5,
  "degree": "M.Sc.",
  "email": "jane.smith@company.com",
  "employmentMode": "PartTime",
  "firstName": "Jane",
  "lastName": "Smith",
  "phone": "+1234567890",
  "position": "Senior Software Engineer",
  "roleId": "ws_abc_role_456",
  "teams": [
    "team_1",
    "team_3"
  ],
  "title": "Dr."
}'
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
      ]
    }
  ]
}