Fieldmotion API Getting started

Digital Waste Tracking

Check local waste-tracking readiness

POST /a/DigitalWasteTracking_readiness

Inspect software credentials, private storage, receiving-site gaps and active Form mappings without asserting government approval.

When to use this endpoint

Use for an administrator’s setup checklist. This check does not contact the provider; use health for fresh authentication and reference-data reads.

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

This endpoint has no operation-specific parameters.

Example request

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

Example response

{
  "ok": 1,
  "private_storage_writable": true,
  "profiles": [
    {
      "id": "aaaaaaaaaaaaaaaa",
      "name": "North receiving site",
      "environment": "test",
      "active": true,
      "credentials_configured": false,
      "missing": [
        "organisation_api_code"
      ],
      "payment_required": false,
      "service_charge_expires_at": 0
    }
  ],
  "mapped_forms": [],
  "active_notification_users": 0,
  "pat_allowed": false,
  "government_approval_verified": false,
  "guidance": "Connection checks validate software credentials and reference data only. Organisation API codes, site permits, service charges and production approval must be confirmed separately with Defra. Test submissions must contain synthetic data only."
}

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":"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

  • Returns all profiles, including archived ones. missing lists siteName, authorisationNumber, fullAddress, postcode and/or organisation_api_code when blank. credentials_configured checks presence/non-placeholder software OAuth values for that environment; it is not a live authentication result.
  • mapped_forms includes enabled configurations on non-archived Forms. Each entry has id, name, waste_table_mapped and missing_mappings. It requires resolvable carrier organisation/transport plus the ten core waste-item mappings; archived subforms do not satisfy these checks. It does not validate every conditional field required by a particular receipt.
  • active_notification_users counts configured active users, not every tenant user. payment_required and service_charge_expires_at come from the last saved provider result, not a fresh payment lookup. pat_allowed reflects the service account allowlist.
  • private_storage_writable invokes the private-directory helper, which may create/chmod the configured directory. Credential values, organisation API codes and raw payloads are not returned. government_approval_verified is always false.

Side effects

  • May create or enforce permissions on the service private cache directory. Reads configuration and cached payment status; does not submit or contact the provider.

See it in Fieldmotion

CRM1

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

CRM2

Settings > Digital Waste Tracking loads this setup banner on entry and after a profile/notification edit. Inspect DigitalWasteTracking_readiness; the UI explicitly separates software readiness from external approval.

Related endpoints