Fieldmotion API Getting started

Jobs: scheduling and lifecycle

Change lifecycle status for selected jobs

POST /a/Jobs_statusSet

Apply shared status transitions to a selected ID list and collect per-job errors.

When to use this endpoint

Use the Jobs bulk status actions, including Incomplete→Completed and Completed→Processed. This bypasses the extra linked-quote and recurrence follow-ups in Job_setStatus.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. Legacy edit-restriction bit 128 is enforced; client administrators retain the existing admin exception.

The primary job selection is tenant-scoped. There is no automatic schedule-conflict or assignee-ownership check. Cross-tenant follow-ups use persisted outsourcing context.

Parameters

ParameterTypeRequiredDescription
statusInteger stringYesRequired-present target status, integer-coerced. Uses Job_statusChange semantics; 1 completes, 0 reopens, other indices must be configured. Nonnumeric present text becomes 0.
idsNative/form arrayYesJSON strings are treated as an empty list, not decoded. Integer-coerces, removes zero values and duplicates; negative nonzero values survive and normally yield a missing-job error. Empty list is accepted.
status_indStringNoDefault empty. completed-processed blocks a status-0 job when target>1; incomplete-completed blocks ANY current status>0. Other strings have no extra effect.

Example request

$result = FM_api('Jobs_statusSet', [
	'ids' => ['1042', '1088'], 'status' => '1',
	'status_ind' => 'incomplete-completed',
]);

Example response

{"errors":[]}

No top-level ok. errors contains strings for individual jobs; successful jobs are not listed. Empty/native-unsupported lists return errors=[] without changing jobs.

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: status"}Target status omitted/null.
{"error":"missing or invalid parameter: ids"}IDs omitted.
{"error":"Job does not exist: 1042"}Per-job errors element: missing/deleted/negative ID.
{"error":"Job 1042 is not yet complete."}Per-job completed-processed guard.
{"error":"Job 1042 is already complete."}Per-job incomplete-completed guard; any positive status is considered complete for this test.

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

Behaviour and edge cases

  • Enforces the edit restriction with client-admin exception. Active jobs are preloaded; per-job transition errors are collected and processing continues.
  • status_ind guards are legacy numeric comparisons, not exact lifecycle-state transitions: incomplete-completed can block Cancelled or Authorised jobs too.
  • Calls Job_statusChange directly, not Job_setStatus. It therefore does not perform that wrapper's recurrence-next update, contract dirty flag, linked-quote cancellation or explicit outbound-copy update.
  • Completion delegates to Job_setStatusToComplete and reopening manages mobile markers/counters. Non-completion transitions can set configured current_user_id and record Workflow runs.
  • An unchanged status is a shared-helper no-op, but missing IDs still yield errors. No transaction spans the batch and there is no pagination/size cap.

Side effects

  • Shared status effects include job history/edit metadata, configured Workflow, completion rules/mail/assets, reopen counters/removal markers, optional exports and eligible inbound outsource status mirroring. Wrapper-only Job_setStatus effects are absent.

See it in Fieldmotion

CRM1

Jobs → select rows → Change Status, Incomplete to Completed or Completed to Processed. jobsMultiEdit.js sends native ids and the optional named guard, then displays errors.

CRM2

The same bulk actions in lib/jobsMultiEdit.js use this route and errors collection. Normal row status editing is a separate mapped update flow.

Related endpoints