> ## 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 are working on

<Info>
  **Required scopes:** `roles:read`<br />
  **Rate limit:** `default` tier, 120 requests per minute per key
</Info>

The active roles you are working on: every role where you hold a primary slot (including one on trial), plus every role where you have an active submission, meaning a candidate you submitted who is submitted, reviewed, interviewing, or at offer stage. Paused and closed roles are not listed. To find new roles to work on, use listRecruiterRoles; for a role's full detail, use getRecruiterRole.

`primaryOnly`, `activeTrialOnly`, `singleSubmissionsOnly` and `paraAiOnly` narrow the list. When several are true, a role matching ANY of them is returned. `activeTrialOnly` matches a trial still inside its window whose submission goal is not yet met. `singleSubmissionsOnly` and `paraAiOnly` match whether or not you also hold a primary slot on the role.

Ordered by the role's last update, newest first, then role ID. Defaults to 50 roles; the maximum is 100. A page can hold fewer roles than `limit`, or none, while `nextCursor` is set; continue until `nextCursor` is null.

`fee` is what the placement pays you, the same figures listRecruiterRoles returns. Amounts are in `baseSalary.currency`; a null currency means it is not recorded. When your agency hides payment from its members, every `fee` field is null; agency owners always see fees. `fee` itself is null when the role's fee cannot be read through this endpoint.

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

## Query parameters

<ParamField query="primaryOnly" type="string">
  Use true or false. Defaults to false. True matches roles where you hold a primary slot.
  Allowed values: `true`, `false`.
</ParamField>

<ParamField query="activeTrialOnly" type="string">
  Use true or false. Defaults to false. True matches primary slots whose trial is still in progress. A trial ends when its window closes or its submission goal is met.
  Allowed values: `true`, `false`.
</ParamField>

<ParamField query="singleSubmissionsOnly" type="string">
  Use true or false. Defaults to false. True matches roles where you have an active single submission.
  Allowed values: `true`, `false`.
</ParamField>

<ParamField query="paraAiOnly" type="string">
  Use true or false. Defaults to false. True matches roles where you have an active submission made from a ParaAI match.
  Allowed values: `true`, `false`.
</ParamField>

<ParamField query="limit" type="integer" default={"50"}>
  Constraints: minimum 1, maximum 100.
</ParamField>

<ParamField query="cursor" type="string">
  Opaque continuation token. Reuse only with the same filters. Results are live, not a frozen snapshot.
  Constraints: min length 1, max length 2048.
</ParamField>

## Response

<ResponseField name="roles" type="object[]" required>
  <Expandable title="roles properties">
    <ResponseField name="id" type="string" required />

    <ResponseField name="title" type="string" required />

    <ResponseField name="company" type="object" required>
      <Expandable title="company properties">
        <ResponseField name="name" type="string" required />
      </Expandable>
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Allowed values: `ACTIVE`, `PAUSED`, `CLOSED`.
    </ResponseField>

    <ResponseField name="locations" type="string[]" required />

    <ResponseField name="workplaceType" type="string | null" required>
      Allowed values: `REMOTE`, `HYBRID`, `ON_SITE`.
    </ResponseField>

    <ResponseField name="baseSalary" type="object | null" required>
      Annual candidate base salary in whole currency units, without conversion. Null currency is unknown, not implicitly USD.

      <Expandable title="baseSalary properties">
        <ResponseField name="currency" type="string | null" required />

        <ResponseField name="min" type="integer | null" required />

        <ResponseField name="max" type="integer | null" required />
      </Expandable>
    </ResponseField>

    <ResponseField name="updatedAt" type="string" required>
      Constraints: format `date-time`.
    </ResponseField>

    <ResponseField name="fee" type="object | null" required>
      Null when this role's fee cannot be read here. Every field is null when your agency hides payment from members.

      <Expandable title="fee properties">
        <ResponseField name="amountLowerBound" type="number | null" required />

        <ResponseField name="percentOfSalary" type="number | null" required />

        <ResponseField name="boostPercent" type="number | null" required />

        <ResponseField name="bonusAmount" type="number | null" required />

        <ResponseField name="firstSubmissionReward" type="number | null" required />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="nextCursor" type="string | null" required />

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://external-api.paraform.com/api/external/v1/recruiter/active-roles?limit=50" \
    -H "Authorization: Bearer $PARAFORM_API_KEY"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "roles": [
      {
        "id": "string",
        "title": "string",
        "company": {
          "name": "string"
        },
        "status": "ACTIVE",
        "locations": [
          "string"
        ],
        "workplaceType": "REMOTE",
        "baseSalary": {
          "currency": "string",
          "min": 0,
          "max": 0
        },
        "updatedAt": "2024-01-01T00:00:00.000Z",
        "fee": {
          "amountLowerBound": 0,
          "percentOfSalary": 0,
          "boostPercent": 0,
          "bonusAmount": 0,
          "firstSubmissionReward": 0
        }
      }
    ],
    "nextCursor": "string"
  }
  ```
</ResponseExample>


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