Fieldmotion API Getting started

Contracts

Update one mapped contract field

POST /a/Contract_updateField

Apply one mapped contract field to one or more non-deleted contracts and return their previous raw values.

When to use this endpoint

Use Contract_updateField for a controlled bulk change where every selected contract receives the same mapped value.

Prefer Contract_updateData for normal CRM2 edits because it can update related fields together.

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

ParameterTypeRequiredDescription
fieldMapped field nameYesOne of id, name, cDate, notes, lastEdited, createdBy, active, customers, customValues, budget, expiryDate, number, address, manager, typeID, dateCompleted, meta, dateStarted, metaHoursBudget, metaNotInvoiceable, or metaStage. Internal/derived fields are not blocked.
valMapped valueYesShared replacement value. Date fields require valid YYYY-MM-DD or blank; other types use generic coercion and map limits.
idInteger string or arrayConditionalOne ID or native array. When both id and ids are present, this key wins.
idsNative arrayConditionalAlternative multi-ID list. A JSON string is not decoded and is converted as one integer-like scalar; send a request array.

Example request

$result = FM_api('Contract_updateField', [
	'ids' => ['720', '721'],
	'field' => 'metaStage',
	'val' => 'renewal',
]);

Example response

{
  "ok": 1,
  "oldData": [
    {"id": "720", "meta": "{\"stage\":\"review\"}"},
    {"id": "721", "meta": "{}"}
  ]
}

Errors and unusual responses

ResponseCondition
{"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: field"}field is omitted.
{"error":"missing or invalid parameter: val"}val is omitted.
{"error":"missing or invalid field"}The field is outside the contract map.
{"error":"missing or invalid parameter: id/ids"}Neither ID parameter is present.
{"error":"invalid date parameter: ..."}A mapped date value is invalid.
{"ok":"1","warning":"no change required"}No matching non-deleted row needs a different value; unknown IDs also reach this response.

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

Behaviour and edge cases

  • IDs are integer-converted and soft-deleted rows are excluded. Duplicate IDs collapse in the SQL IN query.
  • Non-JSON fields are updated in one statement; nested metadata fields are updated row by row. last_edited advances on changes.
  • Changing expiryDate synchronizes all expiry work for every extracted ID. Changing active replaces type-104 work from each current expiry.

Side effects

  • Writes one generic contract audit entry whose object ID is a comma-separated set of changed IDs. The oldData response contains raw rows read before the write.
  • Expiry and active changes also mutate global cron rows; those writes are not transactional with the contract update.

See it in Fieldmotion

CRM1

No active CRM1 client caller was found.

CRM2

The generic CRM2 display framework can derive this setter, but the current Contract configuration uses Contract_updateData; a former explicit call remains commented out on the detail page.

Related endpoints