Fieldmotion API Getting started

Contracts

Set contract name

POST /a/Contract_setName

Rename one non-deleted contract with explicit blank and length validation.

When to use this endpoint

Use Contract_setName for CRM1’s inline Contract Name edit.

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
idInteger stringYesPositive non-deleted contract ID.
nameStringYesTrimmed nonblank replacement, at most 64 bytes as measured by strlen. The value need not be unique.

Example request

$result = FM_api('Contract_setName', [
	'id' => '720',
	'name' => 'North Region Service Contract',
]);

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":"invalid or missing parameter: id"}The ID is absent or nonpositive.
{"error":"parameter too long: name"}The trimmed name exceeds 64 bytes. Multibyte characters can therefore consume more than one unit.
{"error":"invalid or missing parameter: name"}The trimmed name is blank.
{"error":"contract does not exist"}No non-deleted contract has the 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

  • If the stored and submitted strings are identical, the endpoint returns success without touching last_edited or writing an audit entry.
  • Contract names are not required to be unique. This is a single-row mutation without filtering or pagination.

Side effects

  • On a change, updates name/last_edited, invalidates the contracts cache, and writes a contract audit entry.

See it in Fieldmotion

CRM1

Click a Contract Name cell on the Contracts page, edit it, and filter Network requests for Contract_setName.

CRM2

No direct production CRM2 call was found; CRM2 uses mapped updates.

Related endpoints