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.

Note

These endpoints are available only to tokens whose user can read the org chart (the company-role.read permission). A token without it receives 403.

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",
      "dueDate": { "type": "relative", "fixedDate": null, "relativeDays": 30, "anchor": "role_assignment_date" },
      "retrainingOverride": { "type": "recurring", "intervalDays": 365, "completionMode": "changed_material" }
    },
    {
      "type": "topic",
      "id": "t_91ab...",
      "name": "Maintenance plans",
      "dueDate": { "type": "none", "fixedDate": null, "relativeDays": null, "anchor": null },
      "retrainingOverride": null
    }
  ],
  "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}.
curriculum[].dueDate	object	When the item is due for a person in the role. type is none, fixed or relative. A fixed deadline carries fixedDate. A relative one carries relativeDays and an anchor (assignment_date, enrollment_date, employment_start, role_assignment_date or first_login), and has no single date until it is applied to a person.
curriculum[].retrainingOverride	object | null	The role’s own retraining rule for the item, which replaces the item’s default completely. null when the role defers to the item’s default policy. An object with type: "none" means the role has said never to retake it, which is different from deferring.
members[]	object	Each holder’s id and name.

List a role’s duties

GET /v1/company-roles/{id}/duties

Everything this role answers for, from the holder’s side. The duties endpoint answers the opposite question: who answers for a given topic. Needs raci-assignment.read as well as access to the org chart, as the duty list on the role’s page does.

Query parameters

Parameter	Type	Notes
entityType	string	TOPIC, ITEM, SPACE, or CATEGORY. Worth using: a duty on a topic reaches every item on it, so an unfiltered list is mostly items.
cursor	string	Pagination cursor from a previous response.
limit	number	1–100. Default 50.

Request

curl "https://api.mereon.ai/v1/company-roles/695690de/duties?entityType=TOPIC" \
  -H "Authorization: Bearer $MEREON_TOKEN"

Response

{
  "data": [
    {
      "role": "ACCOUNTABLE",
      "entityType": "TOPIC",
      "entityId": "top_9f2a...",
      "entityName": "Expense approval",
      "inheritedFrom": { "entityType": "SPACE", "entityId": "spc_4c81..." },
      "tierQualifier": "MIN_TIER",
      "advancementTierId": "tier_7a12...",
      "advancementTierLabel": "Senior",
      "assignmentId": "ras_71b3...",
      "source": "MANUAL",
      "confidence": null,
      "learningPriorityOverride": null,
      "url": "https://mereon.ai/topics/expense-approval"
    }
  ],
  "nextCursor": null
}

Field	Type	Notes
role	string	RESPONSIBLE, ACCOUNTABLE, CONSULTED, or INFORMED.
entityName	string	Resolved so the row stands alone. Duties on entities no longer in the live graph are omitted, so this is always present.
inheritedFrom	object | null	The ancestor the duty reaches this entity through, or null when assigned directly. A duty on a space is reported against each topic in it.
tierQualifier	string	How far the duty reaches across the role’s advancement path: ALL, MIN_TIER, MAX_TIER, or EXACT_TIER. ALL when the role has no path.
advancementTierLabel	string | null	The tier the qualifier refers to, when one applies.
assignmentId	string	The assignment behind this duty. For an inherited duty it is the parent’s assignment, not one on the entity named.
source	string	Who set the duty: MANUAL for a person’s own assignment, or AI_ENHANCED or AI_CLASSIFIED for the system’s suggestion.
confidence	number | null	How sure the suggestion was, from 0 to 1. null for a person’s own assignment.
learningPriorityOverride	string | null	This duty’s own learning priority (CRITICAL, HIGH, MEDIUM, or LOW). null means the topic’s priority applies.

Caution

This lists duties assigned to the role. It does not include company-wide policies the role’s holders also carry — a duty given to everyone in the organization, or to every internal or external role, is held by the organization rather than by any one role, so it will not appear here even though the people in this role answer for it.

Rows are ordered by entity type then name, and the list is limited to entities the caller can read. A duty held at the space or category level expands to one row per descendant, so it can be long — which is what entityType is for.

Get the org chart

GET /v1/org-chart

The whole chart in one call: every role with the role it reports to, the people who currently hold it, and whether it is vacant. Use it to answer “who holds this role?” or “which roles are unfilled?” without reading each role in turn.

Rebuild the tree by matching each role’s reportsToRoleId to an id in the same list. A role at the top has reportsToRoleId: null. Someone who has left the organization does not count as holding a role, so a seat only they held reads as vacant.

Request

curl "https://api.mereon.ai/v1/org-chart" \
  -H "Authorization: Bearer $MEREON_TOKEN"

Response

{
  "data": [
    {
      "id": "695690de-1c49-42c7-a416-b0d3bea29102",
      "name": "Service Manager",
      "reportsToRoleId": "1c0f8b2a-7d34-4e91-bf02-3a5d9c6e8f10",
      "holders": [
        { "id": "usr_2d9e...", "name": "Ada Admin", "email": "ada@example.com" }
      ],
      "vacant": false
    }
  ],
  "nextCursor": null
}

The chart is not paginated, so nextCursor is always null. This is the chart of roles. Who answers to whom is a separate question, answered for the connected user below.

Get your reporting line

GET /v1/me/reporting-line

The roles the connected user holds, the person they report to, and the people who report to them.

Two people who share a title are not each other’s managers, because the people come from the manager each person has been given and not from the role tree. managers has at most one entry. It is a list so the shape does not change if dotted lines are ever supported. Only people who are currently employed are listed.

Response

{
  "myRoles": [{ "id": "695690de-1c49-42c7-a416-b0d3bea29102", "name": "Service Manager" }],
  "managers": [
    {
      "employeeId": "emp_81c2...",
      "userId": "usr_44aa...",
      "name": "Grace Hopper",
      "email": "grace@example.com",
      "roleNames": ["Operations Director"]
    }
  ],
  "directReports": []
}

Field	Type	Notes
employeeId	string	Always present. A manager need not have a login.
userId	string | null	null for someone who has never signed in.
roleNames	string[]	May be empty. A role says what someone does, not who manages them.