Update contracts through the field map

When to use this endpoint

Use Contract_updateData for CRM2 configurable list, modal, and Kanban saves where several mapped fields can change together.

Use a focused Contract_set* endpoint only when its narrower validation or exact CRM1 behavior is required.

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
`id`	Integer string or array	Yes	One contract ID or a native request array. Soft-deleted and unknown IDs are skipped with warnings. Multi-ID mode applies the same fields to each ID but discards individual results.
`name / notes / number / address / manager`	Strings	No	Mapped text fields. Name has a 64-character mapper limit; the others use their map/schema types without wrapper-specific validation.
`active / budget / typeID / createdBy`	Numbers	No	Mapped status, budget, type, and creator fields. Referenced IDs and supported status values are not checked by this wrapper.
`customers`	String	No	Raw cached customer/asset list. External callers should not update this derived compatibility field directly.
`customValues`	JSON value	No	Complete replacement for stored contract custom values.
`expiryDate / dateStarted / dateCompleted`	Date / date-time strings	No	Mapped lifecycle dates. Date fields accept valid `YYYY-MM-DD` or blank; date-time conversion follows the shared mapper.
`meta`	JSON value	No	Complete raw metadata replacement. This can remove internal cache/import/status fields and should not be used by ordinary integrations.
`metaHoursBudget / metaNotInvoiceable / metaStage`	Scalar	No	Mapped properties below `meta`. Blank/number coercion follows the shared field types.
`noRecord / noRecordCustom`	Arrays	No	Internal audit controls that hide selected generic log entries.

Example request

$result = FM_api('Contract_updateData', [
	'id' => '720',
	'name' => 'North Region Service Contract',
	'budget' => '27500',
	'expiryDate' => '2027-09-30',
	'metaStage' => 'renewal',
]);

Example response

{
  "ok": 1
}

A no-op returns {"warning":"No Change."}; an unknown/deleted ID returns {"warning":"No data."}; no recognized mapped fields returns {"warning":"no updated fields."}.

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: id"}`	The `id` key is omitted.
`{"error":"invalid date parameter: expiryDate"}`	A mapped date does not match a valid `YYYY-MM-DD` value or blank.
`{"error":"... has a maximum length of ..."}`	A mapped length constraint is exceeded.

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

Behaviour and edge cases

Multi-ID expiry/status side effects target the wrong shape. The generic mapper updates each ID, then the wrapper applies expiry/status scheduling using intval on the original ID array rather than iterating it. Use single-ID requests when changing expiryDate or active.

Only supplied mapped keys are changed; unknown keys are ignored. Soft-deleted contracts are excluded.
A scalar no-op or missing row returns a warning rather than ok. Multi-ID mode always ends with {"ok":1}, even when individual updates warn or fail.
A successful expiryDate update replaces email and status schedules. A successful active update replaces status work using the current stored expiry.

Side effects

Changed fields update last_edited and create generic contract activity entries; custom-value changes are logged per custom key.
The wrapper scans mapped note values for mentions after every non-error result, including warning/no-change paths. It does not publish the notification-service update event.

See it in Fieldmotion

CRM1

No normal CRM1 caller was found. CRM1 uses full edit and focused setters.

CRM2

Edit a contract from the CRM2 Contracts list, detail layout, or Kanban card and filter Network requests for Contract_updateData. Kanban stage moves also use this route.

Related endpoints

Contract_getRequestedDetails reads the same mapped field names.
Contract_updateField applies one mapped field to one or more IDs.
Contract_edit is CRM1’s replacement-oriented save.