Fieldmotion API Getting started

Job types

Set a job type’s default form

POST /a/JobType_setForm

Set the form offered as a default when a job editor selects this type.

When to use this endpoint

Use JobType_setForm for CRM1’s Default Form cell. CRM2 normally writes mapped field metaFormID with JobType_updateData.

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 stringYesExisting positive job-type ID.
valInteger stringYesForm ID after integer conversion. 0 clears the default. A nonzero row must exist, but its type, archive state, and department are not checked.

Example request

$result = FM_api('JobType_setForm', [
	'id' => '42',
	'val' => '18',
]);

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 integer-converts below one.
{"error":"missing parameter: val"}val is absent or null.
{"error":"job type does not exist"}No type matches the ID.
{"error":"invalid parameter: val"}A nonzero form ID does not exist.

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

Behaviour and edge cases

  • Invalid or non-object existing metadata is replaced with an object. Otherwise unrelated metadata keys are preserved.
  • An equal integer value is a no-op. CRM1 applies the default whenever the type changes; CRM2 applies it only when the job form is empty.
  • Existing jobs keep their current form and form values.

Side effects

  • On change, writes meta.form_id, updates last_edited, and advances the job-type cache marker.
  • This focused setter writes no generic field-level audit entry.

See it in Fieldmotion

CRM1

Open Settings → Job Types and change Default Form. CRM1 lists non-archived job forms before calling this route.

CRM2

CRM2 filters form choices to active job forms compatible with the selected department, then saves through JobType_updateData; those UI restrictions are not server validation here.

Related endpoints