> ## Documentation Index > Fetch the complete documentation index at: https://docs.pland.app/llms.txt > Use this file to discover all available pages before exploring further. # Update a Job > Update a job (v2). The job fields go into the `job` object, the edit options next to it. **Warning: only use this endpoint if you know exactly what it does.** It applies the same logic as the PlanD planner: with `type` FUTURE it can split a recurring series, with THIS it detaches a single occurrence, and `userIds` replaces the assigned users (omitting it unassigns all current users). A wrong request changes the schedule of your employees. Try your requests against the sandbox server first. ## OpenAPI ````yaml PATCH /jobs/{id}/v2 openapi: 3.0.0 info: title: PlanD API description: PlanD Public API version: '2' servers: - url: https://cloud-api.pland.app/v2 description: Production Server - url: https://beta-api.pland.app/v2 description: Sandbox Server security: [] tags: - name: Absences description: >- Absence management endpoints for creating, updating, and managing user absences - name: Customers description: Customer management operations - name: Customer Objects description: >- Customer object management operations - locations and buildings where services are performed - name: Documents description: >- Document management operations for uploading, retrieving, and managing files - name: Logbuch description: >- Operations for sending, retrieving, updating, and deleting Logbuch in entity chats. - name: Equipment description: Equipment management operations - name: Jobs description: >- Endpoints for managing jobs, including creation, listing, updating, and job-specific actions. - name: Material Orders description: Operations for listing, viewing, updating, and managing material orders. - name: Articles description: >- Operations for creating, listing, viewing, updating, and deleting articles. - name: Quality Control description: Quality control and assessment management operations - name: Salary description: >- Salary management operations for tracking and managing employee compensation - name: Tasks description: Task management operations - name: Task Types description: Task type management operations - name: Time Tracking description: >- Time tracking management endpoints for recording, monitoring, and managing work time entries - name: Users description: >- User management endpoints for creating, updating, and managing system users - name: Webhooks paths: /jobs/{id}/v2: patch: tags: - Jobs summary: Update a job description: >- Update a job (v2). The job fields go into the `job` object, the edit options next to it. **Warning: only use this endpoint if you know exactly what it does.** It applies the same logic as the PlanD planner: with `type` FUTURE it can split a recurring series, with THIS it detaches a single occurrence, and `userIds` replaces the assigned users (omitting it unassigns all current users). A wrong request changes the schedule of your employees. Try your requests against the sandbox server first. operationId: patchJob parameters: - name: id in: path description: Job ID required: true schema: type: string format: objectid - name: updateTeam in: query description: Apply the update to all jobs of the team required: false schema: type: string enum: - 'true' - 'false' requestBody: required: true content: application/json: schema: required: - job properties: job: description: >- The job fields to set. `targetTime` (seconds) and `iCalendar` are required. allOf: - $ref: '#/components/schemas/Job' - required: - targetTime - iCalendar userIds: description: >- The full set of assigned users after the update. Omitting it unassigns the current users. type: array items: type: string format: objectid type: description: >- Edit only this occurrence or this and all future ones. Default: FUTURE type: string enum: - THIS - FUTURE splitDate: description: Occurrence date where the series is split (epoch ms) type: integer format: int64 exDate: description: Occurrence date to exclude from the series (epoch ms) type: integer format: int64 changedFrom: description: Date the occurrence was moved from (epoch ms) type: integer format: int64 changedTo: description: Date the occurrence was moved to (epoch ms) type: integer format: int64 unset: description: Job fields to remove type: array items: type: string type: object example: job: targetTime: 3600 iCalendar: frequency: WEEKLY interval: 1 dtstart: '1793865600000' byDay: - MO userIds: - 665f1c2e9b1e8a0012345678 type: FUTURE responses: '200': description: Job updated content: application/json: schema: $ref: '#/components/schemas/Job' '400': description: Invalid input '401': description: Unauthorized '403': description: Forbidden '404': description: Job not found security: - API-Key: [] - Bearer-Auth: [] components: schemas: Job: title: Job description: >- A job assigned to a user or object, with scheduling, assignment, and status information. Inherits common fields from ChatableEntityModel. type: object allOf: - $ref: '#/components/schemas/ChatableEntityModel' - properties: assignmentId: description: Assignment ID format: objectid targetTime: description: Target time for the job in seconds (at most 86400) type: number format: float from: description: Start time of the job format: date-time to: description: End time of the job format: date-time userId: description: ID of the user type: string format: objectid wrapperId: description: Wrapper ID type: string format: objectid nullable: true absenceId: description: >- Absence Id, if this job is connected to an absence (if it needs a replacement) type: string format: objectid iCalendar: $ref: '#/components/schemas/ICalendarStruct' assignment: $ref: '#/components/schemas/Assignment' masterJobId: description: Master job ID if this is a replacement job format: objectid timeTrackings: description: Time tracking entries for the job type: array items: $ref: '#/components/schemas/TimeTrackingEntry' salaries: description: Salaries for the job type: array items: $ref: '#/components/schemas/Salary' splitId: description: Split job ID format: objected nullable: true acceptedStatus: description: Accepted status type: string jobComment: description: Comment for the job type: string teamId: description: Team ID format: objectid nullable: true activityType: oneOf: - $ref: '#/components/schemas/ActivityType' nullable: true description: Activity type for the job exceptionJobId: description: Exception job ID format: objectid nullable: true title: description: Title of the job type: string requiredDrivingTime: description: Required driving time in minutes type: integer format: float requiredBreakTime: description: Required break time in minutes type: integer format: float started: description: Job started entries type: array items: $ref: '#/components/schemas/JobStartedStruct' absences: description: Absences related to the job type: array items: $ref: '#/components/schemas/JobAbsencesStruct' documentIds: description: Document IDs related to the job type: array items: type: string format: objectid serviceReportId: description: Service Report ID if job is linked to a service report format: objectid nullable: true type: object ChatableEntityModel: title: Chatable Entity Model description: Base class for all entities that can have a chat associated with them. type: object allOf: - $ref: '#/components/schemas/Entity' - properties: chatId: description: ID of the chat associated with this entity type: string format: objectid nullable: true type: object ICalendarStruct: description: Represents a structured iCalendar object with recurrence rules properties: frequency: description: Recurrence frequency (e.g., DAILY, WEEKLY, MONTHLY) type: string tzid: description: Time zone ID for the recurrence rule type: string interval: description: Interval between occurrences type: integer rrule: description: Recurrence rule as a string type: string deprecated: true bySetPos: description: Position in the set for monthly recurrences type: integer byDay: description: Days of the week for the recurrence type: array items: type: string byMonthDay: description: Day of the month for the recurrence type: string byMonth: description: Months for the recurrence type: array items: type: integer dtstart: description: >- Start date and time of the recurrence (epoch ms; responses use the digit string, requests also accept an integer) example: '1793865600000' oneOf: - type: string pattern: ^[0-9]+$ - type: integer format: int64 dtend: description: >- End date and time of the recurrence (epoch ms; responses use the digit string, requests also accept an integer) example: '1796457600000' oneOf: - type: string pattern: ^[0-9]+$ - type: integer format: int64 exDate: description: >- Exception dates for the recurrence (epoch ms; job responses return integers, requests also accept digit strings) type: array items: oneOf: - type: integer format: int64 - type: string pattern: ^[0-9]+$ type: object Assignment: title: Assignment description: >- An Assignment acts as the overall structure for jobs. They contain information about what kind of work should be done, where it should be done and how it should be billed. Assignments can be used to track the time spent on a job, the materials used and the costs incurred. type: object allOf: - $ref: '#/components/schemas/ChatableEntityModel' - properties: objectId: description: ID of the customer object where this assignment is performed type: string format: objectid example: 507f1f77bcf86cd799439011 nullable: true customerId: description: ID of the customer who owns this assignment type: string format: objectid example: 507f1f77bcf86cd799439012 nullable: true title: description: Title or name of the assignment type: string example: Monthly Cleaning Service nullable: true iCalendar: oneOf: - $ref: '#/components/schemas/ICalendarStruct' nullable: true description: >- Calendar configuration defining when and how often this assignment occurs material: description: Materials or products associated with this assignment type: array items: type: object example: - productId: 507f1f77bcf86cd799439013 quantity: 2 nullable: true activityTypeId: description: ID of the activity type defining what kind of work is performed type: string format: objectid example: 507f1f77bcf86cd799439014 nullable: true comment: description: Additional comments or notes for this assignment type: string example: Special instructions for weekend work nullable: true documentIds: description: Array of document IDs attached to this assignment type: array items: type: string format: objectid example: - 507f1f77bcf86cd799439015 - 507f1f77bcf86cd799439016 billing: oneOf: - $ref: '#/components/schemas/AssignmentBilling' nullable: true description: >- Billing configuration for this assignment including pricing and invoice settings quota: $ref: '#/components/schemas/AssignmentQuota' autoGenerateInvoiceError: description: Error information from automatic invoice generation, if any type: object nullable: true costUnit: description: >- The cost unit of the assignment. Can be set to an arbitrary string type: string nullable: true jobChatId: description: ID of the chat that all jobs under this assignment share type: string format: objectid example: 507f1f77bcf86cd799439017 nullable: true useUserPayTypeOnly: description: >- When true, always use the user default pay type instead of the activity type pay type type: boolean nullable: true linkedCache: description: >- Cached data linked to this assignment for performance optimization type: array items: type: object nullable: true type: object TimeTrackingEntry: title: Time Tracking Entry description: >- A time tracking entry recording work time for a job, including start/end times, location data, and status information type: object allOf: - $ref: '#/components/schemas/ChatableEntityModel' - properties: _id: description: Unique identifier for the time tracking entry type: string format: objectid userId: description: ID of the user who performed the work type: string format: objectid jobId: description: ID of the job being tracked type: string format: objectid objectId: description: ID of the customer object/location where work was performed type: string format: objectid timeStart: description: Start timestamp of the work period (UTC) type: string format: date-time timeEnd: description: End timestamp of the work period (UTC) type: string format: date-time workingTime: description: Actual working time in seconds (timeEnd - timeStart - break) type: integer minimum: 0 targetTime: description: Target/expected working time in seconds type: integer minimum: 0 break: description: Break time in seconds type: integer minimum: 0 requiredBreakTime: description: Legally required break time in seconds type: integer minimum: 0 type: description: Type of time tracking entry type: string enum: - default - simple - offline - driving - manual location: description: GPS coordinates where work started properties: latitude: type: number format: float longitude: type: number format: float type: object logOutLocation: description: GPS coordinates where work ended properties: latitude: type: number format: float longitude: type: number format: float type: object approved: description: Whether the time tracking entry has been approved for billing type: boolean cancelled: description: Whether the time tracking entry has been cancelled type: boolean offline: description: Whether the entry was created while offline type: boolean generatedByUser: description: Whether the entry was manually created by a user type: boolean editedByManager: description: Whether the entry was modified by a manager type: boolean trackingJobDate: description: Date for which the work was scheduled/performed (UTC) type: string format: date-time comment: description: Additional comments or notes about the work performed type: string reason: description: Reason for manual time tracking entry creation type: string errors: description: Array of error codes preventing automatic salary release type: array items: type: string allFoundErrors: description: Array of all detected errors during time tracking validation type: array items: type: string salaryIds: description: Array of salary IDs created from this time tracking entry type: array items: type: string format: objectid objectManagerId: description: ID of the object manager responsible for this entry type: string format: objectid signingId: description: ID of associated signing document type: string format: objectid activityTypeId: description: ID of the activity type performed type: string format: objectid assignmentId: description: ID of the assignment associated with this time tracking type: string format: objectid type: object Salary: title: Salary description: >- A salary record representing payment information for work performed by a user. Inherits common fields from ChatableEntityModel. type: object allOf: - $ref: '#/components/schemas/ChatableEntityModel' - properties: userId: description: User ID who earned this salary type: string format: objectid timeTrackingId: description: Time tracking entry ID this salary is based on type: string format: objectid type: description: Type of salary (regular, overtime, etc.) type: string objectId: description: Object ID where the work was performed type: string format: objectid workingTime: description: Actual working time in seconds type: integer targetTime: description: Target working time in seconds type: integer reason: description: Reason or description for this salary entry type: string approvedByUserId: description: User ID who approved this salary type: string format: objectid updatedByUserId: description: User ID who last updated this salary type: string format: objectid from: description: Start date/time for this salary period type: string format: date-time to: description: End date/time for this salary period type: string format: date-time break: description: Break time in seconds type: integer minBreakTime: description: Minimum break time required in seconds type: integer absenceId: description: Only set when type = Salary Absence type: string format: objectid jobId: description: Job ID this salary is associated with type: string format: objectid trackingJobDate: description: Date/time when job tracking was started type: string format: date-time ignoreDoubleSalaries: description: Whether to ignore double salary checks type: boolean roundedUp: description: Whether working time was rounded up type: boolean roundUpSeconds: description: Seconds that were rounded up type: integer payType: description: Pay type classification type: string nightWorkingTime: description: >- Total working time during night hours in seconds (deprecated - use surcharges) type: integer deprecated: true sundayWorkingTime: description: >- Total working time on Sunday in seconds (deprecated - use surcharges) type: integer deprecated: true publicHolidayWorkingTime: description: >- Total working time on public holidays in seconds (deprecated - use surcharges) type: integer deprecated: true surcharges: description: >- Array of salary surcharges for special work conditions (night, weekend, holiday, etc.) type: array items: $ref: '#/components/schemas/SurchargeOnSalary' workloadSurcharges: description: >- Array of workload-based surcharges (calculated from daily/weekly hour thresholds) type: array items: $ref: '#/components/schemas/SurchargeOnSalary' nullable: true drivingTime: description: Total driving time in seconds type: integer drivingTimeFrame: oneOf: - $ref: '#/components/schemas/TimeFrame' nullable: true description: >- Clock time of the drive as tracked in the app, only set when the driving time was tracked payTypeId: description: Resolved pay type ID (snapshot from creation) type: string format: objectid nullable: true payTypeSource: description: Source of resolved pay type type: string enum: - user_default - activity_type nullable: true assignmentId: description: Assignment ID this salary belongs to type: string format: objectid activityTypeId: description: Activity type ID for categorizing work type: string format: objectid releasedBySystem: description: Indicates if this salary was released by the system type: boolean nullable: true locked: description: >- Indicates if this salary is locked and cannot be changed or deleted type: boolean nullable: true type: object ActivityType: title: Activity Type description: >- Activity type defines the category of work to be performed (e.g., cleaning, maintenance) required: - name type: object allOf: - $ref: '#/components/schemas/Entity' - properties: _id: description: Unique identifier for the activity type type: string format: objectid name: description: Name of the activity type type: string example: Unterhaltsreinigung hexCode: description: Color code for visual representation in hex format type: string pattern: ^#[0-9A-Fa-f]{6}$ example: '#34c759' nullable: true description: description: Detailed description of the activity type type: string example: Regular maintenance cleaning activities nullable: true payTypeId: description: >- Optional pay type for this activity type. When set, assignments with this activity type may use this pay type instead of the user default (higher wage wins). type: string format: objectid nullable: true type: object JobStartedStruct: title: JobStartedStruct description: >- This is the structure that is used to store the information about a started job. properties: trackingJobDate: description: The date when the job was started. type: string format: date-time userId: description: The ID of the user on the job. type: string format: object-id time: description: The time when the job was started. type: string format: date-time isLive: description: Indicates if the job is live or already finished. type: boolean wasAddedManually: description: >- This indicates if the started variable was added due to that the time tracking was added manually later type: boolean salaryId: description: |- The Salary that created the stared object. may not be setted type: object JobAbsencesStruct: title: JobAbsencesStruct description: This struct contains the absences that affect a job. required: - absenceId - dtStart - dtEnd - calculationType type: object allOf: - $ref: '#/components/schemas/Entity' - properties: absenceId: description: The ID of the absence that affects this job. type: string format: objectId dtStart: description: The start date and time of the absence. type: string format: date-time dtEnd: description: The end date and time of the absence. type: string format: date-time calculationType: description: The type of calculation for the absence. type: string type: object Entity: title: Entity description: >- Base class for all entities in the system, providing common properties and methods. properties: _id: description: Unique identifier of the entity type: string format: objectid number: description: Unique number of the entity, used for identification type: integer companyId: description: The ID of the company this entity belongs to type: string format: objectid x-internal: true status: $ref: '#/components/schemas/StatusStruct' type: object AssignmentBilling: description: Base class for assignment billing types properties: type: description: Type of billing type: string enum: - MANUAL - RECURRING - ON_EVENT positions: description: Array of positions/line items for invoice generation type: array items: type: object oneOf: - $ref: '#/components/schemas/InvoicePosition' - $ref: '#/components/schemas/TextPosition' - $ref: '#/components/schemas/DynamicPosition' lastInvoiceDate: description: Date of the last invoice type: string format: date-time defaultInvoiceTemplateId: description: Default invoice template ID for automatic invoice creation type: string format: objectId type: object AssignmentQuota: description: The Assignment Quota defines the quota for an assignment properties: enabled: description: Are quotas enabled type: boolean quotaCalculation: description: How is the Assignment Quota calculated? type: string enum: - once - weekly - monthly total: description: >- The quota total. The meaning of this value is dependent on the quotaCalculation type: number format: float billingRateEnabled: description: Is the billing rate calculation enabled type: boolean billingRateCalculation: description: Defines how the billingRate is calculated type: string enum: - hourly - flat - dynamic billingRateAmount: description: >- The billing rate amount. The meaning of this value is dependent on the billingRateCalculation type: number format: float expectedMargin: description: >- The Margin the customer expects. We use this number to calculate the real margin of the customer. Value should be between 0.0 - 1.0 type: number format: float type: object SurchargeOnSalary: title: Surcharge on Salary description: >- Represents a surcharge applied to a salary for special work conditions like night hours, weekends, holidays, or driving time. required: - seconds type: object allOf: - $ref: '#/components/schemas/Entity' - properties: surchargeId: description: Surcharge ID reference type: string format: objectid name: description: >- Name of the surcharge (e.g., "Night Shift", "Weekend", "Holiday") type: string number: description: Surcharge number for ordering/display purposes type: integer surcharge: description: Surcharge percentage (e.g., 25 for 25% surcharge) type: number format: float surchargeType: description: 'Type of surcharge: percent or fixed_hourly' type: string enum: - percent - fixed_hourly wage: description: Fixed wage per hour (used when surchargeType is fixed_hourly) type: number format: float taxFreeType: description: Tax-free category per ยง 3b EStG type: string enum: - none - night - sunday - holiday - special_holiday taxFreeNumber: description: Separate payroll number for tax-free portion type: integer nullable: true activeOn: description: Configuration defining when this surcharge is active type: object userId: description: User ID (used in salary export rows) type: string format: objectid date: description: Date (used in salary export rows) type: string format: date seconds: description: Duration of the surcharge application in seconds type: integer minimum: 0 activeTimeFrames: description: >- Time frames when this surcharge was active during the salary period type: array items: properties: from: description: Start time of the surcharge period type: string format: date-time to: description: End time of the surcharge period type: string format: date-time type: object _cash: description: >- Calculated cash amount for this surcharge (available in combined calculations) type: number format: float default: 0 type: object TimeFrame: description: Represents a time frame with a start and end date. properties: from: description: The start date of the time frame. type: string format: date-time to: description: The end date of the time frame. type: string format: date-time type: object StatusStruct: description: Entity Status information properties: status: description: Current status type: integer createdAt: description: Creation timestamp type: string format: date-time createdBy: description: User who created this supplier type: string format: objectid lastModifiedAt: description: Last modification timestamp type: string format: date-time lastModifiedBy: description: User who last modified this supplier type: string format: objectid agentId: description: Agent that created or modified this entity type: string format: objectid nullable: true assistantId: description: >- Text assistant that created or modified this entity on behalf of a user type: string format: objectid nullable: true type: object InvoicePosition: title: Invoice Position description: >- Represents a line item position in an invoice, offer, or credit note. Contains pricing, tax, and product information. required: - quantity - unit - price - tax - title type: object allOf: - $ref: '#/components/schemas/RawPosition' - properties: quantity: description: Quantity of the item or service type: number format: float minimum: 0 example: 2.5 unit: description: Unit of measurement (e.g., "hours", "pieces", "kg") type: string example: hours price: description: Unit price of the item or service type: number format: float minimum: 0 example: 32.5 tax: description: >- Tax rate as decimal (e.g., 0.19 for 19% tax) - deprecated, use taxRate instead type: number format: float maximum: 1 minimum: 0 example: 0.19 deprecated: true taxRate: oneOf: - $ref: '#/components/schemas/TaxRate' nullable: true description: Tax rate object containing detailed tax information title: description: Title or name of the item or service type: string example: Cleaning Service description: description: Description of the item or service type: string example: Detailed description of the cleaning service nullable: true discount: description: >- Discount applicable to the item or service, represented as a decimal (e.g., 0.1 for 10% discount) type: number format: float maximum: 1 minimum: 0 example: 0.1 nullable: true productId: description: Identifier for the product associated with this invoice position type: string format: uuid example: 550e8400-e29b-41d4-a716-446655440000 nullable: true includedWageCostFactor: description: >- Wage cost factor included in the price, used for internal calculations type: number format: float example: 0.95 nullable: true isOptional: description: >- If true, the position will not be included in the total price calculation type: boolean example: false nullable: true bookingAccountNumber: description: >- Used when the invoice is fixed, so that later changes for the product can not overwrite the original number type: string example: ACC-123456 nullable: true skontoBookingAccountNumber: description: Skonto booking account number, used for early payment discounts type: string example: SKONTO-123456 nullable: true assignmentId: description: >- ID of the assignment this position originates from (for collective invoices, used for cost unit in exports) type: string format: objectid nullable: true type: object TextPosition: title: Text Position description: >- A simple Text position for an invoice. This position is used to add custom text to an invoice, e.g. for notes or additional information. type: object allOf: - $ref: '#/components/schemas/RawPosition' - properties: text: description: The text content of the position type: string type: object DynamicPosition: title: Dynamic Position description: >- A dynamic position in an assignment, which can be converted to a standard invoice position. type: object allOf: - $ref: '#/components/schemas/InvoicePosition' - properties: dynamicType: description: >- The calculation type for this position, i.e. whether the actual working time, the planned time, the confirmed time or the number of job occurences should be used. type: string enum: - PLANNED_TIME - WORKING_TIME - SALARY_TIME - JOB_COUNT type: object RawPosition: description: Base class for all raw positions in the invoice system properties: type: description: Type of the position type: string enum: - INVOICE_POSITION - PRODUCT_POSITION - TEXT_POSITION - DYNAMIC_POSITION type: object TaxRate: title: TaxRate description: Tax rate configuration for invoices and positions required: - type - rate type: object allOf: - $ref: '#/components/schemas/Entity' - properties: type: description: Type of tax rate (VAT, ZERO_RATE, EXEMPT, REVERSE_CHARGE) type: string enum: - VAT - ZERO_RATE - EXEMPT - REVERSE_CHARGE example: VAT rate: description: Tax rate as decimal (e.g., 0.19 for 19% tax, 0.07 for 7% tax) type: number format: float maximum: 1 minimum: 0 example: 0.19 description: description: Human-readable description of the tax rate type: string example: Regelsteuersatz nullable: true bookingAccountNumber: description: Booking account number for accounting integration type: string example: '8400' nullable: true skontoBookingAccountNumber: description: Skonto booking account number for early payment discounts type: string example: '8405' nullable: true default: description: Whether this is a system default tax rate (cannot be deleted) type: boolean example: false type: object securitySchemes: API-Key: type: apiKey name: x-API-Key in: header Bearer-Auth: type: http bearerFormat: JWT scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.