Fieldmotion API Getting started

Opportunity statuses and referrals

Page the current account’s referrals with mapped fields and submitter/company lookups

POST /a/Referrals_getDataTable

Page the current account’s referrals with mapped fields and submitter/company lookups.

When to use this endpoint

Use the CRM2 referral table contract to retrieve visible account referrals, then edit via Referral_updateData or inspect an ID with Referral_getRequestedDetails. This is not the cross-account operator list.

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 always adds parent_id=current account and status!=7. There is no account-3819 operator exception on this mapped route, and no creating-user-only restriction or additional page permission.

Parameters

ParameterTypeRequiredDescription
fieldsNative arrayYesNative mapped alias list; id, parentID and userID are added automatically so enrichment works even when omitted. Unknown aliases are ignored and JSON strings are rejected. Aliases include companyName, contactName, phone, email, notes, status, cDate, signedDate, referralSource, customerID, numSigned, appID, editedUUID and lastEdited.
isTable / start / length / draw / limitInteger stringsNoDefaults isTable=1, start=0, length=10, draw=0. start/limit must be nonnegative and length positive integers. Table mode uses LIMIT start,length. isTable=0 returns only data, unbounded unless limit>0; start/length are then ignored.
orderBy / orderDescStringsNoIn table mode supply both: mapped alias and asc/desc (case-insensitively normalized). Invalid aliases fall back to a selected mapped field; invalid directions return a validation error.
order[0][column] / order[0][dir]Native nested arrayNoFallback ordering when the explicit pair is absent. Column is converted to a selected-field index minus one, clamped at zero; exact desc descends, otherwise asc. With no order, the first selected mapped field ascends. No unique-ID tie-breaker.
Mapped aliasesScalar or native arrayNoAll supplied filters are ANDed. Scalar text is trimmed/lowercased substring LIKE with active %/_ wildcards; text arrays use exact membership. Numeric scalars use intval; numeric arrays use numeric membership, with empty lists matching none.
searchValue / searchFieldString / alias or native arrayNoNonblank searchValue adds ORed substring search over searchField aliases. Omission searches All mapped fields, not merely selected fields; invalid-only selections add no search constraint.
referenceDate / dateFrom / dateToMapped alias / signed day offsetsNoSelect the date alias first. dateFrom/dateTo must both be supplied for an inclusive day range relative to today in tenant timezone (UTC fallback). Timestamp ranges span 00:00:00–23:59:59, date-only ranges use Y-m-d.
offsetFrom / offsetToNative {hour,minute} objectsNoAdjust range boundaries: hour is negated, minute is added. Omit only by omitting the object; supply both keys when present. Date-only ranges ignore offsets.
timeRangeFrom / timeRangeToInteger hour stringsNoHour filter requires referenceDate and timeRangeFrom; timeRangeTo alone is ignored by a legacy condition. Defaults 0–23, swaps reversed bounds, applies the from-hour offset. SQL timezone conversion uses tenant timezone or Europe/London fallback; timezone tables affect results.
groupByNative array of mapped aliasesNoGroups selected SQL rows. Does not convert counts to group counts; non-grouped selected fields depend on database SQL mode. Avoid for normal paged record reads.
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

$table = FM_api('Referrals_getDataTable', ['fields' => ['companyName', 'status', 'parentID', 'userID'], 'id' => '1042', 'draw' => '1', 'start' => '0', 'length' => '10', 'orderBy' => 'id', 'orderDesc' => 'asc']);

Example response

{"data":[{"companyName":"Northwind Services","status":"0","parentID":"100","userID":"201","id":"1042","companies":{"100":"Example contractor"},"users":{"201":{"name":"Sam Taylor","email":"sam@example.com","parent":"100"}}}],"draw":1,"recordsTotal":"5","recordsFiltered":"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: fields"}Fields omitted.
{"error":"error in database query"}Main mapped query fails.
{"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

  • Rows are objects keyed by requested mapped aliases, plus id. Database scalar numbers remain strings. Table mode returns data, integer draw and database-string recordsTotal/recordsFiltered on every page; isTable=0 returns only data.
  • Without a unique tie-breaker, repeated sort values can move across pages. There is no snapshot/checkpoint guarantee for changing data.
  • Date range handling uses tenant timezone to choose today, then PHP/server-time parsing for constructed boundaries; Unix timestamp projection uses the database connection timezone. Do not assume every stage uses UTC.
  • 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.
  • Every row gains companies (object keyed by parentID, company-name string or false) and users (object keyed by userID, {name,email,parent} or false). These maps accumulate as rows are processed: later rows can contain lookup entries from earlier rows, not just the row’s own submitter.
  • companies/users are derived, not mapped filter/order aliases. The reader automatically includes parentID/userID for those identity lookups.
  • cDate/lastEdited remain SQL datetime strings and signedDate is a date/null. No create notification, cache write, audit or other mutation occurs.
  • 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.
  • recordsTotal counts the current account’s non-status-7 rows; recordsFiltered applies account/status visibility and requested filters before pagination. Neither count includes another account’s rows.
  • parentID and userID are automatically selected for companies/users enrichment. The maps remain cumulative per row; index users by userID and companies by parentID. CRM2’s email display uses the user ID, not the account ID.

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. CRM1 uses Referrals_getDT, not this named-field table.

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. Open the table, page or sort it and inspect the request. It includes parentID/userID and reads companies/users lookup maps to display the submitter.

Related endpoints