List contracts on a customer tab

When to use this endpoint

Supply customers to select exact Customer membership. This namespace does not add that selection implicitly.

Authentication and permissions

Use signed API-key authentication or a logged-in CRM session. API keys act as their owner; session requests use dispatcher CSRF protection where configured. IDs and mapped queries address the authenticated tenant.

Login is required. CRM2 requests require Contracts View. CRM2 TeamAccess scope applies to records and related data. These added CRM2 role/scope checks do not apply to CRM1 requests; CRM1 retains its legacy permission model. Tenant isolation and business validation apply to both clients.

Parameters

Parameter	Type	Required	Description
`id / ids`	Positive integer or native/JSON-encoded list	Yes for updates; optional for reads	id takes precedence. Decimal integer strings are accepted and duplicates removed; invalid/nonpositive members reject the selection. Empty lists select no records. Omitted IDs on a read leave the other mapped filters in control.
`fields`	Native list of mapped names	Required for tables; optional for details	Details default to all mapped fields. Unknown projection names are omitted and id is included. JSON-encoded fields text is rejected.
`Mapped filters / advanceSearch`	Scalars, native lists or structured rules	No	Mapped filters combine with AND; lists use IN. Detail quoted scalars use trimmed case-insensitive exact matching; table quoted scalars use substring LIKE. Advanced rules require a mapped column/id, value and one of equal, notEqual, contains, greaterThan, greaterThanOrEqual, lesserThan, lesserThanOrEqual; andOr and balanced special parentheses are validated. Raw where fragments and nonempty groupBy are rejected.
`order / orderBy / orderDesc`	Mapped names/descriptors or DataTables order	No	Use mapped names and asc/desc. Tables accept DataTables column/dir ordering or named orderBy/orderDesc, with main.id ascending as a stable tie-breaker. Detail order accepts mapped names or {id,dir} descriptors; no detail pagination is applied.
`start / length / draw`	Integer-compatible	No	Table defaults are 0/10/0. start is a nonnegative offset, length must be positive, draw is echoed as an integer. length=-1 is rejected; no route-specific maximum is imposed.
`isTable / limit`	Integer-compatible	No	Default table mode returns data, draw, recordsTotal and recordsFiltered. isTable=0 returns a data envelope without draw/counts; limit is a nonnegative unpaged cap (0 means uncapped).
`searchValue / searchField`	Text / mapped name or native list	No	Nonblank text performs case-insensitive substring LIKE; searchField defaults All. SQL LIKE % and _ retain wildcard meaning. Joined reference fields search their configured labels.
`referenceDate / dateFrom / dateTo`	Mapped date name / integer day offsets	No	With both bounds, select inclusive day boundaries relative to today in the account timezone (UTC fallback). Bounds are day offsets, not absolute dates. offsetFrom/offsetTo hour/minute objects adjust datetime boundaries; date-only fields ignore them. timeRangeFrom enables inclusive hour filtering, with timeRangeTo default 23; reversed hour bounds swap and the hour timezone defaults Europe/London.
`customers / customerAssetID`	Positive ID	No	Both select exact Customer membership tuples; supplying different values is rejected. Numeric/string encodings of historical tuple elements are accepted; similarly numbered IDs and the other object type do not match.
`expiryStatus`	Scalar or native list	No	Uses the first list value. 0 selects NULL expiry (no expiration), 1 selects non-NULL expiry; neither tests whether a date has passed. Other nonnegative IDs add no expiry predicate; blank/empty skips it.

Example request

$result = FM_api('CustomerContracts_getDataTable', ['fields'=>['id','name'],'customers'=>'1042','start'=>'0','length'=>'10','draw'=>'1']);

Example response

{
  "data": [
    {
      "id": "18",
      "name": "Annual service",
      "meta": "{\"spendStatus\":\"ok\",\"hoursSpentStatus\":\"ok\"}",
      "customers": "[[0,1042]]",
      "labourCost": 0,
      "mileageCost": 0,
      "stockCost": 0,
      "sorCost": 0,
      "miscCost": 0,
      "netPrice": 0,
      "grossPrice": 0,
      "jobs": [],
      "sorCostPerJob": "[]"
    }
  ],
  "draw": 1,
  "recordsTotal": "12",
  "recordsFiltered": "1"
}

Scalar numeric values may be strings or numbers depending on the database driver.

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 is not a native list, or is absent in table mode.

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

Behaviour and edge cases

Details return a bare row array; plural table routes return a data envelope (draw/counts are omitted with isTable=0). Empty selections produce []/empty data. Database scalar types remain driver-dependent; whole JSON/text columns remain encoded strings. Counts respect the same CRM2 visibility boundary as the data; recordsFiltered includes the request filters.
Totals, jobs and per-Job rates use one active Job set: direct contract_id matches win; a type-6 relation is a fallback only when the Job has no direct Contract. CRM2 Job scope is applied only to CRM2 requests. Table customer filters also constrain Jobs by the exact Customer/Asset type and ID. jobs contains integer IDs ordered by scheduled time then ID.
labourCost, mileageCost, stockCost, miscCost, netPrice and grossPrice sum saved Job amounts. sorCost uses the shared Job rate-cost calculation, including every rate row multiplied by its ordered quantity and component quantities. Saved component costs are honored; missing components are enriched from current rate data. Rate totals round to three decimals; sorCostPerJob is an encoded array of {id,sorCost}. Empty Job sets return zero totals and empty lists.
Uses the canonical Contract projection map (customValues and nested metadata aliases), and includes id, meta and customers automatically. Without a customer filter, returns all visible matching Contracts with totals over their full Job sets.
No direct caller of this exact namespace was found in the current mobile intermediary/app sources; mobile synchronization uses separate APIs.

Side effects

Reads only; no record, membership, queue or notification changes.

See it in Fieldmotion

CRM1

In CRM1, open Customers > a record > Contracts. The current source uses Customer_contractsGetDT for the table and Contract_setNotes/Contract_setActive for edits; no direct call to this alias was found.

CRM2

In CRM2, open Customers > a record > Contracts. The current shared moduleContracts selects Contract/Contracts prefixes, including Contracts_getDataTable and Contract create/update routes; no direct current caller to this legacy alias was found. Inspect those requests rather than assuming the tab caption selects this namespace.

Related endpoints

CustomerContract_getRequestedDetails — Read raw or enriched Contract details.
CustomerContract_createData — Create the underlying Contract.
CustomerContract_updateData — Understand invoiceability and expiry follow-ups.
CustomerContract_updateField — Use the different canonical inline field map.