Fieldmotion API Getting started

Digital Waste Tracking

Test live waste-tracking connectivity

POST /a/DigitalWasteTracking_health

Force fresh OAuth authentication and all five reference-catalogue reads for one receiving environment.

When to use this endpoint

Run after server credentials or the receiving environment changes. A successful software connection is separate from organisation API-code, permit, payment and external approval checks.

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
profile_idStringNoTrimmed profile ID; blank/omitted uses account default. It must be active. A saved but archived profile is unavailable.

Example request

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

Example response

{
  "ok": 1,
  "profile_id": "aaaaaaaaaaaaaaaa",
  "environment": "test",
  "reference_fetched_at": 1792497600
}

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 chosen/default profile is absent or archived.
{"error":"provider_credentials_unavailable"}Required software credentials are missing/placeholders.
{"error":"reference_service_unavailable"}A reference request failed or returned an empty catalogue.
{"error":"oauth_failed"}Fresh software authentication failed.
{"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

  • 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.
  • Forces a new token request and all five nonempty reference catalogues even when cached data is still fresh. A failure is returned directly; this forced path never falls back to stale references. Success includes reference_fetched_at as Unix seconds.
  • The connection uses environment-specific server software credentials. It does not send the receiving organisation API code or a receipt, and therefore does not verify that code, site authorisation or government approval. No pagination or Job selection applies.

Side effects

  • Makes OAuth/reference HTTP requests and refreshes private token/reference caches. Does not create receipt mappings.

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 > receiving site > Test connection calls DigitalWasteTracking_health with that row’s id. The success message lists what this check does and does not verify.

Related endpoints