Programme Contracts
Move live Programme work
/a/ContractProgramme_move
Change the date or user for live incomplete work while retaining its original schedule.
When to use this endpoint
Use Job Progress Switch Day rather than ordinary Job assignment/date APIs, which protect Programme provenance. Choose one Job or all incomplete work in its current day group.
Send operation fields inside one JSON-encoded data object. When data is present it replaces top-level operation fields; otherwise the handler accepts the top-level request. String data is limited to 2 MB. Reserved transport/internal keys are removed. Malformed or non-array JSON becomes an empty input, so validate JSON before sending.
Authentication and permissions
Authenticate with a signed API key or logged-in CRM session; session requests follow dispatcher CSRF checks. API-key requests use the key owner’s identity and permissions.
Requires the Contracts entitlement (features & 64), features2.contractProgrammes and Contracts View. Also requires features2.contractProgrammePublishing. Requires Contracts Edit.
All storage belongs to the authenticated tenant. Contract operations follow the actor’s recursive HR manager/team scope, or the configured TeamAccess Contract/Department policy. Client administrators have broad Contract scope; private Programme and route ownership still applies. Active assignees must be within the permitted team.
Non-administrators also need Jobs Edit; the legacy Job edit restriction (permissions bit 128) and TeamAccess field roles remove Edit.
The tenant must have the Programme storage upgrade (foundation 803; independent route ownership 804 before planning). Requests never create or repair tables. A missing/incompatible storage failure can return an initialization/storage error or Contracts operation failed. Check the saved state before retrying.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
job_id | Positive integer or digit string | Yes | Job with non-deleted, non-archived Programme provenance and is_complete=0. |
date | YYYY-MM-DD | Yes | New tenant-local calendar date; no Visit-boundary, weekend or holiday restriction. |
user_id | Positive integer or digit string | Yes | Active local assignee within your permitted team; use the workspace’s board user choices. |
whole_day | 0/1 or boolean | No | Defaults to 0. At 1, moves live incomplete Jobs sharing the selected provenance Visit/day/current date/old user. |
Example request
$result = FM_api('ContractProgramme_move', [
'data' => json_encode([
'job_id' => 810,
'date' => '2026-11-10',
'user_id' => 104,
'whole_day' => 0,
]),
]);Example response
{
"ok": 1,
"moved": 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":"Programme Contracts is not enabled"} | Workspace flag or Contracts entitlement is disabled. |
{"error":"Permission denied"} | Contracts View or the required action permission is unavailable. |
{"error":"This Contracts capability is not enabled"} | The operation’s additional feature flag is disabled. |
{"error":"Only live incomplete work can be moved"} | Job missing/deleted, archived or no longer incomplete. |
{"error":"User is outside your team"} | Target assignee is outside the permitted team. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- Keeps each Job’s tenant-local hour/minute while replacing its date and assignee. Original provenance date, day number, position, reusable route and original Job metadata remain intact.
- whole_day moves only incomplete work in that specific current grouping, not all work on the calendar date; every Contract is checked before commit.
- No capacity or overlap validation is performed. Existing due_date shifts by the local calendar-day difference, preserving its relative deadline; unset dates remain unset. A stored due_date_e shifts by the same local calendar days when present. The incomplete Job’s estimated completion is recomputed from the new start and current hours, with date_completed, date_completed_e and completion_date.times-edited.timestamp kept consistent. Actual completion evidence in other metadata entries is preserved. An assignment-only move on the same date retains the existing end estimate, including separately edited estimates.
- The same date/user still writes history and sync timestamps. There is no request_key replay acknowledgement; inspect saved state after an uncertain response.
Side effects
- The service serializes writes on the tenant owner in a transaction. Validation, persistence, audit or TeamAccess outstanding-Job access failures roll back that transaction. Successful changed writes refresh linked Contract/Customer sync timestamps and shared mobile update markers, then invalidate CRM caches after success. These operations do not create schema or enable account features.
- Updates live meeting date/user, relative deadline, completion estimate and provenance scheduled_date/user; appends one contract_programme_changes row per Job and live_work_moved audit. Retains previous_users for mobile reconciliation. Matching older linked Programme Tasks follow assignment/date; no new Tasks or emails are created.
See it in Fieldmotion
CRM1
No direct caller was found in CRM1 source. This workflow is implemented by the opted-in CRM2 Programme Contracts workspace.
CRM2
In Job Progress choose Switch Day for a Job/day, edit Date/User and optionally Move Whole Day. Filter for ContractProgramme_move.
Related endpoints
ContractProgramme_publish— Create the live provenance first.ContractProgramme_addJob— Add work without changing the reusable route.