Fieldmotion API Getting started

Contracts

Set contract hours budget

POST /a/Contract_setHoursBudget

Store the labour-hours allowance inside contract metadata for CRM1’s labour budget report.

When to use this endpoint

Use Contract_setHoursBudget for the Budget Hours cell on the CRM1 Contract Labour tab.

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 contract ID. The route does not verify that the row exists or is active/non-deleted.
valNumber stringYesConverted with floatval, then stored as a JSON string at meta.hours_budget. Nonnumeric text becomes 0; negative values are accepted.

Example request

$result = FM_api('Contract_setHoursBudget', [
	'id' => '720',
	'val' => '160',
]);

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":"missing or invalid parameter: val"}The val key is omitted.

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

Behaviour and edge cases

  • The JSON property is stored as text even though the input is converted to a float. Readers such as Contracts_getLabourBudgetsDT convert it back with floatval.
  • A nonexistent ID still returns success and produces an audit entry. There is no no-change shortcut, filtering, or pagination.

Side effects

  • May normalize the entire metadata object, updates meta.hours_budget and last_edited, and writes a contract audit entry.

See it in Fieldmotion

CRM1

Open Contracts → Contract Labour, edit Budget Hours, and filter Network requests for Contract_setHoursBudget.

CRM2

No direct production CRM2 caller was found; CRM2 has separate contract-labour models and mapped contract metadata.

Related endpoints