Fieldmotion API Getting started

Jobs: reports, email and links

Send an internal assignment email

POST /a/Job_emailAbout

Understand the internal PHP assignment-email helper and why its HTTP route cannot take assignment arguments.

When to use this endpoint

This helper is called positionally by PHP Job_setUserId and Jobs_setUser. Use the assignment setters to change a job and trigger its configured notification; posting assignment fields here is not an alternative setter.

Authentication and permissions

Signed API-key authentication or a logged-in CRM session is required. The handler uses the authenticated tenant and has no additional role/page check.

The dispatcher also applies user/account and IP restrictions. CRM sessions carrying a CSRF token must supply X-FMCSRF or _csrf; missing or incorrect tokens can be rejected before the handler runs.

Parameters

This endpoint has no operation-specific parameters.

Example request

// The HTTP dispatcher supplies no positional PHP arguments.
$result = FM_api('Job_emailAbout', []);

Example response

{"error":"no user_id"}

The normal authenticated HTTP response is always this error, even if user_id is posted. Internally the helper has no explicit success return (null).

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":"no user_id"}The HTTP dispatcher calls the function with its default user_id=0. Internally, a zero positional user ID has the same result.
{"error":"meeting time is far in the past"}Internal call: formatted meeting_time contains 1970.
{"error":"user does not exist"}Internal call: the positional user ID did not resolve.
{"error":"Job email queue response was not confirmed. Check mail history before retrying."}Mail failed or returned an ambiguous acknowledgement. Earlier recipients may already be queued; do not repeat automatically.

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

Behaviour and edge cases

  • Its positional PHP arguments are user_id=0, old_uid=-1, form_id=0, customer_type=0, customer_id=0, notes='', meeting_time='', job_ref='', id=0 and assignment=null. Neither api.php nor fnCall maps request fields to those arguments.
  • Internal calls select user_reassigned when old_uid>0, otherwise user_assigned. email_user must equal 1 to retain the assignee’s address. The notification enabled flag controls template preferences but does not itself suppress this helper’s delivery.
  • Template selection uses the configured template, then the form-based default, then the last numerically matching form override. Asset context resolves a customer location first or owner otherwise; structured notes are flattened.
  • When assignment is omitted, source metadata uses typed user type 0 for the new assignee and for the old assignee when old_uid>=0. The supplied snapshot is used unchanged when present. There is no list filtering or pagination.

Side effects

  • Internal calls attempt type-2 mail to the assignee and log job history as email about when id is nonzero only after a positive mail acknowledgement. An uncertain reply returns an error asking for mail-history review. The direct HTTP no-user branch does neither.

See it in Fieldmotion

CRM1

Change a job’s assigned user or use bulk assignment. PHP Job_setUserId / Jobs_setUser call this helper directly; inspect the setter request, not a separate Job_emailAbout browser request.

CRM2

No direct HTTP caller was found. CRM2 mapped/typed assignment uses its assignment workflow; do not call this helper route to reproduce that behavior.

Related endpoints