Customer tab: legacy Contract APIs
Read contract details through the customer tab alias
/a/CustomerContract_getRequestedDetails
Read mapped Contract details.
When to use this endpoint
Supply explicit Contract IDs for details. 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. |
isContractMain | Integer-compatible mode | No | Exactly 1 enriches financial/date display. Omitted or any other value returns a raw row array. Enrichment loads the needed base fields automatically even with a narrow fields list. |
Example request
$result = FM_api('CustomerContract_getRequestedDetails', ['id'=>['18'],'fields'=>['id','name']]);Example response
[
{
"id": "18",
"name": "Annual service"
}
]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.
- Raw detail projection uses the alias map (custom, not customValues). Main mode adds financial totals, jobs, sorCostPerJob and customerAssetID (encoded ID-only list). cDate formats M d, Y g:i A; expiryDate/dateCompleted format M d, Y. Null/blank cDate and dateCompleted remain null; null expiry displays No Expiration. Unparseable saved dates become null.
- When meta.customersDirty is present, ordinary Contracts derive customers and customerAssetID from the same visible Job set for this response. Explicit Programme membership is preserved. This read never rewrites stored customers, meta or links.
- 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
CustomerContracts_getDataTable— Find Contract IDs and understand tab-specific costs.CustomerContract_createData— Create the underlying Contract.CustomerContract_updateData— Understand invoiceability and expiry follow-ups.CustomerContract_updateField— Use the different canonical inline field map.