Fieldmotion API Getting started

Opportunity statuses and referrals

Read selected referral fields, including hidden referrals, within the current account

POST /a/Referral_getRequestedDetails

Read selected referral fields, including hidden referrals, within the current account.

When to use this endpoint

Read selected referral fields, including hidden referrals, within the current 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 and adds parent_id=current account. It does not restrict to the creating user or apply a separate page permission.

Parameters

ParameterTypeRequiredDescription
fieldsNative arrayNoDefaults to all mapped aliases. id is always added. Unknown aliases are ignored. Supply nested arrays directly to FM_api; JSON strings are not decoded here. Aliases: id, userID, companyName, phone, email, notes, status, cDate, signedDate, parentID, contactName, referralSource, customerID, numSigned, appID, editedUUID, lastEdited.
id / idsPositive integer string or nonempty native arrayNoOptional validated selector. id takes precedence; malformed, nonpositive and explicitly empty native lists are rejected. IDs do not grant access outside the authenticated account.
Mapped aliasesScalar or native arrayNoAdditional filters are ANDed. Scalar text is lowercased/trimmed exact equality, not substring search; text arrays use lowercase membership. Numeric scalars use intval; numeric arrays retain numeric entries and empty numeric lists match none.
orderAlias, native array of aliases or {id,dir} objectsNoDefault has no ORDER BY. Each id is a mapped alias, not a record ID; only dir=desc selects descending. Unknown aliases are skipped. No pagination or limit is applied.
advanceSearchNative list of structured clausesNoEach clause uses a mapped alias in column or id, supported condition (equal, contains, notEqual, greaterThan, greaterThanOrEqual, lesserThan, lesserThanOrEqual), scalar/native scalar-list value, optional AND/OR and balanced special parentheses. Raw where SQL is rejected.

Example request

$rows = FM_api('Referral_getRequestedDetails', ['id' => '1042', 'fields' => ['companyName', 'contactName', 'status', 'signedDate']]);

Example response

[{"companyName":"Northwind Services","contactName":"Alex Morgan","status":"0","signedDate":null,"id":"1042"}]

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.
[]No match, another account’s ID, or a failed query. Missing records and query failure are indistinguishable.
{"error":"unsupported raw advanced search"}A raw where clause is supplied.
{"error":"unbalanced advanced search"}Structured parentheses are unmatched.
{"error":"missing or invalid parameter: orderDesc"}Explicit direction is not asc/desc.
{"error":"missing or invalid parameter: id"}Invalid/nonpositive selector; the message names id or ids.

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

Behaviour and edge cases

  • Unlike the table endpoints, there is no status!=7 filter. Hidden/deleted-by-status rows remain readable in their owning account.
  • CRM1 presents status 0=Open, 1=Contacted, 2=Signed, 3=Declined, 4=Paid. Status 7 hides a row from both table endpoints. The dedicated status setter accepts 0–4; legacy stored values are not remapped on read.
  • Datetime aliases cDate/lastEdited return stored SQL datetime strings; signedDate returns a date string or null. Database integer fields remain strings. No row enrichment with companies/users is added here.
  • No limit, pagination, default ordering, cache update, mail or other write occurs. There is no referral-specific feature gate.
  • Native selectors and query controls are validated before the helper runs. Explicit empty/nonpositive ID selectors are rejected; unknown mapped field names are still ignored.

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.

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.

Related endpoints