Fieldmotion API Getting started

Programme Contracts

Retire a Programme definition

POST /a/ContractProgramme_deleteProgramme

Hide a Programme definition while retaining published work and evidence.

When to use this endpoint

Use after deciding the definition is no longer needed. The UI asks the operator to type its name, but the API itself requires only the definition ID.

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.

Non-administrators also need Contracts Delete. The creator check remains separate.

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

ParameterTypeRequiredDescription
idPositive integer or digit stringYesExisting, non-deleted Programme definition; creator or administrator editing a default only.

Example request

$result = FM_api('ContractProgramme_deleteProgramme', [
	'data' => json_encode([
		'id' => 410,
	]),
]);

Example response

{
  "ok": 1
}

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":"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 private or unavailable"}Definition missing, deleted or private.
{"error":"Only the programme creator can change its definition"}Definition is readable but not writable by 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

  • Sets deleted=1, ddate and active=0 on the definition. It does not cascade to routes, runs, Visits, Jobs or evidence.
  • Another actor’s private definition remains unavailable even to an administrator. Repeating deletion returns unavailable rather than success.
  • Default-definition deletion is permitted server-side to client administrators; CRM2’s removal action is more restrictive and exposes creator-owned rows only.

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.
  • Appends the contract_programmes deletion-log record and programme_deleted audit. Published Jobs are neither archived nor deleted by this operation.

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 choose Delete, type the Programme name and confirm. Filter for ContractProgramme_deleteProgramme; the browser confirmation text is not sent as an API requirement.

Related endpoints