Fieldmotion API Getting started

Contracts

Set contract custom values

POST /a/Contract_setCustom

Set one named entry inside a contract’s legacy custom-value JSON object.

When to use this endpoint

Use Contract_setCustom for CRM1’s Contract Custom Details editor when changing one configured field.

Use the mapped customValues field only when intentionally replacing the complete custom object.

Authentication and permissions

The request must establish an authenticated tenant context. The handler checks DBP but has no separate page or role check.

The contract lookup is tenant-scoped and includes soft-deleted rows.

Parameters

ParameterTypeRequiredDescription
idInteger stringYesPositive contract ID. Soft-deleted contracts can be updated.
nameStringYesNonempty custom-field key. It is neither trimmed nor checked against contracts-template.
valueAny request scalar/arrayYesValue assigned to the named key. Blank and null-like present values are accepted; arrays are JSON-encoded with the containing object.

Example request

$result = FM_api('Contract_setCustom', [
	'id' => '720',
	'name' => 'Service tier',
	'value' => 'Gold',
]);

Example response

{
  "ok": 1
}

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: id"}The ID is absent or nonpositive.
{"error":"invalid parameter: name"}The name is omitted or false-like.
{"error":"missing parameter: value"}The value key is omitted.
{"error":"contract does not exist"}No row has the supplied ID.

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

Behaviour and edge cases

  • Blank stored custom data starts as an empty array before the named key is assigned. Existing JSON is decoded to an associative array.
  • The route does not remove keys, validate template types, update last_edited, or provide pagination.
  • A custom key named differently only by case is a separate JSON property.

Side effects

  • Replaces the stored custom JSON, invalidates the contracts cache, and writes a contract audit entry containing the full updated custom object.

See it in Fieldmotion

CRM1

Open a contract’s Custom Details from the Contracts table and change a configured field. Filter Network requests for Contract_setCustom.

CRM2

No direct production CRM2 call was found; CRM2’s mapped layout writes the complete customValues object.

Related endpoints