> ## 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 recruiter-entered preferences for many candidates at once

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

Reads the recruiter-entered preferences of up to 50 candidates in one call — the batch form of `GET /talent-network/candidates/{candidateUserId}/preferences`, for CRMs that mirror a whole list rather than one candidate at a time. These are the same values a recruiter manages in-app, and the source that always wins for ParaAI matching.

Each item references a candidate by `candidateUserId` (from `GET /talent-network/candidates` or `POST /talent-network/candidates/lookup`), or by `email` / `linkedinUrl`. `candidateUserId` wins when both are given; otherwise `linkedinUrl` beats `email`, the same precedence `lookup` documents. Any candidate owned by an approved member of your agency is addressable — deliberately wider than the membership list, so off-market or expired candidates are readable too.

An identity reference resolves to EVERY membership row your agency holds for that person, so `candidates` can carry more than one entry: a candidate two of your recruiters own has a separate, independently editable preferences row per owner, each listed with its own `candidateUserId`. Entries are ordered by ParaAI eligibility expiry, latest first, with rows that have no expiry last. Do not assume a single entry — read them all, or pick by `candidateUserId`.

`results` is index-aligned with `candidates` and the request answers 200, so branch on per-item `ok`. `status` is `found` (`candidates` lists one entry per owning membership row) or `not_found` (no candidate owned by an approved member of your agency matches this reference, indistinguishable from a candidate that does not exist). Values are never rejected: an unparseable `linkedinUrl`, an unknown `email`, or an item naming no candidate at all — `null` fields read as omitted — answers `not_found` at its own index, so one bad value never costs you the rest of the batch. Only schema violations fail the whole request with 400, as on every endpoint: fields must carry their documented JSON types, and `candidateUserId`, when present, must be a non-empty string. Statuses are never renamed but new ones may be added — branch on `ok` and treat an unknown `status` as informational.

An entry's `preferences` is `null` when that membership row has no recruiter-entered preferences yet (possible for candidates who entered the network via a role submission) — exactly what the single-candidate GET returns for it. Candidates predating today's validation may read back `null` numbers or empty arrays.

This endpoint only reads; it never creates or modifies anything and takes no `Idempotency-Key`. Duplicate references in one request get the same answer at every index.

## Body

<ParamField body="candidates" type="object[]" required>
  Constraints: min items 1, max items 50.

  <Expandable title="candidates properties">
    <ParamField body="candidateUserId" type="string | null">
      Constraints: min length 1.
    </ParamField>

    <ParamField body="email" type="string | null" />

    <ParamField body="linkedinUrl" type="string | null" />
  </Expandable>
</ParamField>

## Response

<ResponseField name="results" type="object[]" required>
  <Expandable title="results properties">
    <ResponseField name="index" type="integer" required>
      Constraints: minimum 0.
    </ResponseField>

    <ResponseField name="candidates" type="object[]">
      <Expandable title="candidates properties">
        <ResponseField name="candidateUserId" type="string" required />

        <ResponseField name="preferences" type="object | null" required>
          <Expandable title="preferences properties">
            <ResponseField name="locations" type="string[]" required>
              <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>
            </ResponseField>

            <ResponseField name="workplaceTypes" type="string[]" required>
              Allowed values: `REMOTE`, `ON_SITE`, `HYBRID`.
            </ResponseField>

            <ResponseField name="salaryMin" type="integer | null" required />

            <ResponseField name="salaryMax" type="integer | null" required />

            <ResponseField name="ote" type="integer | null" required />

            <ResponseField name="idealFundingRounds" type="string[]" required>
              Allowed values: `PRE_SEED`, `SEED`, `SERIES_A`, `SERIES_B`, `SERIES_C`, `SERIES_D_PLUS`, `UNKNOWN`.
            </ResponseField>

            <ResponseField name="visaAuthorization" type="string | null" required>
              Allowed values: `NO_VISA_AUTHORIZATION_NEEDED`, `HAS_VISA_AUTHORIZATION`, `NEEDS_NEW_VISA_AUTHORIZATION`.
            </ResponseField>

            <ResponseField name="roleType" type="string[]" required>
              <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>
            </ResponseField>

            <ResponseField name="excludedIndustries" type="string[]" required>
              <Expandable title="39 allowed values">
                `venture_capital`, `logistics`, `real_estate`, `marketplace`, `healthcare`, `life_sciences`, `hardware`, `ai`, `gaming`, `fintech`, `finance`, `education`, `ecommerce`, `devtools`, `defense`, `cybersecurity`, `crypto`, `data`, `enterprise`, `financial_services`, `government`, `insurance`, `law`, `marketing`, `media`, `transportation`, `environment`, `robotics`, `security`, `construction`, `manufacturing`, `consumer`, `ad_tech`, `b2b`, `api_sdk`, `software_development`, `creator_economy`, `edtech`, `autonomous_vehicles`
              </Expandable>
            </ResponseField>

            <ResponseField name="companySizePreferences" type="string[]" required>
              Allowed values: `< 10 employees`, `10 - 50 employees`, `50 - 200 employees`, `200 - 1000 employees`, `> 1000 employees`.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="ok" type="boolean" required />

    <ResponseField name="status" type="string" required>
      Allowed values: `found`, `not_found`.
    </ResponseField>

    <ResponseField name="message" type="string" />
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://external-api.paraform.com/api/external/v1/talent-network/candidates/preferences/lookup" \
    -H "Authorization: Bearer $PARAFORM_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "candidates": [
      {
        "candidateUserId": "string"
      }
    ]
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "results": [
      {
        "index": 0,
        "ok": true,
        "status": "found"
      }
    ]
  }
  ```
</ResponseExample>


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