Opportunity statuses and referrals
Record the signing date for one referral
/a/Referral_setSignedDate
Record the signing date for one referral.
When to use this endpoint
Record the signing date for 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.
The handler requires an authenticated tenant context and hardcodes account 32 as the internal Fieldmotion operator account. Other accounts receive the internal-use error even if they know a global referral ID. Within that account, the update/lookup is by global ID without a source-parent filter.
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. |
signed_date | Y-m-d string | Yes | Exact valid calendar date; missing, blank and impossible dates are rejected. Use snake_case signed_date, not mapped signedDate. |
Example request
$result = FM_api('Referral_setSignedDate', ['id' => '1042', 'signed_date' => '2026-10-10']);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 internal account 32; REFERRAL_ADMIN does not bypass this route. |
{"error":"no ID"} | ID absent or converts to zero. |
{"error":"invalid date parameter: signed_date"} | 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.
- This sets only the signing date, not status or num_signed. The server validates calendar dates independently of the UI.
- 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. On a converted/non-Open row, choose Signed and enter a date. The client sends this setter before the status and count setters.
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_setStatussets Signed separately.Referral_setNumSignedrecords count separately.Referral_updateDatauses mapped signedDate with calendar validation.