Fieldmotion API Getting started

Skills

Set a skill description

POST /a/Skill_setDescription

Replace one skill description through CRM1’s administrator-only inline editor.

When to use this endpoint

Use Skill_setDescription only to reproduce CRM1’s nonblank inline edit. Use Skill_updateData when clearing a description or following CRM2’s mapped workflow.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session, and the identity must pass Core_isClientAdmin().

ID and description validation runs before authentication. The update is scoped to the authenticated tenant.

Parameters

ParameterTypeRequiredDescription
idInteger stringYesSkill ID after integer conversion; it must be greater than zero.
descriptionStringYesTrimmed complete replacement. Empty string, whitespace, and "0" are rejected. No maximum length is enforced by the handler.

Example request

$result = FM_api('Skill_setDescription', [
	'id' => '42',
	'description' => 'Qualified to complete electrical tests',
]);

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 below 1 after conversion.
{"error":"missing or invalid parameter: description"}The trimmed description is PHP-empty.
{"error":"not an admin"}The authenticated caller is not a client administrator.
{"ok":1}The positive skill ID does not exist; affected-row count is not checked.

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

Behaviour and edge cases

  • The description is trimmed before storage. This route cannot clear it, despite CRM1 allowing the user to type a blank value before the server rejects it.
  • No name or duplicate check is involved, and no current row is loaded before updating.

Side effects

  • Updates the description and sets last_edited to current Unix time.
  • Does not explicitly invalidate the skills cache or write generic audit history.

See it in Fieldmotion

CRM1

Open Users → Skills and click a Description cell. Leaving the edited field triggers Skill_setDescription.

CRM2

CRM2 edits descriptions through the shared Skill_updateData route and can store a blank value.

Related endpoints