People and KPIs

Who's in the organization, their job roles, and how your KPIs are tracking, plus recording KPI values.

People

GET /v1/people?search=ana needs people:read. It lists active people with their job title, role, manager and teams. Use a person's id as assignee_id when adding or updating items and tasks.

GET /v1/job-roles lists the organization's job roles, who holds each, and how many responsibilities it has.

KPIs

With kpis:read, a key sees the KPIs its owner can see in the app.

curl https://developers.playbookops.ai/v1/kpis \
  -H "Authorization: Bearer $PLAYBOOKOPS_API_KEY"

curl "https://developers.playbookops.ai/v1/kpis/KPI_ID/values?since=2026-01-01&until=2026-06-30" \
  -H "Authorization: Bearer $PLAYBOOKOPS_API_KEY"

Each KPI has a unit, a frequency, a goal, and a goal_direction of above or below, saying which side of the goal is on track. Values come one per period, with the period_start date and any note.

Weekly KPI digest

List the KPIs, fetch the last two values of each, and compare them with goal and goal_direction to post which ones are on track and which are slipping.

Recording values

With kpis:write, a key records a value the same way its owner would on the scorecard: only for KPIs they own (or any KPI, for an org admin), and only for KPIs entered by hand, not ones PlaybookOps works out itself.

curl -X PUT https://developers.playbookops.ai/v1/kpis/KPI_ID/values/2026-11-12 \
  -H "Authorization: Bearer $PLAYBOOKOPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"value": 42, "note": "Two large renewals"}'

The date in the path can be any day in the period; the answer's period_start says which period it went to, the Monday for a weekly KPI or the 1st for a monthly one. Sending a value for a period that already has one replaces it, note included, so the same request is safe to repeat. Future periods aren't allowed.

DELETE /v1/kpis/KPI_ID/values/2026-11-12 clears a period's value and note, so it shows as not entered, with the same rules.

Sync from another system

Run a job after each period closes that reads the number from your CRM or spreadsheet and records it here, so the scorecard is filled in before the weekly meeting.

Reference

ActionEndpointMCP tool
PeopleGET /v1/peoplelist_people
Job rolesGET /v1/job-roleslist_job_roles
KPIsGET /v1/kpislist_kpis
KPI valuesGET /v1/kpis/{id}/valuesget_kpi_values
Record a KPI valuePUT /v1/kpis/{id}/values/{period}record_kpi_value
Clear a KPI valueDELETE /v1/kpis/{id}/values/{period}clear_kpi_value

Every parameter is in the API reference under People and KPIs.