> ## 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 an agency member's approved roles

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

Lists only the selected approved agency member's approved roles, including limited-access roles. The bearer key authorizes delegation within its own agency; recruiterEmail is required and is revalidated on every request. This is not an agency-wide union or a marketplace search, and it does not depend on talent-network membership.

Defaults to active roles and 50 results; the maximum page size is 100. Paused and closed history is supported. Ordered by the role row's update time descending, then role ID descending. Cursors are bound to the agency, member, and normalized filters, not a frozen snapshot. Confidentiality filtering can produce a partial or empty page; continue until nextCursor is null.

Only the permitted company name is returned. Candidate base salary remains available, without currency conversion; null currency means unknown. Recruiter rewards, fees, commissions, bonuses, role types, and candidate/application histories are not returned. Approval is not proof that a particular candidate can be submitted.

## Query parameters

<ParamField query="recruiterEmail" type="string" required>
  Email of a currently approved member of the authenticated agency. Selects that member's permissions; it does not authenticate the person holding the key.
  Constraints: format `email`, max length 254.
</ParamField>

<ParamField query="query" type="string">
  Search permitted role titles and company display names within this member's approved roles.
  Constraints: min length 1, max length 200.
</ParamField>

<ParamField query="primaryOnly" type="string">
  Use true or false. Defaults to false; true restricts to approved FULL-access primary slots.
  Allowed values: `true`, `false`.
</ParamField>

<ParamField query="status" type="string" default={"ACTIVE"}>
  CLOSED includes hired and churned roles. Pending, rejected, and disqualified roles are not exposed.
  Allowed values: `ACTIVE`, `PAUSED`, `CLOSED`.
</ParamField>

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

<ParamField query="cursor" type="string">
  Opaque continuation token. Reuse with the same agency, recruiter, query, primaryOnly, and status.
  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>
  </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/agency/roles?recruiterEmail=jane@example.com&status=ACTIVE&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"
      }
    ],
    "nextCursor": "string"
  }
  ```
</ResponseExample>


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