Create or edit a receiving profile

When to use this endpoint

Use this for the CRM2 receiving-site dialog. Read the current profile first and submit its complete active/site details when editing; it is not a sparse patch.

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

Parameter	Type	Required	Description
`profile`	Native object or JSON object text	Yes in practice	Receiving profile fields described below. Omission becomes an empty object; validation then rejects a missing/default inactive profile rather than providing a special missing-parameter error.
`make_default`	Truthy/falsey value	No	Nonempty selects the saved profile as account default. String "0" is false; string "false" is nonempty and therefore true.
`profile.revision`	String	Recommended on edits	Echo the revision returned by the profile table/settings reader. CRM2 supplies it. A stale revision fails; omission retains legacy compatibility. New profiles need no previous revision.

Example request

$result = FM_api('DigitalWasteTracking_profileSave', [
	'profile'=>'{"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}',
	'make_default'=>'1',
]);

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

Response	Condition
`{"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 not found"}`	A nonblank profile ID is not already saved.
`{"error":"choose another account default before archiving this receiving site"}`	The dialog attempts to archive the default/make-default profile.
`{"error":"invalid Digital Waste Tracking API code"}`	A nonblank code is not a UUID.
`{"error":"this profile has receipt history; create a separate profile for the other environment"}`	The requested environment differs from a profile with receipt mappings.
`{"error":"client administrator access required"}`	The identity is not a client administrator.
`{"error":"receiving profiles changed; reload before saving"}`	The supplied revision is stale.
`{"error":"choose an active default receiving profile"}`	The resulting catalogue would have an archived default.

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

Behaviour and edge cases

Omit/blank profile.id to create a random 16-character lowercase hexadecimal identity. Existing IDs are lowercased/trimmed and must identify a saved profile. legacy-default is the compatibility identity. IDs are durable references; rename the name field rather than changing an ID.
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.
This dialog endpoint refuses to archive the current default or a profile being made default. Read-modify-write replaces the stored settings without an optimistic revision or an enclosing transaction. The underlying settings write acknowledgement is not checked; reload before treating success as durable.
The dialog refuses to archive the current default or a profile being made default. Both dialog and full settings saves now require an active default. Profile changes serialize with the tenant-owner lock, read the latest catalogue and check revision when provided, preserving concurrent profile additions. Legacy clients omitting revision retain last-save semantics for values they explicitly replace.
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

Checks and persists the catalogue and a settings audit entry atomically; invalidates its settings cache. Audit contains operation context, not API codes. Form-choice synchronization and provider connectivity remain separate operations.

See it in Fieldmotion

CRM1

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

CRM2

Open Settings > Digital Waste Tracking > receiving sites and choose Create or Edit. The dialog sends profile as JSON and numeric make_default; Archive and Make default actions use the same endpoint.

Related endpoints

DigitalWasteTracking_profiles — Obtain the editable masked profile object.
DigitalWasteTracking_settingsSave — Replace account-wide settings and notification recipients.
DigitalWasteTracking_profileChoicesSync — Refresh a Form’s saved receiving-site choices after renames.