Jobs: field and bulk edits
Change one job’s due date
/a/Job_setDueDate
Replace one job’s due date and reschedule its overdue notifications.
When to use this endpoint
Replace one job’s due date and reschedule its overdue notifications.
Read the target job 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. The request uses the authenticated account’s job IDs, not mobile app IDs.
The legacy userdata.permissions bit 128 blocks editing with No permission to edit; this handler does not exempt client administrators from that bit. It does not add an assignee/department scope.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | Integer string | Yes | Physical job ID in the authenticated account, converted with intval; must be positive. |
value | Date string | Yes | Trimmed date text. Send YYYY-MM-DD; the validation only searches for a YYYY-MM-DD substring, not a full valid calendar date. Blank cannot clear the field. The error names due_date, but the request key is value. |
Example request
$result = FM_api('Job_setDueDate', ['id'=>'1042', 'value'=>'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: id"} | id is absent or converts to a nonpositive integer. |
{"error":"No permission to edit"} | The legacy edit restriction bit is set. |
{"error":"missing or invalid parameter: due_date"} | value lacks the required date-shaped substring. |
{"error":"job does not exist"} | The active job lookup fails or has no row. |
{"ok":1,"warning":"value already set"} | The saved due-date text already matches. |
{"error":"Unable to save job"} | The primary database write failed. History and dependent effects are not performed for that failed save. |
{"ok":1,"warning":"Job saved, but the outsourced copy could not be updated"} | The local save committed but an outsourced read/write failed. Do not repeat the local mutation blindly. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- Requires an active job and returns early if the stored due_date exactly equals the trimmed value.
- Stores the supplied text without updating due_date_e. Validation is weaker than Jobs_setDueDate: invalid calendar dates or extra surrounding text can reach the database.
- No schedule, recurrence, completion or user-assignment change is made.
- The primary UPDATE is checked before history and dependent effects. There is no transaction combining this field write with later cross-object effects; inspect committed-success warnings before retrying.
Side effects
- Writes last_edited and edited_uuid with the changed fields and invalidates the meetings cache.
- Records a job history entry. No mail is sent directly by this setter.
- Mirrors due_date and edit markers to the linked outsourced job in the routed destination account; a failed mirror returns committed success with a warning and has no deleted filter.
- Updates the overdue email queue and existing overdue SMS entries for 23:59:59 on the requested date, interpreted by PHP’s current timezone. Cron_update can create a missing future email reminder; it does not create missing SMS entries or new past-due email reminders. No immediate email is sent here.
See it in Fieldmotion
CRM1
Edit a job through the legacy edit dialog (Job_save invokes this setter internally), or change a recurring job’s due date in pageJobsRecurring.js. Filter for Job_setDueDate or inspect the parent save request.
CRM2
In the Recurring module change a generated job’s due date; moduleRecurring.js directly requests Job_setDueDate. Bulk due-date editing instead uses Jobs_setDueDate.
Related endpoints
Jobs_setDueDatesets a strict calendar date on selected jobs while preserving stored time suffixes.Jobs_getSomereads selected job records before editing and verifies the stored result afterward.