Skip to main content

Add Goal Reading

POST 
/api/success-plan/goals/:goal/readings

Records a new value you entered on a goal (a C reading). Earlier readings are kept. When the value reaches the target, the goal becomes met.

Required scope: success_plan:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Authentication: Requires Bearer token with the success_plan:write scope. The user must hold the success_plan.manage permission.

Send the fields at the top level (or nested under reading). The same rules apply as for a baseline.

Fields:

  • value (number): the figure. Required unless use_measured / use_imported is true, or the unit is hours_per_week (send roles) or boolean (send value_bool). 0–100 for percentage units; zero or more for counts, units and days.
  • value_bool (boolean): yes / no for boolean goals.
  • roles (array, 1–20): hours by role for hours_per_week goals; each row is role (string, required, max 60) and hours_per_week (number 0–168, required). The value is the total. Not allowed on other units.
  • as_of (date, Y-m-d): when the figure was true. Required with a typed value; never in the future; at most 365 days back (in retrospective mode, back to the start of the month before go-live).
  • evidence (string): how you know it: document, system_export or estimate (recall is also accepted in retrospective mode). Required with a typed value.
  • source_note (string, max 255): where the figure came from.
  • range_low, range_high (number): only with estimate or recall; required with recall. The value must sit inside the range.
  • confidence (string): high, medium or low; only with estimate or recall; required with recall.
  • attachment_ids (integer array, max 10): uploaded evidence files; only with document or system_export evidence.
  • use_measured (boolean): use SKU.io's measured figure for last month instead of a typed value (measured templates only).
  • use_imported (boolean): retrospective mode only; use orders imported from before go-live.

Returns the goal (201) with the new reading as latest. Refused writes answer 422 with a machine-readable code alongside the usual errors, where each error is {message, code}: max_active_goals (three active goals at most; archive one first), measured_baseline_unavailable, imported_baseline_unavailable, baseline_required, unit_not_allowed, goal_archived, goal_has_target.

409 goal_busy: SKU.io was measuring this goal and did not finish in time; nothing was saved, so retry shortly.

Request​

Responses​

Created

Response Headers
    Content-Type