> ## 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.

# Browse roles you can work on

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

The roles the calling recruiter can see on Paraform, the same set and the same ordering as the in-app Browse page.

Every filter is optional and they combine with AND. Array filters match ANY of the values given; pass a filter more than once to send several values. `query` is a full-text search over the role and company that tolerates typos. `minSalary` and `maxSalary` are whole numbers of annual salary, compared to each role's salary band as stored, with no currency conversion, and matched to the nearest 1,000. A bound above 999,000 is read as 999,000. `compensation.salaryLowerBound`, `salaryUpperBound` and `fee.amountLowerBound` are in `compensation.currency` when it is set; when it is null the currency is not recorded, so it is not necessarily dollars.

`location`, `roleType`, `workplace` and `talentDensity` take ONLY the keys listed in this schema (for example `san_francisco`, `product_management`, `ON_SITE`). A display name such as "San Francisco" or "Product Manager" is rejected with a 400 that names the field and lists the accepted values.

`primaryOnly` narrows to roles where you hold a primary slot: the roles you are working on. `approvedOnly` narrows to every role where your approval is APPROVED at any access level, primary or not; it is not a list of roles you can submit any candidate to. Both are much cheaper than paging the whole board and reading `myRole`. `investors` matches investor names as substrings, ignoring case, so `Y Combinator` and `combinator` both work.

Set `matchMyPreferences` to true to fold in the role types, locations, industries, funding rounds and minimum salary saved on your Paraform profile; read them with `getRecruiterPreferences`. Within one field the saved values are ADDED to the values you send, across fields the filters still combine with AND, and the salary floor is the higher of the two. The search drops a `maxSalary` below that floor, so the ceiling does not apply. To get only your preferences send this flag and no other filters.

Each role carries `fee` (what the placement pays), `pipeline` (competition across all recruiters), `recruiterAccess` (how crowded the role is), `hiringManager` (rating, responsiveness, recency) and `myRole` (your approval, whether you are primary, and your own submission counts). `fee.percentOfSalary` is the rate offered to you and `fee.amountLowerBound` is that rate at the bottom of the salary band. When your agency hides payment from its members, every `fee` amount is null.

`myRole.isApproved` is `approvalStatus` equal to APPROVED. `myRole.isPrimary` is that plus `accessLevel` FULL: you hold a primary slot and submit through the normal path. APPROVED with `accessLevel` CROSS\_SUBMIT is single-submission access: no primary slot, and whether a given candidate can go through is decided per candidate, so this flag alone does not mean you can submit. SUBMISSION\_REQUEST\_ONLY means only candidates a hiring manager specifically requested. `approvalStatus` null or anything other than APPROVED (PENDING, REJECTED, WITHDRAWN and so on) means you are not on the role; `urls.recruit` is null in that case.

`recruiterAccess.density` is `low`, `medium` or `high`: how much recruiter competition the role already has, the same tier the Browse page labels. Exact recruiter counts are not published. `atMaxCapacity` true means the role's count of pending, unreviewed submissions has reached Paraform's backlog threshold; it does not say whether you can submit. `notAcceptingRecruiters` true means the role does not let recruiters join by themselves and you are not on it, so you cannot self-serve onto it right now.

`hiringManager.responsivenessDays` is a weighted average of response times in days; a metric with no data counts as 0, so a very low value can mean little history rather than a fast hiring manager. `hiringManager.engagement.finalRating` runs 3.5 to 5.0 and `percentileRank` 0 to 100 against other hiring managers; both are null until the role has enough submissions to rate.

`myRole.trial` is set on a primary slot that is on trial. `isActive` true means the goal is not yet met inside the window; `endingSoon` true means the slot is about to be withdrawn. To find slots about to be lost, request `primaryOnly` and keep every role whose `trial.isActive` is true, sorted by `businessDaysLeft`. `submissionGoal` and `submissionsCounted` are the trial target and your progress toward it, `endsAt` the deadline, and `businessDaysLeft` the same countdown the app shows. The response keeps the Browse order.

PAGING: one response is ONE page of at most 20 roles, not the whole board. `nextCursor` present means more roles match; absent means this page was the last. `cursor` is a position inside the result list for one exact set of filters. When anything about the search changes (a different `query`, a filter added, removed or changed), start a NEW search with no `cursor`; reusing a cursor from a different search does not fail, it silently skips rows. An empty `roles` array on a fresh first page (no `cursor`) means nothing matched those filters, not that no roles exist. An empty page reached with a `cursor` only means there are no more rows at that position.

Each row is a summary. `getRecruiterRole` with the row's `id` returns the description, requirements, hiring manager questions, interview stages and recruiting advice.

Roles nobody can self-serve onto, and roles whose hiring manager has stopped reviewing, are left out, matching the in-app Browse page.

`urls.recruit` links to the role on Paraform, and `urls.browse` does when recruit is null. Paraform URLs are not guaranteed to be derivable from an id.

## Query parameters

<ParamField query="query" type="string">
  Constraints: min length 1.
</ParamField>

<ParamField query="cursor" type="integer | null" default={"0"}>
  The `nextCursor` of the previous page. Omit for the first page.
  Constraints: minimum 0.
</ParamField>

<ParamField query="limit" type="integer" default={"20"}>
  Constraints: minimum 1.
</ParamField>

<ParamField query="location" type="string | string[]">
  <Expandable title="21 allowed values">
    `new_york`, `san_francisco`, `south_bay_area`, `los_angeles`, `boston`, `seattle`, `texas`, `chicago`, `europe`, `latam`, `korea`, `canada`, `australia`, `india`, `uk`, `washington_dc`, `asia`, `denver`, `florida`, `minnesota`, `sacramento`
  </Expandable>
</ParamField>

<ParamField query="workplace" type="string | string[]">
  Allowed values: `REMOTE`, `ON_SITE`, `HYBRID`.
</ParamField>

<ParamField query="roleType" type="string | string[]">
  <Expandable title="83 allowed values">
    `backend_engineer`, `frontend_engineer`, `full_stack_engineer`, `mobile_engineer`, `infrastructure_devops_sre`, `security_engineer`, `forward_deployed_engineer_solutions_support`, `robotics_software_engineer`, `robotics_platform_engineer`, `sales_solutions_engineer`, `qa_test_engineering`, `blockchain_protocol_engineer`, `developer_relations_advocacy`, `founding_engineer`, `product_engineer`, `embedded_firmware_engineer`, `mechanical_engineer`, `electrical_engineer`, `robotics_hardware_engineer`, `aerospace_flight_engineer`, `machine_learning_engineer`, `robotics_ml_engineer`, `data_engineer`, `data_science_analytics`, `computer_vision_engineer`, `research_scientist_applied_research`, `ai_ml_researcher`, `research_engineer_applied_research`, `data_scientist_applied_scientist`, `machine_learning_infrastructure`, `machine_learning_ops_platform`, `research_scientist`, `research_engineer`, `ai_engineer`, `product_management`, `product_design_ux_ui`, `brand_visual_design`, `marketing_growth`, `growth_engineer`, `growth_marketing`, `demand_generation`, `performance_paid_media`, `lifecycle_crm_email`, `seo_organic_growth`, `marketing_ops_analytics`, `product_marketing`, `customer_marketing`, `content_marketing`, `brand_marketing`, `social_media_influencer`, `communications_pr`, `events_field_marketing`, `marketing_leadership`, `founding_marketer_generalist`, `account_executives_sales`, `account_management_customer_success`, `business_development`, `sales_development_rep`, `customer_technical_support`, `content_copywriting`, `sales_gtm_leadership`, `partnerships`, `operations_strategy`, `robotics_operations_engineer`, `revenue_operations`, `finance_accounting`, `people_talent`, `chief_of_staff`, `program_project_management`, `executive_assistant`, `data_analyst`, `engineering_leadership`, `executive_leadership`, `clinical_healthcare`, `legal_compliance_officer`, `legal_operations`, `legal_compliance`, `legal_partner`, `legal_counsel`, `legal_associate`, `legal_in_house_counsel`, `legal_paralegal`, `legal_admin`
  </Expandable>
</ParamField>

<ParamField query="industry" type="string | string[]" />

<ParamField query="techStack" type="string | string[]" />

<ParamField query="talentDensity" type="string | string[]">
  Allowed values: `S_PLUS`, `S`, `A`, `B`, `C`.
</ParamField>

<ParamField query="minSalary" type="integer | null">
  Constraints: minimum 0.
</ParamField>

<ParamField query="maxSalary" type="integer | null">
  Constraints: minimum 0.
</ParamField>

<ParamField query="minYearsExperience" type="integer | null">
  Constraints: minimum 0.
</ParamField>

<ParamField query="maxYearsExperience" type="integer | null">
  Constraints: minimum 0.
</ParamField>

<ParamField query="matchMyPreferences" type="string">
  Allowed values: `true`, `false`.
</ParamField>

<ParamField query="currentlyInterviewing" type="string">
  Allowed values: `true`, `false`.
</ParamField>

<ParamField query="approvedOnly" type="string">
  Allowed values: `true`, `false`.
</ParamField>

<ParamField query="primaryOnly" type="string">
  Allowed values: `true`, `false`.
</ParamField>

<ParamField query="investors" type="string | string[]" />

<ParamField query="roleTitles" type="string | string[]" />

<ParamField query="visaSponsorship" type="string">
  Allowed values: `available`, `not_available`.
</ParamField>

<ParamField query="minHiringManagerRating" type="number | null">
  Constraints: minimum 0.
</ParamField>

<ParamField query="maxResponsivenessDays" type="number | null">
  Constraints: minimum 0.
</ParamField>

<ParamField query="minActiveInterviews" type="integer | null">
  Constraints: minimum 0.
</ParamField>

<ParamField query="maxActiveInterviews" type="integer | null">
  Constraints: minimum 0.
</ParamField>

<ParamField query="postedWithinDays" type="integer">
  Constraints: minimum 1.
</ParamField>

## Response

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

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

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

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

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

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

        <ResponseField name="confidentialSearch" type="boolean" required />

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

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

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

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

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

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

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

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

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

    <ResponseField name="compensation" type="object" required>
      <Expandable title="compensation properties">
        <ResponseField name="salaryLowerBound" type="number" required />

        <ResponseField name="salaryUpperBound" type="number" required />

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

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

    <ResponseField name="experience" type="object" required>
      <Expandable title="experience properties">
        <ResponseField name="yearsMin" type="number" required />

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

    <ResponseField name="fee" type="object" required>
      <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>

    <ResponseField name="pipeline" type="object" required>
      <Expandable title="pipeline properties">
        <ResponseField name="totalApplications" type="number | null" required />

        <ResponseField name="totalInterviewing" type="number" required />

        <ResponseField name="totalHired" type="number" required />

        <ResponseField name="openingsText" type="string" required />
      </Expandable>
    </ResponseField>

    <ResponseField name="myRole" type="object" required>
      <Expandable title="myRole properties">
        <ResponseField name="isApproved" type="boolean" required />

        <ResponseField name="isPrimary" type="boolean" required />

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

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

        <ResponseField name="submissions" type="object" required>
          <Expandable title="submissions properties">
            <ResponseField name="submitted" type="number" required />

            <ResponseField name="interviewing" type="number" required />

            <ResponseField name="hired" type="number" required />

            <ResponseField name="total" type="number" required />
          </Expandable>
        </ResponseField>

        <ResponseField name="trial" type="object | null" required>
          <Expandable title="trial properties">
            <ResponseField name="endsAt" type="string | null" required />

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

            <ResponseField name="submissionGoal" type="number" required />

            <ResponseField name="submissionsCounted" type="number" required />

            <ResponseField name="isActive" type="boolean" required />

            <ResponseField name="endingSoon" type="boolean" required />
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="recruiterAccess" type="object" required>
      <Expandable title="recruiterAccess properties">
        <ResponseField name="atMaxCapacity" type="boolean" required />

        <ResponseField name="notAcceptingRecruiters" type="boolean" required />

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

    <ResponseField name="hiringManager" type="object" required>
      <Expandable title="hiringManager properties">
        <ResponseField name="lastActiveAt" type="string | null" required />

        <ResponseField name="responsivenessDays" type="number" required />

        <ResponseField name="engagement" type="object | null" required>
          <Expandable title="engagement properties">
            <ResponseField name="finalRating" type="number | null" required />

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

<ResponseField name="nextCursor" type="number" />

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

<ResponseExample>
  ```json 200 theme={null}
  {
    "roles": [
      {
        "id": "string",
        "name": "string",
        "postedAt": "string",
        "urls": {
          "browse": "string",
          "recruit": "string"
        },
        "company": {
          "name": "string",
          "confidentialSearch": true,
          "anonymizedName": "string",
          "oneLiner": "string",
          "industries": [],
          "size": 0
        },
        "locations": [
          "string"
        ],
        "workplaceType": "string",
        "roleTypes": [
          "string"
        ],
        "techStack": [
          "string"
        ],
        "visaText": "string",
        "compensation": {
          "salaryLowerBound": 0,
          "salaryUpperBound": 0,
          "currency": "string",
          "equity": "string"
        },
        "experience": {
          "yearsMin": 0,
          "yearsMax": 0
        },
        "fee": {
          "amountLowerBound": 0,
          "percentOfSalary": 0,
          "boostPercent": 0,
          "bonusAmount": 0,
          "firstSubmissionReward": 0
        },
        "pipeline": {
          "totalApplications": 0,
          "totalInterviewing": 0,
          "totalHired": 0,
          "openingsText": "string"
        },
        "myRole": {
          "isApproved": true,
          "isPrimary": true,
          "accessLevel": "string",
          "approvalStatus": "string",
          "submissions": {},
          "trial": {}
        },
        "recruiterAccess": {
          "atMaxCapacity": true,
          "notAcceptingRecruiters": true,
          "density": "string"
        },
        "hiringManager": {
          "lastActiveAt": "string",
          "responsivenessDays": 0,
          "engagement": {}
        }
      }
    ]
  }
  ```
</ResponseExample>


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