Fieldmotion API Getting started

Opportunity statuses and referrals

Hide a referral by setting its legacy deleted status

POST /a/Referral_delete

Hide a referral by setting its legacy deleted status.

When to use this endpoint

Hide a referral by setting its legacy deleted status.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. Referrals are global platform rows, not rows in a tenant-prefixed table; the scope and additional account checks described below are therefore significant.

Requires authenticated tenant context and scopes both the locked read and final global update to parent_id=current account. A foreign ID is rejected; the caller need not be the creating user.

Parameters

ParameterTypeRequiredDescription
idPositive integer stringYesOne global referral ID owned by the current account. Missing/zero returns the legacy no referral ID error; other malformed/nonpositive IDs are rejected.

Example request

$result = FM_api('Referral_delete', ['id' => '1042']);

Example response

{"ok":1}

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":"no referral ID"}ID absent or converts to zero.
{"error":"referral does not exist"}ID is absent or foreign.
{"error":"Could not record deletion audit."}Tenant deletion-audit write fails; the global status update is rolled back.
{"error":"referral write failed"}A global insert/update fails; its global transaction rolls back.
{"error":"referral read failed"}A checked row read fails.
{"error":"referral transaction failed"}The global transaction cannot start or commit.
{"error":"referral operation failed"}Unexpected database/runtime failure.

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

Behaviour and edge cases

  • Retains the global row and sets status=7. Both tables exclude it; the owner’s mapped details read still returns it.
  • Unlike ordinary edits, an already-hidden owned row is accepted as an idempotent no-op. Nonexistent/foreign IDs no longer return success.
  • Changed hiding advances last_edited/edited_uuid, requests the referrals cache marker and records a tenant deletion audit. This retains the existing status-7 convention; no new deleted/ddate columns or restore API are introduced.
  • The global row and tenant audit can be on different database servers. An audit failure rolls back the global write, but a global commit failure after audit persistence can leave an audit-only entry. Do not infer restoration support from the audit alone.
  • No linked customer is removed, payment reversed or notification sent.

Side effects

  • Writes status=7 and server edit metadata in the global transaction; records the deletion snapshot in the authenticated tenant’s deletes log and requests cache markers. No email, generic field history or linked-customer mutation occurs.

See it in Fieldmotion

CRM1

CRM1 Settings → Refer another business (pageRefer.js) creates referrals with Referral_new and lists/deletes them with Referrals_getDT/Referral_delete. The separate Customers → Referrals operator screen (pageReferrals.js) offers conversion and status/signing controls. In Refer another business, use the row’s Delete confirmation to see this individual-ID request.

CRM2

CRM2 Settings → Refer another business (pageRefer.js) uses Referrals_getDataTable with Referral/Referrals widget prefixes, mapped detail/update helpers and individual Referral_delete calls. Its custom Create form still calls Referral_new, not Referral_createData. Select rows and choose Delete. The widget checks a client-side delete permission and loops individual IDs; that UI check is not enforced by the handler.

Related endpoints