Fieldmotion API Getting started

Reporting dashboards and targets

Change a monthly user target

POST /a/ReportsTarget_setTarget

Update the stored target for a selected user, target type, year, and zero-based month.

When to use this endpoint

Initialize annual targets first, then send the table’s user/type/year plus its zero-based month for a cell edit. This setter cannot create a missing row.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session; all rows belong to that tenant.

Employer feature bit 8192 is required by both target feeds and mutations. No additional page-role, department, ownership, or target-user permission check is enforced.

For signed form requests, sign numeric scalar values as strings, including values inside native nested arrays. Send JSON text only for parameters explicitly accepting JSON strings; see Getting started.

These reporting handlers require tenant schema upgrade 794 before deployment. No request path creates or repairs schema.

Parameters

ParameterTypeRequiredDescription
typeInteger-compatibleYesCRM target editors use 0 Quote Won, 1 Invoice Paid, 2 Job, and 3 Opportunity. The handler does not enforce this list. Must be a nonnegative integer; fractional or malformed values are rejected.
yearInteger-compatibleYesTarget calendar year. No range validation. Must be a nonnegative integer; fractional or malformed values are rejected.
userIDInteger-compatibleYesUser ID. This endpoint does not validate user existence.
monthInteger-compatibleYesZero-based month: 0 January through 11 December. Values outside that range or non-integers are rejected.
targetInteger-compatibleYesInteger fitting the signed 32-bit column; negative values are permitted. Fractional or malformed values are rejected.

Example request

$result = FM_api('ReportsTarget_setTarget', ['userID'=> '7','type'=> '0','year'=> '2026','month'=> '0','target'=> '1250']);

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: type"}Required type is absent or invalid.
{"error":"missing or invalid parameter: year"}Required year is absent or invalid.
{"error":"missing or invalid parameter: userID"}Required userID is absent or invalid.
{"error":"missing or invalid parameter: month"}Required month is absent or invalid.
{"error":"missing or invalid parameter: target"}Required target is absent or invalid.
{"error":"no permission to access api"}Employer feature bit 8192 is unset.
{"error":"reporting write failed"}A database write failed. Transactional operations roll back instead of returning success.
{"error":"target is not existing."}No active month matches the requested identity.

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

Behaviour and edge cases

  • Every active matching row, including duplicates, is updated. Missing/deleted monthly rows return target is not existing.; no row is inserted.
  • userID=0 means literal user zero, not all users. Numeric inputs are validated and the value is bound to SQL.

Side effects

  • Updates active monthly target/edit times and invalidates the target cache transactionally. No history, notification, or recalculation occurs.

See it in Fieldmotion

CRM1

The Report Target page uses this endpoint for its monthly target cell edits. Filter browser Network requests for ReportsTarget_setTarget.

CRM2

Report Targets classic/new editors use this endpoint for single or bulk monthly-cell changes. Filter browser Network requests for ReportsTarget_setTarget.

Related endpoints