List contract choices · Fieldmotion API

When to use this endpoint

Use Contracts_list to populate job, quote, order, asset-timeline, and recurrence contract selectors.

Pass the current customer/asset for relevant choices and always for an existing selection that must remain visible even if inactive or expired.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session. The handler performs no additional page or role-permission check.

The lookup and any write use the authenticated tenant; an ID from another tenant cannot be addressed through this call.

Parameters

Parameter	Type	Required	Description
`customer_id`	Integer string	No	Customer or asset ID. A positive value enters relationship mode. The cached match does not distinguish type, so equal customer/asset IDs can collide.
`customer_type`	Integer string	No	Normally `0` customer or `1` asset. Any positive value also enters relationship mode. Only exact `1` enables the asset-location customer fallback.
`active`	Integer string	No	In relationship mode, any truthy integer adds `active`. Zero/blank means no status filter; it cannot request only completed rows.
`all`	String	No	Exact `1` includes active and completed rows only when not in relationship mode.
`non-expired`	Integer string	No	Truthy keeps null expiry or dates later than the current PHP server date/time. Today’s date compares as earlier than a current date-time and can be excluded.
`always`	Integer string	No	Positive non-deleted contract ID OR-ed into the result even when it fails relationship, active, or expiry filters.

Example request

$contracts = FM_api('Contracts_list', [
	'customer_id' => '1042',
	'customer_type' => '0',
	'active' => '1',
	'non-expired' => '1',
	'always' => '720',
]);

Example response

[
  {"id": "720", "name": "North Region Service Contract"},
  {"id": "731", "name": "National Support"}
]

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.
`[]`	No non-deleted contract matches.

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

Behaviour and edge cases

Relationship matching is ID-text based. The cached customers field is searched for ,ID] without checking the preceding type. A customer and asset sharing the same numeric ID can therefore see each other’s contracts.

With no customer/asset mode, the default is non-deleted active contracts ordered by name. Relationship mode has no explicit order.
For an asset whose current location is a customer, relationship mode also includes contracts whose cache contains that customer ID.
Before relationship filtering, every contract marked customersDirty in the tenant is rebuilt. This can make a picker request substantially more expensive than its small response suggests.
There is no pagination or limit. always never revives a soft-deleted row.

Side effects

Rebuilding dirty customer caches replaces relationship rows and touches affected contracts’ customers, meta, and last_edited values.

See it in Fieldmotion

CRM1

Open or edit a job and inspect the Contract selector; CRM1 calls Contracts_list with customer/asset, active, non-expired, and current-selection values. Jobs, Quotes, and target selectors also use it.

CRM2

Contract pickers in CRM2 jobs, quotes, assets, recurring work, and list-picker widgets call Contracts_list. Filter Network requests while opening one of those selectors.

Related endpoints

Contracts_getById expands selected IDs into additional fields.
Contracts_getDataTable provides full CRM2 filtering/pagination.