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

# Read agency roles

> List a member's approved roles, search the marketplace on their behalf, and read a full recruiting brief.

Three endpoints let your systems read roles **as one of your agency's members sees them**. They need an agency key with `agency_roles:read`, and Paraform must have enabled external API access for your agency. They don't depend on Talent Network.

| Endpoint | Returns |
| - | - |
| [`GET /agency/roles`](/agency/api-reference/list-agency-roles) | The member's **approved** roles, including limited-access roles |
| [`GET /agency/roles/search`](/agency/api-reference/search-agency-roles) | A search of the **active-role marketplace** as the member can see it, not limited to roles they're approved on |
| [`GET /agency/roles/{roleId}`](/agency/api-reference/get-agency-role) | One role's full recruiting brief, using the member's permissions |

## Choose the member with `recruiterEmail`

Every call requires `recruiterEmail`: the email of a **currently approved member** of your agency. It selects whose permissions the read uses. It doesn't authenticate anyone, because your key does that. Membership is re-checked on every request. If the email isn't an approved member of your agency, the call answers `403`.

```bash theme={null}
curl "https://external-api.paraform.com/api/external/v1/agency/roles?recruiterEmail=alex%40youragency.com" \
  -H "Authorization: Bearer $PARAFORM_API_KEY"
```

## List a member's roles

`GET /agency/roles` returns the member's approved roles, most recently updated first.

| Parameter | Notes |
| - | - |
| `status` | `ACTIVE` (default), `PAUSED`, or `CLOSED`. `CLOSED` includes hired and churned roles. Pending, rejected, and disqualified roles are never exposed. |
| `primaryOnly` | `true` restricts to roles where the member holds a full-access primary slot. Defaults to `false`. |
| `query` | Searches role titles and company display names within the member's approved roles. |
| `limit`, `cursor` | Default 50, maximum 100. See [Pagination](/pagination). |

Confidentiality filtering can make a page partial or even empty. Keep going until `nextCursor` is `null`. Approval on a role isn't proof that a particular candidate can be submitted to it.

## Search the marketplace

`GET /agency/roles/search` searches active roles with typo-tolerant matching and the member's visibility rules.

```bash theme={null}
curl -G "https://external-api.paraform.com/api/external/v1/agency/roles/search" \
  -H "Authorization: Bearer $PARAFORM_API_KEY" \
  --data-urlencode "recruiterEmail=alex@youragency.com" \
  --data-urlencode "query=backend engineer" \
  --data-urlencode "location=new_york" \
  --data-urlencode "workplace=HYBRID"
```

* Filters combine with AND. Repeat an array parameter (`location`, `workplace`, `roleType`, `industry`, `techStack`) to match any of up to 20 values.
* Filter values must be the platform's filter keys, listed on the [reference page](/agency/api-reference/search-agency-roles). Unknown parameters and invalid values are rejected with `400`.
* `minSalary` and `maxSalary` are annual whole currency units, compared in 1,000-unit steps without currency conversion.
* Text searches are ordered by relevance. Without `query`, results are ordered by marketplace priority.
* `limit` defaults to 20, maximum 50. Results are live, so pages can be shorter or empty. Continue while `nextCursor` is present.

Search excludes hidden or experimental roles the member can't see, roles not accepting recruiters, and roles whose hiring manager isn't reviewing. Appearing in search doesn't grant a recruiting slot or permission to submit.

## Read a role brief

`GET /agency/roles/{roleId}` returns the recruiter-facing brief: description, requirements, responsibilities, interview stages, submission questions, recruiting guidance, candidate targeting, and company information. The role doesn't need to be in the member's approved list. A role that's missing or that the member can't see returns `404`.

```bash theme={null}
curl "https://external-api.paraform.com/api/external/v1/agency/roles/$ROLE_ID?recruiterEmail=alex%40youragency.com&includeIntakeTranscripts=true" \
  -H "Authorization: Bearer $PARAFORM_API_KEY"
```

`includeIntakeTranscripts=true` adds the intake-call transcripts the member is permitted to read, chosen by the role's intake settings. It defaults to `false`, which omits the field. Permitted transcripts with no readable text come back as an empty array. Summaries never stand in for transcript text, and recording or playback URLs are never returned.

## What these endpoints never return

Recruiter fees, rewards, commissions, and bonuses; candidate and application histories; company logos; hiring-manager contact details; and candidate calibration examples. Unknown or withheld fields are `null`, and withheld collections are empty.


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