Fieldmotion API Getting started

Digital Waste Tracking

Replace waste-tracking settings

POST /a/DigitalWasteTracking_settingsSave

Save the complete profile catalogue, account default and active operator notification recipients.

When to use this endpoint

Use after reading DigitalWasteTracking_settingsGet. Preserve every profile you still want available and set active explicitly; omitted profiles are archived rather than deleted.

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
settingsNative object or JSON object textYesExplicit versioned settings object (native or JSON), normally read from settingsGet. Omitted/empty settings is rejected. Include profiles, an active default and notification recipient state for a full replacement.
settings.profilesArray of objectsNo for legacy compatibility; normally yesComplete profile catalogue. Existing IDs remain stable; a blank ID requires new=1 to generate an ID. Include active=1 for active profiles.
settings.default_profile_idStringNoDefaults to the existing default, which must exist and be active in the final retained catalogue.
settings.notification_user_idsNative ID arrayNoDefaults empty in a versioned save. Values are integer-converted, deduplicated and nonzero-filtered; every retained ID must be an active tenant user.
settings.revisionStringRecommendedEcho settingsGet.revision. CRM2 sends it; stale full replacements fail before changing the catalogue. Legacy omission is accepted.

Example request

$result = FM_api('DigitalWasteTracking_settingsSave', [
	'settings'=>'{"version": 2, "default_profile_id": "aaaaaaaaaaaaaaaa", "notification_user_ids": [], "profiles": [{"id": "aaaaaaaaaaaaaaaa", "name": "North receiving site", "environment": "test", "receiving_site": {"receiver": {"siteName": "North receiving site", "authorisationNumber": "EPR/AB1234CD", "emailAddress": "waste@example.test", "phoneNumber": "", "regulatoryPositionStatements": []}, "address": {"fullAddress": "1 Synthetic Road", "postcode": "BT1 1AA"}}, "submission_mode": "manual", "active": 1, "api_code_masked": ""}]}',
]);

Example response

{
  "version": 2,
  "default_profile_id": "aaaaaaaaaaaaaaaa",
  "notification_user_ids": [],
  "profiles": [
    {
      "id": "aaaaaaaaaaaaaaaa",
      "name": "North receiving site",
      "environment": "test",
      "receiving_site": {
        "receiver": {
          "siteName": "North receiving site",
          "authorisationNumber": "EPR/AB1234CD",
          "emailAddress": "waste@example.test",
          "phoneNumber": "",
          "regulatoryPositionStatements": []
        },
        "address": {
          "fullAddress": "1 Synthetic Road",
          "postcode": "BT1 1AA"
        }
      },
      "submission_mode": "manual",
      "active": 1,
      "api_code_masked": "",
      "revision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    }
  ],
  "revision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

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":"invalid settings"}settings is invalid JSON or not an array/object.
{"error":"invalid or duplicate receiving profile ID"}A profile ID is duplicated or not legacy-default/16 hexadecimal characters.
{"error":"default receiving profile is invalid"}The chosen default does not exist in the final profile set.
{"error":"notification users must be active account users"}A nonzero recipient ID is absent/inactive.
{"error":"client administrator access required"}The identity is not a client administrator.
{"error":"explicit settings are required"}The supplied settings object is empty.
{"error":"choose an active default receiving profile"}The resulting default is archived.
{"error":"receiving profiles changed; reload before saving"}The replacement revision is stale.

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

Behaviour and edge cases

  • A new profile needs a nonblank name; existing profiles preserve the name when omitted. Submitted names are trimmed and may contain neither a colon nor a line break. Omitted environment/submission_mode preserve existing values, defaulting to test/manual on creation; submitted values select production/automatic only for those exact strings. Include active=1 to retain new-receipt availability: omitted active is false, not a partial-update default.
  • receiving_site contains receiver={siteName,authorisationNumber,emailAddress,phoneNumber,regulatoryPositionStatements} and address={fullAddress,postcode}. Unknown keys are discarded. An omitted/non-array receiving_site preserves the existing site; a supplied object replaces its normalized fields, so omitted nested contact/address fields become blank. Optional email must pass email validation; RPS entries must be positive whole numbers. Saving checks neither postcode nor permit format; preview/submission performs those validations.
  • api_code is the receiving organisation’s UUID, separate from software OAuth credentials. Blank/omitted input preserves the saved code; clear_api_code with a nonempty value clears it. The response always masks the code. Published dummy codes are rejected for production. Automatic mode requires a nonblank code, receiver site name/authorisation and full receipt address/postcode.
  • A profile with successful or ambiguous receipt history cannot change environment. Create a separate profile for the other environment. Archiving retains identity/history, blocks fresh receipts using that profile and does not remove previously submitted receipt updates.
  • The settings object itself is returned, not {ok:1}. Duplicate or malformed profile IDs fail. A well-formed previously unknown 16-character hexadecimal ID creates a new profile; only blank IDs require new=1 for server generation. Omitted old profiles are retained with active=0. There is no physical removal endpoint in this family.
  • Legacy top-level environment/api_code/receiving_site/submission_mode/clear_api_code input is still accepted when profiles is absent. It edits the first saved profile, preserves current notification recipients and archives omitted remaining profiles. Prefer the complete versioned contract.
  • Omitted old profiles are archived only if the final catalogue still has an active default. Empty settings and attempts to retain an archived default fail without changing saved data. Legacy single-profile controls are still accepted when they produce a valid active-default catalogue.
  • Full replacement is serialized and checked with history. A provided stale revision rejects concurrent edits; clients omitting revision retain legacy last-save behavior for a complete replacement.
  • Mutations use a checked tenant PDO transaction with the tenant-owner lock, preserving a caller’s savepoint. Writes and history commit together; a failed write/audit rolls back. A controlled save error asks callers to reload before retrying. No migration or deletion-lifecycle change is included.

Side effects

  • Writes settings, cache invalidation and a settings audit entry. Invalid/stale replacements roll back. No provider call or automatic Form-choice synchronization.

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 > notification recipients reads the full settings object, changes notification_user_ids and sends settings as JSON. Individual receiving-site dialogs use DigitalWasteTracking_profileSave.

Related endpoints