Opportunity statuses and referrals
Read opportunity-status labels through the mapped table/search contract
POST
/a/OpportunityStatuses_getDataTable
Read opportunity-status labels through the mapped table/search contract.
When to use this endpoint
Read opportunity-status labels through the mapped table/search contract.
Authentication and permissions
Authenticate with signed API-key fields or a logged-in CRM session. The handler requires login but does not check a settings-page permission, role or record owner. All rows in this family belong to the authenticated tenant’s opportunity_statuses table.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
fields | Native array | Yes | Mapped aliases to select; id is always added and unknown aliases ignored. JSON strings are not decoded. Aliases: id, name, cdate, lastEdited. |
isTable / start / length / draw / limit | Integer strings | No | Defaults 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 / orderDesc | Strings | No | In 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 array | No | Fallback 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 aliases | Scalar or native array | No | All 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 / searchField | String / alias or native array | No | Nonblank 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 / dateTo | Mapped alias / signed day offsets | No | Select 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 / offsetTo | Native {hour,minute} objects | No | Adjust 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 / timeRangeTo | Integer hour strings | No | Hour 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. |
groupBy | Native array of mapped aliases | No | Groups 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. |
advanceSearch | Native list of structured clauses | No | Each 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('OpportunityStatuses_getDataTable', ['fields' => ['name', 'cdate'], 'start' => '0', 'length' => '10', 'draw' => '1', 'orderBy' => 'name', 'orderDesc' => 'asc']);Example response
{"data":[{"name":"Negotiation","cdate":"2026-10-10 09:00:00","id":"1042"}],"draw":1,"recordsTotal":"4","recordsFiltered":"4"}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":"missing or invalid parameter: fields"} | Fields omitted. |
{"error":"error in database query"} | The primary query fails, including malformed LIMIT, grouping or order direction. |
{"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.
- Mapped keys are id (integer), name (text), cdate (creation Unix seconds in storage), and lastEdited (last_edited Unix seconds in storage). Read responses convert both timestamps to SQL datetime strings using the database connection timezone; they are not Unix numbers.
- recordsTotal counts the entire tenant opportunity_statuses table; recordsFiltered counts all matching rows before pagination, not grouped results. No active/built-in exclusion or feature gate applies.
- This read performs no write, audit, email or notification.
- 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
Open CRM1 Settings → General → Opportunity Statuses. pageSettingsOpportunityStatuses.js loads the legacy table, creates labels and saves inline name edits. CRM1 opportunity/customer screens and exports obtain the choices through OpportunityStatuses_list.
CRM2
CRM2’s Opportunity Statuses settings screen (pageOpportunitySettingsStatuses.js) uses CommonList/CommonLists with type=opportunityStatus instead, not this table. No direct CRM2 settings caller to this endpoint was found. Reproduce this contract with the example request; do not assume that changing it changes CRM2’s CommonList choices.
Related endpoints
OpportunityStatuses_getDTuses CRM1 positional rows.OpportunityStatus_getRequestedDetailsperforms unpaginated exact-filter reads.