Browse roles and read a full brief

Both endpoints need a personal key with roles:read.

Browse roles

GET /recruiter/roles returns the roles you can see on Paraform, in the same set and order as the in-app Browse page.

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, 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 to the filters

The reference page 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.

Read a full role brief

GET /recruiter/roles/{roleId} returns everything on the role page in one call. roleId is the id from the list.

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

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.

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.

Guides

API reference

Browse roles and read a full brief

Browse roles

Common filters

What each role includes

Paging

Read a full role brief

​Browse roles

​Common filters

​What each role includes

​Paging

​Read a full role brief

Browse roles

Common filters

What each role includes

Paging

Read a full role brief