Fieldmotion API Getting started

Digital Waste Tracking

Run and record a provider-test scenario

POST /a/DigitalWasteTracking_patRecord

Send a manually prepared synthetic receipt through one server-verified acceptance scenario and save the actual submission evidence.

When to use this endpoint

Prepare the required completed test Job yourself, choose a test-environment profile and confirm synthetic non-personal data. This call can send a real provider test request; it is not merely a local annotation.

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
scenarioString enumYesOne of R01, R02, R03, R04, R05, R07, C01, C02, B01, P01, H01, H02, H03, X01. Case-sensitive after trimming.
job_idInteger-compatibleYesExisting non-deleted Job in Complete (1) or Processed (2). Its effective profile must be test.
confirm_non_piiTruthy valueYesEvery scenario requires a nonempty explicit confirmation that Job data is synthetic/non-personal. This is an attestation, not an anonymization function.
allow_updateTruthy valueNoAn already submitted positive scenario needs an explicit update. Invalid C01/H02 scenarios require a fresh Job and cannot reuse accepted evidence.
expected_category, confirm_invalid_testLegacy UI controlsNoCRM2 sends these, but expected_category is overwritten by the server’s fixed scenario rule and confirm_invalid_test is not consumed. They cannot choose an arbitrary expected failure.

Example request

$result = FM_api('DigitalWasteTracking_patRecord', [
	'scenario'=>'R01',
	'job_id'=>'1042',
	'confirm_non_pii'=>'1',
	'allow_update'=>'0',
]);

Example response

{
  "ok": 1,
  "evidence": {
    "job_id": 1042,
    "job_ref": "DWT-1042",
    "recorded_at": 1792497600,
    "outcome": "accepted",
    "tracking_id": "WT-SYNTHETIC-1042",
    "expected_category": "",
    "provider_categories": [],
    "recorded_by": 7,
    "request_hash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "profile_id": "aaaaaaaaaaaaaaaa",
    "environment": "test"
  }
}

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 PAT scenario"}The scenario is not in the fixed list.
{"error":"confirm that this test job contains only synthetic non-personal data"}Confirmation is absent/falsey.
{"error":"PAT evidence must use a completed test job"}The Job is missing/deleted or not Complete/Processed.
{"error":"PAT evidence may only use a test-environment profile"}The resolved profile is not test.
{"error":"pat_scenario_payload_mismatch"}The saved receipt does not match the required scenario.
{"error":"pat_requires_explicit_update_or_new_job"}An existing receipt cannot be reused under this scenario/update choice.
{"error":"client administrator access required"}The identity is not a client administrator.
{"error":"PAT evidence is not enabled for this account"}The service allowlist check is false/unavailable.

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

Behaviour and edge cases

  • Requires both client administrator and the signed service’s PAT account allowlist (DWT_PAT_CLIENT_IDS); the tenant feature alone is insufficient. A PAT availability lookup is made on every call. These are synthetic provider-acceptance tests, not an automatic declaration of approval.
  • The service verifies scenario content in the actual receipt: R01 exactly one item with disposal/recovery codes, R02 multiple items, R03 road/vehicle, R04 omitted disposal codes with the required provider warning, R05 multiple disposal codes, R07 multiple EWC codes, C01 missing carrier registration/reason, C02 valid missing-registration reason, B01 broker organisation/registration, P01 multiple POP components, H01 multiple hazardous components, H02 missing hazardous consignment/reason, H03 a hazardous missing-consignment reason, and X01 both POPs and hazardous waste.
  • C01 expects carrier.registration_reason_required and H02 reasonForNoConsignmentCode_required. Local validation must contain exactly the expected category before the service intentionally sends the invalid payload. The provider must reject with HTTP 400 and an allowed matching field/category; other rejections are not accepted evidence.
  • Positive scenarios need pat_outcome=accepted. R04 additionally requires DisposalOrRecoveryCodesNotProvided in provider warnings. Merely reusing an already-submitted response does not establish new evidence; the returned submitted request_hash/profile_id are stored.
  • Replaces only this scenario’s evidence in the PAT settings value, recording Job/ref, actor, Unix time, outcome, tracking ID, server expected category, provider categories, actual submitted hash/profile and environment=test. A positive provider result can precede an evidence-persistence failure; inspect status before rerunning.
  • After the provider outcome, the latest PAT state is read under a checked tenant transaction and merged by scenario, preserving concurrent evidence for other scenarios. Evidence and history commit together.
  • If the provider test completed but evidence/history cannot be saved, the response is {ok:1,submitted:1,evidence_saved:0,tracking_id:...,warning:...}; it is not a replayable provider failure. CRM2 displays the warning and reloads the evidence state. Confirm the retained receipt before another run.

Side effects

  • May send a test receipt and retain service mappings/outcomes. Then atomically merges the selected actual evidence and history. A local follow-up failure explicitly warns that the provider request already completed. It does not create/anonymize Jobs.

See it in Fieldmotion

CRM1

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

CRM2

Provider testing > scenario > Run and record collects completed test job ID, explicit synthetic-data confirmation and optional update consent. The read-only invalid-category control mirrors the server rule; it does not authorize arbitrary scenarios.

Related endpoints