Fieldmotion API Getting started

Digital Waste Tracking

Preview a waste receipt

POST /a/DigitalWasteTracking_preview

Build a sanitized receipt summary and validation guidance from one saved Job before submission.

When to use this endpoint

Preview after saving Job answers and correcting Form/profile mappings. A valid preview alone does not submit, queue or prove that a Job has an eligible completion status.

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').

Job reads and mutations enforce the authenticated tenant, active Job, TeamAccess department/assignment scope and the legacy department-based customer boundary. Collections filter before counts/pagination; explicit Job and cancellation requests check access before a service call or queue mutation.

Parameters

ParameterTypeRequiredDescription
job_idInteger-compatibleYesNonzero existing non-deleted tenant Job. Unlike submit, preview does not require Complete/Processed status.

Example request

$result = FM_api('DigitalWasteTracking_preview', [
	'job_id'=>'1042',
]);

Example response

{
  "ok": 1,
  "preview": {
    "date_time_received": "2026-10-20T12:00:00+01:00",
    "carrier": {
      "organisation": "Synthetic Carrier",
      "registration_provided": false,
      "means_of_transport": "Sea",
      "vehicle_registration": ""
    },
    "broker_or_dealer": "",
    "receiving_site": "North receiving site",
    "authorisation_number": "EPR/AB1234CD",
    "hazardous_consignment_code_provided": false,
    "waste_items": [
      {
        "ewc_codes": [
          "170904"
        ],
        "description": "Synthetic mixed waste",
        "physical_form": "Solid",
        "containers": {
          "type": "SKI",
          "count": 1
        },
        "weight": {
          "metric": "Kilograms",
          "amount": 10,
          "isEstimate": false
        },
        "contains_pops": false,
        "contains_hazardous": false,
        "disposal_or_recovery_codes": [
          "R1"
        ]
      }
    ]
  },
  "request_hash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "profile_id": "aaaaaaaaaaaaaaaa",
  "profile_name": "North receiving site",
  "reference_state": {
    "fresh": true,
    "stale": false,
    "fetched_at": 1792497600
  },
  "categories": [],
  "guidance": [],
  "completed": true
}

The example shows a structurally valid synthetic receipt and a fresh catalogue. A preview with errors still has ok=1 but includes categories/guidance.

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":"job_not_found"}The service cannot find a non-deleted Job.
{"error":"form_not_configured"}The Job Form does not enable waste tracking.
{"error":"receiving_profile_unavailable"}The resolved receiving profile is unavailable.
{"error":"permission denied"}The required page action is absent; the shared permission helper retains its legacy roleless fallback.
{"error":"job not found or outside your record scope"}The explicit Job or queue’s Job is missing, deleted or hidden by record scope. Bulk queueing reports this per Job.
{"error":"reference_service_unavailable"}Reference data could not be acquired and no usable stale cache exists. OAuth/storage setup errors can also be returned directly.

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.
  • Builds from saved Job main/table answers using stable mapped field IDs and their current names. It does not accept a caller-supplied provider payload. Receiving profile precedence is Job override, Form selection, account default; a recorded submission/ambiguity pins the historical profile and can include an archived profile.
  • Receipt time uses the mapped answer or falls back to date_completed. Naive dates use the tenant timezone setting, default Europe/London, and serialize with an explicit offset. Booleans recognize 1/yes/true/on; code lists split on commas/newlines; numberOfContainers must be whole, and weight amount must be finite and positive.
  • Validates required receiver/address, receipt time, carrier organisation/transport/registration-or-reason and at least one waste item. Road transport requires vehicle registration. EWC lists contain 1–5 entries; physicalForm is Gas/Liquid/Solid/Powder/Sludge/Mixed; weight units are Grams/Kilograms/Tonnes. POP/hazard flags require their conditional details, and hazardous waste requires a consignment code or allowed missing-code reason.
  • With fresh references, validates all five catalogue families and checks EWC hazardous classification against containsHazardous. With stale/unavailable references, local reference membership checks are skipped; reference_state must be examined separately from categories.
  • The preview summary includes carrier organisation/vehicle, receiver site/authorisation and waste descriptions, but excludes raw apiCode, contact addresses and the full provider payload. It remains business data, not an anonymized record. categories are machine-readable local errors; guidance resolves their paths to Form labels where possible.
  • A successful summary has ok=1 plus completed, categories and guidance. completed=false explicitly identifies a draft/ineligible Job without forbidding preview. Nonempty categories indicate invalid receipt content; ok does not mean validation passed.
  • Reference acquisition errors are returned explicitly, with profile_id/completed context, rather than disguised as an ok summary with empty categories. A usable stale cache remains available with freshness flags, as documented by references.
  • request_hash is SHA-256 over the built provider payload, profile ID and environment. Pass it as expected_hash when submitting the displayed receipt. CRM2 confirmation/update callers do so; changes after confirmation fail before the provider write.

Side effects

  • May request OAuth/reference data and update private caches. It does not send a receipt, change the Job, enqueue work or persist a receipt mapping.

See it in Fieldmotion

CRM1

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

CRM2

On a configured Job Form select the receipt action; CRM2 loads status then DigitalWasteTracking_preview and displays its summary/guidance. Operations > Preview/Update receipt uses the same call.

Related endpoints