Set contract start date · Fieldmotion API

When to use this endpoint

Use Contract_setDateStarted for CRM1’s inline Started date picker on a known contract.

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	Yes	Positive contract ID. Existence and deletion state are not checked.
`val`	String	Yes	Value written directly to the date column after SQL escaping. It is not validated or normalized as `YYYY-MM-DD`.

Example request

$result = FM_api('Contract_setDateStarted', [
	'id' => '720',
	'val' => '2026-10-01',
]);

Example response

{
  "ok": 1
}

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 is absent or nonpositive.
`{"error":"missing or invalid parameter: val"}`	The key is omitted. A present blank string is accepted and left to database date handling.

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

Behaviour and edge cases

Date validity is delegated to the database. The handler neither validates the format nor checks the update result, and returns success for a positive nonexistent ID. Send a real YYYY-MM-DD value and verify important changes.

This is a one-row mutation with no filtering, pagination, or no-change detection.
Soft-deleted rows are addressable because the update has no deleted=0 predicate.

Side effects

Updates date_started and last_edited when a row matches, and writes a contract audit entry regardless.

See it in Fieldmotion

CRM1

Click the Started date on the Contracts page, choose a date, and filter Network requests for Contract_setDateStarted.

CRM2

No direct production CRM2 caller was found; CRM2 uses Contract_updateData.

Related endpoints

Contract_setExpiryDate validates and schedules the expiry date.
Contract_updateField validates mapped dateStarted values.