Company roles

A company role is a named position in your organization’s org chart (for example “Service Manager”). Each role can have a training curriculum — the lessons and topics everyone in the role is expected to complete — and a set of members who currently hold it.

List company roles

GET /v1/company-roles

Lists the organization’s company roles, sorted alphabetically by name. Each result carries how many people hold the role and the role it reports to.

Query parameters

Parameter	Type	Notes
`query`	string	Case-insensitive match on the role name.
`cursor`	string	Pagination cursor from a previous response.
`limit`	number	1–100. Default 50.

Request

curl "https://api.mereon.ai/v1/company-roles?query=manager" \
  -H "Authorization: Bearer $MEREON_TOKEN"

Response

{
  "data": [
    {
      "id": "695690de-1c49-42c7-a416-b0d3bea29102",
      "name": "Service Manager",
      "description": "Supervises the field technician team and schedules work.",
      "memberCount": 2,
      "parentRoleId": "1c0f8b2a-7d34-4e91-bf02-3a5d9c6e8f10",
      "createdAt": "2026-02-01T10:00:00.000Z",
      "updatedAt": "2026-05-20T10:00:00.000Z"
    }
  ],
  "nextCursor": null
}

Field	Type	Notes
`description`	string \| null	The role’s description, if set.
`memberCount`	number	How many people currently hold the role.
`parentRoleId`	string \| null	The role this one reports to; `null` at the top of the chart.

Get a company role

GET /v1/company-roles/{id}

Role detail: the summary fields plus the role’s training curriculum (the lessons and topics everyone in the role must complete) and its current members. Returns 404 if the role is not visible to you.

Response

{
  "id": "695690de-1c49-42c7-a416-b0d3bea29102",
  "name": "Service Manager",
  "description": "Supervises the field technician team and schedules work.",
  "memberCount": 2,
  "parentRoleId": "1c0f8b2a-7d34-4e91-bf02-3a5d9c6e8f10",
  "createdAt": "2026-02-01T10:00:00.000Z",
  "updatedAt": "2026-05-20T10:00:00.000Z",
  "curriculum": [
    { "type": "lesson", "id": "lsn_6e3f...", "name": "Scheduling and dispatch" },
    { "type": "topic", "id": "t_91ab...", "name": "Maintenance plans" }
  ],
  "members": [
    { "id": "usr_44de...", "name": "Carla Field" }
  ]
}

Field	Type	Notes
`curriculum[].type`	string	`lesson` or `topic`.
`curriculum[].id`	string	The lesson or topic id. Resolve a lesson with `/v1/lessons/{id}`, a topic with `/v1/topics/{id}`.
`members[]`	object	Each holder’s `id` and `name`.