Opportunity statuses and referrals
Set the operator workflow status of one referral
/a/Referral_setStatus
Set the operator workflow status of one referral.
When to use this endpoint
Set the operator workflow status of one referral. This is an internal operator workflow, not a general tenant integration operation.
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 an authenticated tenant context. Access is allowed for account 32 or when the internal REFERRAL_ADMIN constant is defined; its definedness is tested, not its truth value. This is not a caller-supplied request flag and is not a normal integration bypass.
No parent_id ownership check is added to the global-ID update. The guard differs from conversion/date/count setters, which only allow account 32.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | Positive integer string | Yes | One global referral ID. The internal operator account/constant guard runs before ID and row validation. |
status | Integer string | Yes | Only 0=Open, 1=Contacted, 2=Signed, 3=Declined or 4=Paid. Status 7 is not accepted as a deletion bypass. |
Example request
$result = FM_api('Referral_setStatus', ['id' => '1042', 'status' => '2']);Example response
{"ok":1}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":"this system is only for FieldMotion use"} | Not account 32 and no defined internal REFERRAL_ADMIN constant. |
{"error":"no ID"} | ID absent or converts to zero. |
{"error":"missing or invalid parameter: status"} | Requested workflow value is absent or invalid. |
{"error":"referral write failed"} | Checked global write fails and rolls back. |
{"error":"referral read failed"} | Checked row read fails. |
{"error":"referral transaction failed"} | Global transaction start/commit fails. |
{"error":"referral does not exist"} | ID is missing, or the row is hidden when a workflow edit is requested. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- The operator permission guard and global-ID row lock precede the write. Status-7 rows are not editable via these routes; a missing row is an error.
- Valid unchanged values return ok without advancing server metadata. A changed write is checked and receives current last_edited plus a server route marker.
- Changing status does not fill signed_date or num_signed, create a customer, calculate commission or issue payment. The UI still uses three calls for Signed.
- No tenant feature flag changes the internal operator account rules.
Side effects
- Changed global rows update the named value and server edit metadata and request the referrals cache marker in a checked transaction. No tenant field history, notification, email or customer update is added.
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 the operator table, change a non-Open row’s Status. Selecting Signed first saves the date, then calls this setter with 2, then saves the signed count.
CRM2
The reviewed CRM2 Refer another business page does not call this internal operator endpoint. Its table displays status, signedDate and numSigned as readonly cells; that page is not an equivalent operator workflow.
Related endpoints
Referral_setSignedDatestores the signing date separately.Referral_setNumSignedstores the signing count separately.Referral_convertToCustomerperforms the separate Open-to-customer action.