Search roles for an agency member

Required scopes: agency_roles:read
Rate limit: default tier, 120 requests per minute per key

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

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.

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.

string | string[]

Repeat for multiple normalized location keys; values within this filter match any.

Show 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

string | string[]

Allowed values: REMOTE, ON_SITE, HYBRID.

string | string[]

Show 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

string | string[]

Industry key (for example, fintech or healthcare), or a namespaced practice area (for example, law::litigation). Repeat for multiple values.

string | string[]

Show 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

string | number

Annual candidate base salary in whole currency units, matched to the nearest 1,000 without currency conversion.

string | number

default:"20"

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.

Response

object[]

required

Show roles properties

string

required

string

required

object

required

Show company properties

string

required

string

required

Allowed values: ACTIVE, PAUSED, CLOSED.

string[]

required

string | null

required

Allowed values: REMOTE, HYBRID, ON_SITE.

object | null

required

Annual candidate base salary in whole currency units, without conversion. Null currency is unknown, not implicitly USD.

Show baseSalary properties

string | null

required

integer | null

required

integer | null

required

string

required

Constraints: format date-time.

string | null

required

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"

{
  "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"
}

Guides

API reference

Search roles for an agency member

Query parameters

Response

​Query parameters

​Response

Query parameters

Response