> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kombo.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Roles

> Understanding system roles and job roles in ATS integrations

Roles define what a person is allowed to do in an ATS. Kombo syncs these roles and exposes them through a unified schema so you can build permissions-aware features without worrying about the differences between ATS systems.

## What are roles?

A **role** represents a function or permission level assigned to a user in an ATS. Roles control what users can see, edit, and manage — both globally and within the context of a specific job.

Here are typical roles you'll encounter:

* **Admin** — Full system access, can configure settings and manage all users
* **Recruiter** — Manages candidate pipelines and coordinates the hiring process
* **Hiring Manager** — Oversees hiring for specific positions, reviews and approves candidates

Kombo syncs all roles and always returns how the role is called with the `remote_label` field.
Additionally, Kombo tries to categorize the role. For example, the role of "Administrator" is categorized as `unified_type: "ADMIN"`.
There are some cases, where the `unified_type` can be `null`, for example: Some built-in roles (e.g., "Onboarding Owner") simply don't have a corresponding unified type (yet). Or the customer has defined custom roles in their ATS (e.g., "Hiring Wizard").

## Job roles vs system roles

ATS systems typically assign roles at two levels:

|                    | System roles                                   | Job roles                                                   |
| ------------------ | ---------------------------------------------- | ----------------------------------------------------------- |
| **Scope**          | Entire ATS instance                            | Single job                                                  |
| **Purpose**        | Control platform-wide permissions              | Define hiring team responsibilities                         |
| **Example**        | "Admin" — can configure settings for all users | "Hiring Manager" — responsible for a specific open position |
| **Where in Kombo** | `system_roles` on `/ats/users`                 | `job_roles` on hiring team members in `/ats/jobs`           |

A single user can have both: they might be an **Admin** system-wide and a **Hiring Manager** for a specific job.

## ATS systems

How roles work varies across ATS platforms. Here are the common approaches:

* **Predefined roles:** The ATS provides a fixed set of roles (e.g., Admin, Recruiter, Hiring Manager) that cannot be customized. These map cleanly to Kombo's unified types.

* **Customizable roles:** The ATS allows creating custom roles with granular permissions. Kombo syncs all roles. Well-known ones are categorized with a `unified_type`. Custom roles are passed through with `unified_type: null` and the original label in `remote_label`.

* **Implicit roles:** Some ATS don't have an explicit roles system. Instead, adding someone as a "Hiring Manager" on a job implicitly assigns them that role. Kombo still normalizes this into the same `job_roles` structure.

<Frame caption="Greenhouse introduces three system roles: Basic, Job Admin and Site Admin">
  <img src="https://mintcdn.com/kombo/iU5GCoohmwFDEBg0/images/ats-roles/greenhouse-system-roles.png?fit=max&auto=format&n=iU5GCoohmwFDEBg0&q=85&s=43a40e1812e32f48b2e275c864f63c10" width="2036" height="414" data-path="images/ats-roles/greenhouse-system-roles.png" />
</Frame>

***

<Frame caption="Workable has more flexible setup, combining system roles and job roles">
  <img width="450px" src="https://mintcdn.com/kombo/iU5GCoohmwFDEBg0/images/ats-roles/workable-system-roles.png?fit=max&auto=format&n=iU5GCoohmwFDEBg0&q=85&s=d06af043b094ec74d089e1638ca5c91c" data-path="images/ats-roles/workable-system-roles.png" />
</Frame>

## Setup

### Scopes

The **Roles** scope is disabled by default. To start syncing roles, enable it in your [scope configuration](/ats/features/scopes). You also need the **Users** scope to be enabled, since all roles are connected to users.

<Frame caption="Enable Roles in scope">
  <img src="https://mintcdn.com/kombo/iU5GCoohmwFDEBg0/images/ats-roles/scope-roles.png?fit=max&auto=format&n=iU5GCoohmwFDEBg0&q=85&s=78e3ac89749ebdd23e6da58b67ac869d" width="1590" height="244" data-path="images/ats-roles/scope-roles.png" />
</Frame>

### Roles endpoint

Use the [`GET /ats/roles`](/ats/v1/get-roles) endpoint to list all roles defined in the connected ATS. You can filter by scope to get only system-level or job-level roles.

```json [expandable] theme={null}
// GET /ats/roles
{
  "status": "success",
  "data": {
    "next": null,
    "results": [
      {
        "id": "26vafvWSRmbhNcxJYqjCzuJg",
        "remote_id": "101",
        "remote_label": "Admin",
        "scope": "SYSTEM",
        "unified_type": "ADMIN",
        "remote_data": null,
        "changed_at": "2024-11-07T14:00:00.000Z",
        "remote_deleted_at": null
      },
      {
        "id": "7yNRgs4cGFpUfhwbGBDaB5Gk",
        "remote_id": "202",
        "remote_label": "Recruiter",
        "scope": "JOB",
        "unified_type": "RECRUITER",
        "remote_data": null,
        "changed_at": "2024-11-07T14:00:00.000Z",
        "remote_deleted_at": null
      },
      {
        "id": "4kTPJfmNaQdhzRCVLd83FYWJ",
        "remote_id": "203",
        "remote_label": "Hiring Wizard",
        "scope": "JOB",
        "unified_type": null,
        "remote_data": null,
        "changed_at": "2024-11-07T14:00:00.000Z",
        "remote_deleted_at": null
      }
    ]
  }
}
```

<Note>
  Above, you see that this customer has one role on the system level ("Admin")
  and two on the job level ("Recruiter", "Hiring Wizard").

  The role of "Admin" and "Recruiter" are categorized in the `unified_type` of
  `ADMIN` and `RECRUITER`.

  However Kombo does not know how to categorize the "Hiring Wizard" role, so the
  `unified_type` is `null`.
</Note>

### Job roles

When [reading jobs](/ats/v1/get-jobs), each hiring team member includes a `job_roles` array showing what roles they have for that specific job.

```json {13-26} [expandable] theme={null}
// GET /ats/jobs
{
  "status": "success",
  "data": {
    "results": [
      {
        "id": "8VkMaFnDx4gNRFfraFgnLbVp",
        "name": "Backend Engineer",
        "hiring_team": [
          {
            "first_name": "John",
            "last_name": "Doe",
            "job_roles": [
              {
                "remote_id": "202",
                "remote_label": "Recruiter",
                "scope": "JOB",
                "unified_type": "RECRUITER"
              },
              {
                "remote_id": "203",
                "remote_label": "Hiring Wizard",
                "scope": "JOB",
                "unified_type": null
              }
            ]
          }
        ]
      }
    ]
  }
}
```

<Warning>
  The `hiring_team_roles` field on hiring team members is deprecated. Use
  `job_roles` instead — it provides the full list of roles including custom ones
  and the original remote label.
</Warning>

### System roles

When [reading users](/ats/v1/get-users), each user includes a `system_roles` array showing their platform-wide roles.

```json {8-15} [expandable] theme={null}
// GET /ats/users
{
  "status": "success",
  "data": {
    "results": [
      {
        "id": "26vafvWSRmbhNcxJYqjCzuJg",
        "system_roles": [
          {
            "remote_id": "101",
            "remote_label": "Admin",
            "scope": "SYSTEM",
            "unified_type": "ADMIN"
          }
        ]
      }
    ]
  }
}
```

## FAQ

### How do I check if a user is an admin?

Look at the `system_roles` array on the user object from `/ats/users`. If any role has `unified_type` set to `"ADMIN"`, the user has admin-level access.

### Can a user have multiple roles?

Yes. A user can have multiple system roles and multiple job roles on different jobs. For example, someone could be both an Admin and a Manager system-wide and a Hiring Manager on a specific job.

### What if a role doesn't have a `unified_type`?

This means the role is custom or doesn't map to one of Kombo's unified types. Use the `remote_label` field to identify what the role is.

### What tools are supported?

You can find a detailed overview of supported ATS platforms in the [ATS coverage grid](https://app.kombo.dev/coverage/ats) on your dashboard.

If you need support for an additional ATS, please contact us to request coverage.