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

# List the roles you're working on

> Get every role where you hold a primary slot or have a candidate in process, and narrow it by how you're working on each one.

[`GET /recruiter/active-roles`](/recruiter/api-reference/list-recruiter-active-roles) returns the active roles you're working on. You need a personal key with `roles:read`.

```bash theme={null}
curl "https://external-api.paraform.com/api/external/v1/recruiter/active-roles" \
  -H "Authorization: Bearer $PARAFORM_API_KEY"
```

A role is on the list when either is true:

* **You hold a primary slot on it**, including a slot that's still on trial.
* **You have a candidate in process on it**: a candidate you submitted who is submitted, reviewed, interviewing, or at offer stage. This counts single submissions, submissions from ParaAI matches, and candidates still in process on a role where you no longer hold a slot.

Paused and closed roles aren't listed. To find new roles to work on, use [Browse roles](/recruiter/guides/browse-roles) instead.

## Narrow the list

| Parameter | Returns |
| - | - |
| `primaryOnly=true` | Roles where you hold a primary slot |
| `activeTrialOnly=true` | Primary slots whose trial is still in progress. A trial ends when its window closes or you meet its submission goal. |
| `singleSubmissionsOnly=true` | Roles where you have a single submission in process |
| `paraAiOnly=true` | Roles where you have a candidate in process from a ParaAI match |

Every filter defaults to `false`. When you set more than one, you get roles matching **any** of them. For example, this returns every role where you have a single submission or a ParaAI submission in process:

```bash theme={null}
curl "https://external-api.paraform.com/api/external/v1/recruiter/active-roles?singleSubmissionsOnly=true&paraAiOnly=true" \
  -H "Authorization: Bearer $PARAFORM_API_KEY"
```

`singleSubmissionsOnly` and `paraAiOnly` match a role whether or not you also hold a primary slot on it. Unknown parameters and values other than `true` or `false` return `400`.

## What each role includes

Each role has its `id`, `title`, `company.name`, `status`, `locations`, `workplaceType`, `baseSalary`, `updatedAt`, and `fee`. For the full brief, call [`GET /recruiter/roles/{roleId}`](/recruiter/guides/browse-roles) with the role's `id`.

`fee` is what the placement pays you, the same figures as `GET /recruiter/roles`:

* If your agency hides payment from its members, every `fee` field is `null`. Agency owners always see fees.
* `fee` itself is `null` when a role's fee can't be read through this endpoint.

A confidential stealth role you aren't assigned to shows its company as "Confidential (Stealth)", with the company name removed from its title and locations.

## Paging

Roles come back most recently updated first. `limit` defaults to 50, and the maximum is 100. A `limit` above 100 returns `400`.

With `activeTrialOnly`, trials whose window has ended are removed after a page is read, so a page can be short or empty while `nextCursor` is still set. Keep going until `nextCursor` is `null`. See [Pagination](/pagination).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.