Record the number of signings attributed to one referral

When to use this endpoint

Record the number of signings attributed to 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.
`num_signed`	Positive integer string	Yes	Positive integer, at least 1; no float, negative, zero or nonnumeric coercion. Use num_signed, not mapped numSigned.

Example request

$result = FM_api('Referral_setNumSigned', ['id' => '1042', 'num_signed' => '1']);

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":"missing or invalid parameter: num_signed"}`	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 stores only a count; it does not change status/date or issue payment. The UI’s minimum of one is also enforced server-side.
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. The Signed dialog sends this endpoint after date and status have been saved, with its client-validated 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_setSignedDate stores the date.
Referral_setStatus stores the status.