Fieldmotion API Getting started

Programme Contracts

Read current grading sets

POST /a/ContractProgramme_grades

Read the latest grade choices for configuring future quality inspections.

When to use this endpoint

Use before assigning a grading_set_id through ContractProgramme_saveConfig or editing a set with ContractProgramme_saveGrades. Historical inspection evidence must use its stored snapshot rather than this current catalogue.

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.contractProgrammeQI.

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

This endpoint has no operation-specific parameters.

Example request

$result = FM_api('ContractProgramme_grades', [
	'data' => json_encode([
	]),
]);

Example response

[
  {
    "id": 1,
    "deleted": 0,
    "ddate": 0,
    "cdate": 1792490400,
    "last_edited": 1792490400,
    "name": "Traffic lights",
    "active": 1,
    "revision": 1,
    "grades": [
      {
        "id": "green",
        "label": "Green",
        "code": "G",
        "colour": "#00aa00",
        "category": "to"
      },
      {
        "id": "red",
        "label": "Red",
        "code": "R",
        "colour": "#ff0000",
        "category": "below"
      }
    ]
  }
]

Example from the disposable regression fixture. Database-derived numeric fields can be numbers or strings depending on the database driver; explicitly cast IDs/counts remain integers.

An empty catalogue returns []; there is no ok/data wrapper.

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.

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

Behaviour and edge cases

  • Returns a bare array, without an ok wrapper. Each entry combines the current grading-set row (id/name/active/revision/timestamps/deletion fields) with decoded grades.
  • Includes inactive, non-deleted sets, ordered by set name, with no pagination/filtering. A missing matching version is omitted by the inner join.
  • Grades contain id, label, code, colour and category (above/to/below). Existing inspection Jobs retain their creation-time version.

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

No direct grades request was found in CRM2. Contract overview receives an embedded grades array; the Grading Sets table uses ContractProgramme_getDataTable(resource=grading_sets). Filter for those requests instead.

Related endpoints