Fieldmotion API Getting started

Jobs: scheduling and lifecycle

Set one job's scheduled start

POST /a/Job_setMeetingTime

Save the job start and refresh the dependent schedule, completion estimate and customer snapshot.

When to use this endpoint

Use for a narrow reschedule without changing assignee or duration. For applying several scheduler rows, use Jobs_setUsersAndTimes.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. Legacy edit-restriction bit 128 is enforced; client administrators retain the existing admin exception.

The primary job selection is tenant-scoped. There is no automatic schedule-conflict or assignee-ownership check. Cross-tenant follow-ups use persisted outsourcing context.

Parameters

ParameterTypeRequiredDescription
idInteger stringYesPositive active job ID.
valueInteger seconds or datetime stringYesUnix seconds or tenant-local YYYY-MM-DD HH:mm:ss. Rejects relative/rolled-over dates. Positive epochs are capped at 7258118400 (2200); larger all-digit input gives Cannot set meeting time later than 2200. A separate legacy comparison rejects local strings earlier than 2013; this is not a consistent lower epoch boundary.
norecurPresence flagNoAny supplied value suppresses bumping the job's recurrence to the top, even 0. Other rescheduling effects still run.

Example request

$result = FM_api('Job_setMeetingTime', [
	'id' => '1042',
	'value' => '2026-10-13 10:00:00',
]);

Example response

{"ok":1,"meeting_time_e":1791882000}

The example epoch corresponds to the example local time in Europe/Dublin. Other tenant timezones produce different seconds. Same-time replies also include warning="value already set" and may retain a database-string epoch.

Errors and unusual responses

ResponseCondition
{"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"}Nonpositive/missing ID.
{"error":"missing or invalid parameter: value"}Invalid calendar/shape or zero.
{"error":"Cannot set meeting time earlier than 2013"}The separate legacy comparison rejects the supplied value.
{"error":"No permission to edit"}Bit 128 is set and the caller is not a client admin.
{"error":"Unable to save meeting time"}The primary DB write returned false.
{"error":"Cannot set meeting time later than 2200"}All-digit epoch exceeds the supported upper limit.

Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.

Behaviour and edge cases

  • An unchanged formatted local start returns before any follow-up. A changed start overwrites meta.original_meeting_time/original_meeting_time_e with the NEW values; these are not an immutable original booking.
  • For status 0, recalculates date_completed/date_completed_e and completion_date times-edited using hours, work-day-start, work-day-end and week-days-off. Other statuses retain their completion values.
  • Epoch formatting uses timezone, with missing fallback Europe/Dublin and blank UTC. Start text is mirrored to an outsourced counterpart; its incomplete completion estimate is calculated with the remote tenant timezone.
  • sync-due-date-to-job-time=1 calls Job_setDueDate with the new date. norecur only suppresses recurrence bumping. The endpoint has no batch mode.

Side effects

  • Advances last_edited/edited_uuid, writes job history, refreshes customer history/address and parent caches, mirrors outsourced timing, bumps recurrence unless suppressed.
  • Updates pending start-reminder email and SMS times and finish-reminder email time; does not create a missing past-due email reminder. Calls Job_emailChangeDate and optionally Job_setDueDate.

See it in Fieldmotion

CRM1

Drag a flexible job in Jobs Timeline or Assets Timeline; filter Job_setMeetingTime. Recurring-job copy also calls this to place the copy.

CRM2

Recurring-job copying in moduleRecurring.js calls this directly. Calendar/timeline moves normally wrap it through Job_moveDatetime; scheduler application wraps it through Jobs_setUsersAndTimes.

Related endpoints