Programme Contracts
Start a new Programme run
/a/ContractProgramme_newRun
Start a fresh Visit sequence while reusing the actor’s saved routes.
When to use this endpoint
Start a run before preview/publication, or after exhausting the previous run’s Visit limit. It does not immediately create or archive Jobs.
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.contractProgrammePlanning. 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.
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 |
|---|---|---|---|
programme_id | Positive integer or digit string | Yes | Local Programme definition ID. It must be active for writes that start runs or save routes, and owned by you or marked as a default. |
Example request
$result = FM_api('ContractProgramme_newRun', [
'data' => json_encode([
'programme_id' => 410,
]),
]);Example response
{
"ok": 1,
"id": 510
}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":"Programme is inactive"} | Definition is inactive. |
{"error":"Programme is private or unavailable"} | Definition is deleted, missing or private. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- The definition must be active and owned by you or marked default. Each actor gets their own run; other actors’ runs are not deactivated.
- Copies definition name/visits into the run. run_number is one greater than the maximum across all runs for the definition, while Visit publication advances separately for each user.
- Deactivates your previous runs for this Programme. Repeating the call creates another run: there is no request_key replay protection.
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.
- Writes a new run, deactivates previous actor-owned runs for this Programme and audits run_started.
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 Programme Settings select Start New Run. Filter for ContractProgramme_newRun. The client sends only programme_id.
Related endpoints
ContractProgramme_saveProgramme— Set the definition Visit count before starting.ContractProgramme_setStart— Choose a Contract’s first Visit.ContractProgramme_preview— Review the next one or two Visits.