Fieldmotion API Getting started

Opportunity statuses and referrals

Edit one or several referrals owned by the authenticated account

POST /a/Referral_updateData

Edit one or several referrals owned by the authenticated account.

When to use this endpoint

Edit one or several referrals owned by the authenticated account.

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 login. Every selected non-status-7 row must belong to the authenticated account, not necessarily the creating user. All targets are locked before mutation. No client-admin flag grants ownership transfer or operator-workflow edits through this route.

Parameters

ParameterTypeRequiredDescription
id / idsPositive integer string or nonempty native arrayYesid takes precedence. Values are validated, deduplicated and sorted. All selected records must be visible and owned by this account.
companyName / contactName / phone / email / notesStringsNoOnly these contact-facing aliases are writable. Blank text is allowed on edit. A nonblank email must pass PHP email validation. Supplied values are stored without trimming.
parentID / userID / status / signedDate / numSigned / customerID / cDate / lastEdited / appID / editedUUID / referralSourceAnyForbiddenTrusted identity/workflow metadata cannot be edited here. Server timestamps/marker advance only on a changed contact edit. Internal staff use the dedicated operator routes.

Example request

$result = FM_api('Referral_updateData', ['id' => '1042', 'notes' => 'Demonstration requested.']);

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":"missing or invalid parameter: id"}Missing/invalid selector; empty lists report id/ids.
{"error":"referral does not exist"}Any ID is missing, foreign or status 7; no edit commits.
{"error":"read-only field: parentID"}A protected alias is supplied; the error names that alias.
{"error":"Invalid email address."}Nonblank email fails validation.
{"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

  • Only contact-facing mapped fields are mutable; unknown keys are ignored. A valid unchanged/unrecognized-only edit returns ok without advancing timestamps.
  • All targets are account-scoped, non-status-7 and locked. The entire batch of contact edits commits together; no earlier edits persist if a later checked write fails.
  • Changed rows receive current server last_edited and Referral_updateData|crm. Status-7 rows cannot be edited or restored through this route.
  • No customer is created, staff notification sent, signing credit calculated or payment issued. Internal workflow fields require their dedicated operator routes.

Side effects

  • Changed global rows request the referrals cache marker and advance server edit metadata in one checked global transaction. This updater does not write generic tenant field history or send email.

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. The reviewed CRM1 screen uses narrow status/date/count setters rather than this mapped updater.

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. Edit an editable company/contact/phone/email/notes cell. The shared updateData helper sends the mapped alias with id; status/date/count are also protected by the API, not just readonly in the table.

Related endpoints