Fieldmotion API Getting started

Departments

Delete a department

POST /a/Department_delete

Permanently delete a department, detach it from active jobs, and record those job department changes.

When to use this endpoint

Use Department_delete only after confirming the department is no longer required. The CRM1 Departments page calls it from its row delete action.

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 stringYesDepartment ID after integer conversion; it must be greater than zero.

Example request

$result = FM_api('Department_delete', [
	'id' => '42',
]);

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, nonnumeric, zero, or negative. This validation happens before the login check.
{"ok":1}No department has the positive ID; absence is not reported as an error.

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

Behaviour and edge cases

  • All non-deleted jobs whose department_id matches are changed to department 0. Deleted jobs are left unchanged.
  • The operation is not transactional: the department deletion, bulk job update, per-job history writes, and deletion-log write happen separately.
  • There is no administrator or page-permission check beyond tenant authentication.

Side effects

  • Hard-deletes the tenant department and invalidates the departments cache.
  • Updates matching active jobs’ department_id, last_edited, and edited_uuid, invalidates the jobs cache, and writes a Department history entry for every affected job.
  • Writes a tenant deletion-log entry even when the positive department ID did not exist. It does not remove the ID from users, assets, customers, requisition orders, or purchase orders.

See it in Fieldmotion

CRM1

Open Users → Departments and delete a row. CRM1 calls this endpoint after the confirmation dialog.

CRM2

The shared Departments widget derives this delete route, although visibility and confirmation are client-side concerns rather than server permission checks.

Related endpoints