> ## 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 and read a full brief

> Find roles you can work on, filter them, and pull a role's full brief.

Both endpoints need a personal key with `roles:read`.

## Browse roles

[`GET /recruiter/roles`](/recruiter/api-reference/list-recruiter-roles) returns the roles you can see on Paraform, in the same set and order as the in-app Browse page.

```bash theme={null}
curl -G "https://external-api.paraform.com/api/external/v1/recruiter/roles" \
  -H "Authorization: Bearer $PARAFORM_API_KEY" \
  --data-urlencode "query=founding engineer" \
  --data-urlencode "location=san_francisco" \
  --data-urlencode "location=new_york" \
  --data-urlencode "workplace=HYBRID" \
  --data-urlencode "minSalary=180000"
```

### Common filters

Every filter is optional. Filters combine with AND. An array filter matches any of its values, so repeat the parameter to send several.

| Parameter | Use |
| - | - |
| `query` | Typo-tolerant full-text search over the role and company |
| `location`, `workplace`, `roleType`, `talentDensity` | Only the keys listed on the [reference page](/recruiter/api-reference/list-recruiter-roles), for example `san_francisco`, `ON_SITE`, or `product_management`. A display name such as "San Francisco" returns `400` with the accepted values. |
| `industry`, `techStack`, `investors`, `roleTitles` | Further narrowing. `investors` matches names as case-insensitive substrings. |
| `minSalary`, `maxSalary` | Annual salary as whole numbers, compared to each role's salary band without currency conversion, to the nearest 1,000 |
| `primaryOnly=true` | Only roles where you hold a primary slot: the roles you're working on |
| `approvedOnly=true` | Every role where your approval is `APPROVED`, at any access level |
| `matchMyPreferences=true` | Adds your [saved preferences](/recruiter/guides/preferences) to the filters |

The [reference page](/recruiter/api-reference/list-recruiter-roles) lists every filter, including hiring-manager rating, responsiveness, active interviews, visa sponsorship, and posting age.

### What each role includes

| Field | What it tells you |
| - | - |
| `fee` | What the placement pays you. `percentOfSalary` is your rate. `null` amounts mean your agency hides payment from members. |
| `myRole` | Your approval, whether you hold a primary slot (`isPrimary`), your submission counts, and any trial (`trial.isActive`, `businessDaysLeft`) |
| `recruiterAccess` | How crowded the role is (`density` is `low`, `medium`, or `high`) and whether it's accepting recruiters |
| `pipeline` | Competition across all recruiters |
| `hiringManager` | Rating, responsiveness, and recency |
| `urls.recruit` | A link to the role on Paraform when you're on it. Otherwise use `urls.browse`. |

`myRole.isApproved` alone doesn't mean you can submit any candidate. `APPROVED` with `accessLevel` `CROSS_SUBMIT` is single-submission access, decided per candidate.

### Paging

A page holds at most 20 roles. Pass `nextCursor` back as `cursor` until it's absent. When anything about the search changes, start again without `cursor`: an old cursor doesn't fail, it silently skips rows. See [Pagination](/pagination).

## Read a full role brief

[`GET /recruiter/roles/{roleId}`](/recruiter/api-reference/get-recruiter-role) returns everything on the role page in one call. `roleId` is the `id` from the list.

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

| Field | Use it for |
| - | - |
| `summary` | The same row the list returns: fee, competition, and your slot |
| `about`, `requirements`, `candidateTraits`, `avoidTraits` | Screening |
| `hiringManagerQuestions` | The questions you must answer about a candidate when you submit |
| `interviewProcess` | The interview stages |
| `pitch` | Outreach: selling points, outreach guidelines and templates, recruiting advice, target companies, FAQs |
| `company` | The company pitch |
| `pipeline` | Anonymized pipeline and rejection patterns, plus your own recent submissions |

<Warning>
  When `company.confidentialSearch` is `true`, the search is confidential. Candidate-facing copy must refer to the employer as `company.anonymizedName` and must not name or identify the company.
</Warning>

`pipeline.mySubmissions` is capped at the 30 newest. For agency owners it also includes the agency's submissions, so don't treat its length as a total.

A role you can't work on returns `404`.


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