Save a named checklist template

When to use this endpoint

Use the named catalogue from bootstrap.checklist_templates. Create a template, then select its ID through ContractProgramme_saveConfig. This is independent of the older Task-template editor.

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. 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
`id`	Positive ID or 0	No	Zero/omitted creates; existing IDs require matching revision.
`revision`	Integer-compatible	For updates	Current revision from the read; stale versions are rejected.
`name`	String	Yes	Trimmed, nonblank, max 128 characters; unique ignoring case across other named templates.
`sector`	String	No	Configured Sector or blank; max 64 characters. An existing unchanged retired name remains valid.
`questions`	Array	Yes	Ordered list of 1–100 strings or objects {id,text,options}. Text max 2000 characters, nonblank and unique ignoring case. ID is 1–64 letters/digits/underscore/hyphen; omission derives a 24-character text hash. IDs must be unique.
`questions[].options`	Array	No	1–30 distinct nonblank single-line string answers, max 256 characters each; defaults to ["Yes","No"]. Equality is case-sensitive.

Example request

$result = FM_api('ContractProgramme_saveChecklistTemplate', [
	'data' => json_encode([
		'name' => 'Site checks',
		'sector' => 'Parks',
		'questions' => [
			[
				'id' => 'gate',
				'text' => 'Is the gate secure?',
				'options' => [
					'Yes',
					'No',
				],
			],
		],
	]),
]);

Example response

{
  "ok": 1,
  "template": {
    "id": 1,
    "name": "Site checks",
    "sector": "Parks",
    "questions": [
      {
        "id": "gate",
        "text": "Is the gate secure?",
        "options": [
          "Yes",
          "No"
        ]
      }
    ],
    "revision": 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":"Checklist Template changed. Reload before saving."}`	Existing template revision is stale or ID unavailable.
`{"error":"Checklist questions must be unique"}`	Duplicate ID or case-insensitive text.
`{"error":"Checklist answers must be unique single-line values"}`	Duplicate or multiline answers.

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 submitted questions replace the complete ordered list. Preserve question IDs during renames/reordering; newly derived IDs change when their text changes.
Named selection is stored on each Contract. Zero selection disables; absence permits the older Contract/sector definition fallback.
Saved answers and completed Jobs retain their frozen question/answer choices. Unanswered incomplete Jobs selecting this template are refreshed; no Task objects are created.

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.
Replaces the named template catalogue, increments its revision, records checklist_template_saved and marks Programme history. Refreshes eligible Contract/Job checklist snapshots atomically.

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 Contracts Module Settings, create/edit a Checklist Template, change Questions/Answers and Save; filter for ContractProgramme_saveChecklistTemplate. The editor preserves question IDs.

Related endpoints

ContractProgramme_saveConfig — Assign or disable the named checklist.
ContractProgramme_saveSectors — Maintain optional Sector labels.
ContractProgramme_saveTasks — Maintain the separate legacy definition list.