Fieldmotion API Getting started

Schedule of Rates

Set Schedule of Rates labour

POST /a/ScheduleOfRates_setLabour

Replace the stored labour definition for one Schedule of Rates row.

When to use this endpoint

Use ScheduleOfRates_setLabour for CRM1’s labour editor. Supply the complete labour list, not a patch.

Authentication and permissions

The request must establish tenant context with signed API credentials or a logged-in CRM session. The handler checks for the tenant database prefix rather than calling the normal login guard.

No additional page or role permission is checked. The CRM screens apply their own client-side Schedule of Rates permissions.

Parameters

ParameterTypeRequiredDescription
idInteger stringYesPositive rate ID.
valJSON string or native arrayNoComplete labour value. Native arrays are JSON-encoded. Strings are stored without JSON validation. Omission stores []. New objects normally contain user_id, hours, and total cost; legacy pairs contain user ID and hours.

Example request

FM_api('ScheduleOfRates_setLabour', [
	'id' => '430001',
	'val' => [[
		'user_id' => 18,
		'hours' => 2,
		'cost' => 50,
	]],
]);

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 not positive.
{"error":"schedule of rates does not exist"}The ID has no row.
{"ok":1,"msg":"no change needed"}The resulting string exactly matches labour_used.

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

Behaviour and edge cases

  • Native arrays are encoded once; already-encoded strings are stored verbatim.
  • Legacy derived-cost readers do not correctly fall back from [user_id,hours] to the user’s current hourly cost, so integrations should store explicit cost objects.

Side effects

  • On change, advances last_edited and the scheduleOfRates cache marker.
  • Fires the tenant-configurable SOR_edit event with the rate ID. Any configured listeners run synchronously and can add integration-specific side effects.

See it in Fieldmotion

CRM1

Edit the Labour Used table on the Schedule of Rates page.

CRM2

CRM2 stores labour through ScheduleOfRate_updateData.

Related endpoints