Fieldmotion API Getting started

Digital Waste Tracking

Read provider-test evidence

POST /a/DigitalWasteTracking_patStatus

Read the fixed 14-scenario acceptance-test evidence set, either directly or as a paginated operator table.

When to use this endpoint

Use to inspect saved evidence before preparing a synthetic completed test Job. Unrecorded scenarios remain visible; this endpoint does not run them.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session; session dispatch applies CSRF checks. The authenticated tenant must have features2.ukDigitalWasteManagement=1. The feature is read from the account record, not trusted from request input.

Requires client-administrator access. A page Edit permission or wildcard role alone does not replace the client-admin check.

Parameters

ParameterTypeRequiredDescription
isTableTruthy valueNoDefault false returns {ok,scenarios,non_pii_required}. Nonempty enables the standard array-backed table.
start, length, drawInteger-compatibleNoOffset (default 0), page size (default 10, clamped 1–500) and echoed draw (default 0). This is not page/limit pagination.
searchValue, searchFieldStringsNoCase-insensitive substring search. searchField defaults to All; unsupported field names normally match no nonblank search.
orderBy, orderDescStringsNoSort by a returned property; only a case-insensitive desc value reverses the default ascending natural string comparison.
scenario, job_id, job_ref, outcome, tracking_id, expected_category, idScalar/native arrayNo in table modeExact filters. Unrecorded outcome is the literal Not recorded. scenario and id are the scenario code.

Example request

$result = FM_api('DigitalWasteTracking_patStatus', []);

Example response

{
  "ok": 1,
  "scenarios": {
    "R01": [],
    "R02": [],
    "R03": [],
    "R04": [],
    "R05": [],
    "R07": [],
    "C01": [],
    "C02": [],
    "B01": [],
    "P01": [],
    "H01": [],
    "H02": [],
    "H03": [],
    "X01": []
  },
  "non_pii_required": 1
}

The example shows all scenarios unrecorded; PHP empty evidence values may be [] on the wire. The API returns stored snapshots without provider revalidation.

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":"UK Digital Waste Tracking is not enabled for this account"}The account feature is disabled.
{"error":"PAT evidence is not enabled for this account"}The service allowlist check does not return allowed=true, including a failed availability lookup.
{"error":"client administrator access required"}The identity is not a client administrator.

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

Behaviour and edge cases

  • Requires both client administrator and the signed service’s PAT account allowlist (DWT_PAT_CLIENT_IDS); the tenant feature alone is insufficient. A PAT availability lookup is made on every call. These are synthetic provider-acceptance tests, not an automatic declaration of approval.
  • Scenario IDs are fixed: R01, R02, R03, R04, R05, R07, C01, C02, B01, P01, H01, H02, H03, X01. Stored evidence is read from the versioned PAT settings value. Unknown scenarios are omitted; each supported scenario defaults to an empty array when no evidence is stored. An unrecorded entry can serialize as [] rather than {}.
  • Plain mode has no pagination. Table mode returns draw/recordsTotal/recordsFiltered/data; each row includes id,scenario,job_id,job_ref,outcome,tracking_id,recorded_at,expected_category,evidence. Missing Job ID is 0, text is blank, outcome is Not recorded. Recorded times in the table are UTC YYYY-MM-DD HH:MM:SS; raw evidence recorded_at remains Unix seconds.
  • For array-backed tables, start defaults to 0 and is clamped to at least 0; length defaults to 10 and is clamped to 1–500 (length=-1 means 1, not all). draw is integer-converted. searchValue is HTML-entity-decoded, trimmed and matched as a case-insensitive substring; searchField=All searches the listed searchable columns. Exact field filters accept one value or a native array of values, combine with AND, and ignore blank/empty lists. orderBy names an actual row property; orderDesc=desc reverses a natural, case-insensitive string comparison. Unknown sort names preserve source order. Counts are before and after these in-memory filters.
  • Searchable columns are scenario, job_id, job_ref, outcome, tracking_id and expected_category; id is additionally an exact filter. The fixed scenario order is retained unless orderBy selects a real row property.

See it in Fieldmotion

CRM1

No direct CRM1 caller was found in the production JavaScript source. The operator workflow is implemented in CRM2.

CRM2

Open Digital Waste Tracking > Provider testing. The widget calls DigitalWasteTracking_patStatus with isTable pagination/filter controls. The CRM2 header also requests the plain state to decide whether to show this administrator-only screen.

Related endpoints