Fieldmotion API Getting started

Skills

Create a skill

POST /a/Skill_new

Create one named skill through the administrator-only legacy editor, rejecting an existing name.

When to use this endpoint

Use Skill_new for CRM1’s Skills create dialog or when you require its admin check and duplicate-name response. CRM2’s shared editor normally derives Skill_createData.

Authentication and permissions

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

Validation of the name occurs before authentication; callers can receive a name error before a login/admin error. The lookup and insert are confined to the authenticated tenant.

Parameters

ParameterTypeRequiredDescription
nameStringYesTrimmed skill name. It must be truthy after trimming, so empty string and "0" are rejected. Maximum 100 bytes, not 100 Unicode characters.
descriptionStringNoTrimmed description; defaults to an empty string and has no endpoint length limit.

Example request

$skill = FM_api('Skill_new', [
	'name' => 'Electrical testing',
	'description' => 'Qualified to complete electrical tests',
]);

Example response

{
  "ok": 1,
  "id": 42
}

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: name"}The trimmed name is PHP-empty.
{"error":"not an admin"}The caller is authenticated but is not a client administrator.
{"error":"name is too long, 100 character limit."}The trimmed name exceeds 100 bytes; the message says characters but the implementation uses byte length.
{"id":"42","error":"that skill already exists"}A row with the same name exists under the tenant database collation.

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

Behaviour and edge cases

  • Duplicate checking includes every skill because skills have no archive/delete state. The existing ID is returned with the duplicate error.
  • The duplicate lookup and insert are separate and not protected by a database uniqueness constraint, so simultaneous creates can race.
  • No user assignment, filtering, or pagination is involved.

Side effects

  • Inserts current Unix time into both cdate and last_edited, plus the trimmed name and description.
  • Does not explicitly invalidate the skills cache or write generic audit history.

See it in Fieldmotion

CRM1

Open Users → Skills, choose Create, enter a name/description, and inspect Skill_new.

CRM2

A production-source search found no direct CRM2 caller. The CRM2 Skills page uses the shared Skill_createData route.

Related endpoints