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

# Search roles for an agency member

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

Searches the active-role marketplace using typo-tolerant matching and recruiter visibility rules. Requires an agency key with agency\_roles:read, external API access enabled for the agency, and the email of a currently approved member of that agency. Unlike listAgencyRoles, results are not restricted to roles the member is already approved on.

Filters combine with AND; repeat array parameters to match any of up to 20 values within a filter. Location, workplace, role type, industry, and tech stack use the platform's filter keys. Unknown parameters and invalid filter values are rejected. Salary bounds are annual whole currency units, compared in 1,000-unit increments without currency conversion.

Text searches are relevance-ordered. Without query, roles are ordered by marketplace priority, with role ID as the tie-breaker. Hidden or experimental roles unavailable to the member, deleted roles, roles not accepting recruiters, and roles whose manager is not reviewing are excluded.

Returns at most 20 roles by default and 50 at maximum. Pass nextCursor back as cursor with the same recruiter and filters. Ranked role IDs are cached for up to 30 seconds. Membership, structured filters, and visibility are checked on every page. Pages can be shorter or empty when roles become unavailable; continue while nextCursor is present. Results are not a frozen snapshot; cache refreshes can shift page boundaries. Stop when nextCursor is null.

Returns the restricted agency role summary only, never recruiter fees, rewards, candidate details, or pipeline counts. Use getAgencyRole for a full permitted role brief. Appearing in search does not grant a recruiting slot or submission permission.

## 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">
  Browse's typo-tolerant role and company search. Omit to browse active roles without a text filter.
  Constraints: min length 1, max length 200.
</ParamField>

<ParamField query="location" type="string | string[]">
  Repeat for multiple normalized location keys; values within this filter match any.

  <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[]">
  Industry key (for example, fintech or healthcare), or a namespaced practice area (for example, law::litigation). Repeat for multiple values.
</ParamField>

<ParamField query="techStack" type="string | string[]">
  <Expandable title="145 allowed values">
    `java`, `python`, `javascript`, `typescript`, `react`, `node`, `nextjs`, `tensorflow`, `pytorch`, `tensorboard`, `pyspark`, `kafka`, `kubernetes`, `redis`, `mongo`, `postgresql`, `mysql`, `mongodb`, `aws`, `gcp`, `azure`, `git`, `docker`, `k8s`, `terraform`, `tailwind`, `cloudflare`, `c/c++`, `c#`, `htmx`, `html`, `css`, `ruby`, `ruby_on_rails`, `django`, `flutter`, `dart`, `fastapi`, `graphql`, `rest_api`, `vue`, `svelte`, `langchain`, `snowflake`, `hadoop`, `mapreduce`, `rpc`, `cassandra`, `cicd`, `graph_database`, `vector_database`, `open_ai`, `web3`, `solidity`, `go`, `rust`, `scala`, `kotlin`, `swift`, `php`, `laravel`, `spring_boot`, `express`, `angular`, `ember`, `backbone`, `jquery`, `sass`, `less`, `webpack`, `babel`, `elasticsearch`, `rabbitmq`, `nginx`, `apache`, `jenkins`, `travis_ci`, `circle_ci`, `ansible`, `puppet`, `chef`, `prometheus`, `grafana`, `tableau`, `power_bi`, `d3`, `three_js`, `unity`, `unreal_engine`, `opencv`, `scikit_learn`, `pandas`, `numpy`, `r`, `sas`, `spark`, `hive`, `airflow`, `luigi`, `dask`, `kubeflow`, `mlflow`, `webflow`, `zapier`, `hubspot`, `sigma`, `notion`, `amplitude`, `google_ads`, `google_search`, `figma`, `photoshop`, `illustrator`, `after_effects`, `premiere_pro`, `audacity`, `canva`, `slack`, `microsoft_office`, `microsoft_word`, `microsoft_excel`, `microsoft_powerpoint`, `salesforce`, `jira`, `confluence`, `trello`, `monday`, `basecamp`, `zendesk`, `intercom`, `mailchimp`, `sendgrid`, `stripe`, `paypal`, `square`, `quickbooks`, `xero`, `looker`, `google_analytics`, `adobe_creative_suite`, `sketch`, `invision`, `zeplin`, `framer`, `airtable`
  </Expandable>
</ParamField>

<ParamField query="minSalary" type="string | number">
  Annual candidate base salary in whole currency units, matched to the nearest 1,000 without currency conversion.
</ParamField>

<ParamField query="maxSalary" type="string | number" />

<ParamField query="minYearsExperience" type="string | number" />

<ParamField query="maxYearsExperience" type="string | number" />

<ParamField query="limit" default="20" type="string | number" />

<ParamField query="cursor" type="string">
  Opaque continuation token. Reuse only with the same agency, recruiter, query, and filters. Results are live, not a frozen snapshot.
  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/search?recruiterEmail=jane@example.com&limit=20" \
    -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.