Fieldmotion API Getting started

Reporting dashboards and targets

Create twelve monthly user targets

POST /a/ReportsTarget_new

Initialize January–December target rows for a selected user or all active users.

When to use this endpoint

Choose a target type, year, and user in Report Targets, then initialize the annual rows here. Use the month setter for later changes; creation skips users who already have any matching 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-compatibleYesExisting selected user ID, or 0 for all active=1 users. A selected existing user need not be active. User IDs and other numeric fields must be integer-compatible, not SQL expressions.
startTargetInteger-compatibleNoJanuary target, default zero. Must be an integer fitting the signed target column; negative values are permitted.
progressionInteger-compatible percentNoDefault zero; must be an integer percentage. Each month adds the fixed startTarget × abs(progression/100), not a compounded percentage.

Example request

$result = FM_api('ReportsTarget_new', ['userID'=> '7','type'=> '0','year'=> '2026','startTarget'=> '1000','progression'=> '10']);

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":"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.

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

Behaviour and edge cases

  • Months are zero-based 0..11. With the example, targets are 1000, 1100, …, 2100. Fractional progression is rejected; a negative integer percentage still increases by its magnitude. Targets are truncated to integer values and must fit the signed integer column.
  • Any existing active month still skips that entire user/year/type; initialization does not fill holes or overwrite existing annual targets. Deleted rows do not block new initialization.
  • Selected user rows are locked during the precheck and inserts, serializing concurrent initialization for those users. The whole request commits or rolls back together.
  • Numeric inputs are validated and SQL values bound/coerced. Missing selected users or failed writes return errors.

Side effects

  • Inserts twelve rows per eligible user with creation/edit times and cache invalidation in one transaction. No activity, notification, or report calculation occurs.

See it in Fieldmotion

CRM1

The Report Target page uses this endpoint for its Add action. Filter browser Network requests for ReportsTarget_new.

CRM2

Report Targets classic/new editors use this endpoint for annual initialization. Filter browser Network requests for ReportsTarget_new.

Related endpoints