Jobs: field and bulk edits
Move selected jobs to a calendar date
/a/Jobs_setMeetingDate
Replace the tenant-local calendar date of selected jobs while retaining each job’s time of day.
When to use this endpoint
Replace the tenant-local calendar date of selected jobs while retaining each job’s time of day.
Read the target jobs first with Jobs_getSome to obtain the current values and confirm the IDs belong to the intended account.
Authentication and permissions
Authenticate with signed API-key fields or a logged-in CRM session. Requests address physical job IDs in the authenticated account.
The legacy job-edit restriction bit 128 blocks the request before reads or writes unless the user is a client administrator, matching Job_setMeetingTime. No additional assignee or department scope is applied.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
ids | Native array | Yes | Native list of positive decimal job IDs; JSON strings and nonscalar/nonpositive members are rejected. Duplicates are removed. Empty lists are a successful no-op; missing/deleted jobs are omitted by the active-job query. |
date | YYYY-MM-DD string | Yes | Strict real YYYY-MM-DD calendar date with year at least 2013, without surrounding whitespace or a time suffix. Replaces each selected job’s tenant-local calendar date while preserving its local time of day. |
Example request
$result = FM_api('Jobs_setMeetingDate', ['ids'=>['1042','1088'], 'date'=>'2026-11-20']);Example response
{"ok":"1"}Errors and unusual responses
| Response | Condition |
|---|---|
{"error":"not logged in"} | No authenticated tenant context is available. Invalid signed credentials can be rejected by the dispatcher before the handler runs. |
{"error":"missing or invalid parameter: ids"} | IDs are absent, not a native array, or contain nonpositive/nonscalar/nondecimal members. |
{"error":"missing or invalid parameter: date"} | Date is absent, not a strict valid calendar date, or before year 2013. |
{"error":"No permission to edit"} | The job-edit restriction applies and the user is not a client administrator. |
{"error":"Could not read jobs. Please retry."} | The active-job query failed. |
{"error":"Unable to save meeting time","failedId":1088,"updatedIds":[1042]} | A nested save failed. Other nested messages can appear in error; successfully written earlier IDs remain committed. |
{"error":"Could not read job. Please retry.","failedId":1088,"updatedIds":[1042]} | A selected job could not be read before its nested edit. |
{"error":"Unable to complete meeting time update; inspect the job before retrying","failedId":1088,"updatedIds":[1042]} | The nested setter threw; the failed job may already have been written before the exception. |
Legacy application errors can use HTTP 200. Inspect error, failedId and updatedIds before retrying; ok does not confirm mail delivery or every unchecked follow-up.
Behaviour and edge cases
- Converts each stored start epoch to tenant-local time, replaces only its calendar-date part and skips a matching date. This is not an N-day offset or UTC-midnight operation.
- Active jobs are fetched with IN, without pagination, in ascending physical job-ID order. Duplicate IDs collapse through that query.
- Calls Job_setMeetingTime with norecur=1, suppressing recurrence bumping. The nested edit permission guard still applies (with its client-admin exception). The wrapper stops and reports the nested error with failedId and updatedIds.
- Successful batches return string ok='1'. There is no schedule-conflict check or all-batch rollback. The preloaded nested-job context is restored/cleared even on failure; exceptions are reported as uncertain completion requiring read-back.
Side effects
- Successful nested time changes update scheduled time/epoch, original-time metadata and edit markers, and for incomplete jobs recompute estimated completion using work-day-start/end and week-days-off.
- The nested time setter records history, mirrors outsourced schedule/completion metadata, refreshes customer details, updates configured before-start/before-finish notifications and can send a date-change email. The nested setter does not surface every mail/mirror failure, so successful primary scheduling does not prove notification delivery or remote persistence.
- If sync-due-date-to-job-time=1, the nested time setter also invokes the single-job due-date path, with its reminder/mirror effects. Re-read dates and due dates before retrying.
See it in Fieldmotion
CRM1
In CRM1 Jobs list select several rows, open the bulk-edit menu and choose Change Job date. jobsMultiEdit.js calls Jobs_setMeetingDate; filter Network for that route.
CRM2
In CRM2 Jobs list select several rows, open the bulk-edit menu and choose Change Job date. lib/jobsMultiEdit.js calls Jobs_setMeetingDate; filter Network for that route.
Related endpoints
Job_isScheduleOverlapchecks a user’s schedule before a rescheduling decision.Jobs_setDueDatechanges due dates without rescheduling the job.Jobs_getSomereads selected job records before editing and verifies the stored result afterward.