Set a Contract’s starting Visit

When to use this endpoint

Set the first Visit before this Contract has been published in the run. Other Contracts retain common Visit numbering; this does not renumber the run.

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.

Only a client administrator may perform this operation, in addition to the permissions above.

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
`run_id`	Positive integer or digit string	Yes	Existing run; must be owned by the actor before its first Contract publication.
`contract_id`	Positive integer or digit string	Yes	Local, non-deleted Contract with an accessible Programme configuration.
`first_visit`	Positive integer or digit string	Yes	1 through the run’s saved visits limit.

Example request

$result = FM_api('ContractProgramme_setStart', [
	'data' => json_encode([
		'run_id' => 510,
		'contract_id' => 210,
		'first_visit' => 8,
	]),
]);

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":"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":"Starting Visit exceeds this run"}`	Requested number exceeds run.visits.
`{"error":"Starting Visit cannot change after publication"}`	Run already contains provenance for this Contract.
`{"error":"Run is private or unavailable"}`	Run missing/deleted or not available to this actor.

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

Behaviour and edge cases

Only a client administrator may save this override. Contract scope is still required.
A Contract already represented by any publication provenance in this run cannot change its starting Visit, including historical rows. A run owned by another actor cannot receive a new unpublished Contract override.
No active-run check is made here; publication separately requires an active run and active Programme. Saving the same first_visit still audits the action.

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.
Creates/updates the run/Contract starting row and audits starting_visit_set. Creates no Jobs.

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

Open the Programme Contract and choose Starting Visit, select a run and first Visit, then Save. Filter for ContractProgramme_setStart.

Related endpoints

ContractProgramme_newRun — Start the run before setting its override.
ContractProgramme_preview — Observe skipped Contract work before its first Visit.