Fieldmotion API Getting started

Digital Waste Tracking

Read waste reference catalogues

POST /a/DigitalWasteTracking_references

Load the normalized codes used by receipt validation and autocomplete for a receiving environment.

When to use this endpoint

Use when editing a configured waste receipt. It returns code catalogues, not profile/site details or a receipt preview.

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 Jobs View through Core_requirePermission('view', 'pageJobs').

The selected receiving profile belongs to the authenticated tenant. Reference catalogues are shared by receiving environment/base URL; no Job record is read by this operation.

Parameters

ParameterTypeRequiredDescription
profile_idStringNoActive receiving-profile ID; blank selects the account default. Profiles in the same environment/base URL share the service reference cache.

Example request

$result = FM_api('DigitalWasteTracking_references', [
	'profile_id'=>'aaaaaaaaaaaaaaaa',
]);

Example response

{
  "ok": 1,
  "fresh": 1,
  "fetched_at": 1792497600,
  "catalogs": {
    "ewc": [
      {
        "code": "170904",
        "is_hazardous": false,
        "is_not_recovery_to_final_product": false
      }
    ],
    "hazardous": [
      {
        "code": "HP1"
      }
    ],
    "disposal_or_recovery": [
      {
        "code": "R1"
      }
    ],
    "container": [
      {
        "code": "SKI"
      }
    ],
    "pop": [
      {
        "code": "PCB"
      }
    ]
  },
  "profile_id": "aaaaaaaaaaaaaaaa"
}

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":"receiving_profile_unavailable"}The selected/default profile is absent or archived.
{"error":"private_storage_unavailable"}The service cannot use its private directory.
{"error":"reference_service_unavailable"}No usable fresh/stale reference result is available.
{"error":"permission denied"}The required page action is absent; the shared permission helper retains its legacy roleless fallback.

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 CRM forwards this operation to its signed on-complete service with the tenant and actor installed server-side. A caller cannot choose another tenant. Missing service configuration returns Digital Waste Tracking service is not configured; a non-JSON service reply returns Digital Waste Tracking service returned an invalid response.
  • Returns ewc, hazardous, disposal_or_recovery, container and pop arrays under catalogs. String catalogue entries normalize to {code}; object entries also expose boolean is_hazardous and is_not_recovery_to_final_product. Descriptive provider fields are not retained.
  • A reference cache younger than 21,600 seconds (six hours) returns fresh=1. After refresh failure, an existing cache up to 604,800 seconds old (seven days) can return ok=1, fresh=0, stale=1 and warning=reference_data_stale. Older/missing caches return an error, fresh=0 and empty catalogs.
  • Fresh catalogue values validate waste codes and EWC hazardous classification. Stale values remain available for assistance, but the server skips local catalogue membership validation when fresh is false. Structural receipt validation still applies.
  • The CRM merges profile_id into the service response, including an error response after profile resolution. Cached success does not prove current OAuth credentials work; health forces fresh reads.
  • The mobile app has a separate authenticated m/www intermediary for this same-named operation. It feature-gates the mobile session and calls the signed service; the CRM Jobs View check described here belongs to the CRM route.

Side effects

  • May perform OAuth and five provider reference reads and write private caches. No receipt submission, queue or Job mutation.

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 a configured receipt Job Form and edit waste fields. CRM2 requests DigitalWasteTracking_references for code suggestions. The mobile app calls its intermediary through digitalWasteTrackingReferences and caches each profile’s response locally for offline suggestions.

Related endpoints