# 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.

```bash
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.

```bash
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

| Action | Endpoint | MCP tool |
| --- | --- | --- |
| People | `GET /v1/people` | `list_people` |
| Job roles | `GET /v1/job-roles` | `list_job_roles` |
| KPIs | `GET /v1/kpis` | `list_kpis` |
| KPI values | `GET /v1/kpis/{id}/values` | `get_kpi_values` |
| Record a KPI value | `PUT /v1/kpis/{id}/values/{period}` | `record_kpi_value` |
| Clear a KPI value | `DELETE /v1/kpis/{id}/values/{period}` | `clear_kpi_value` |

Every parameter is in the API reference under [People](https://developers.playbookops.ai/reference/people) and [KPIs](https://developers.playbookops.ai/reference/kpis).
