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

# Bulk submit candidates to the talent network

<Info>
  **Required scopes:** `talent_network:write`<br />
  **Rate limit:** `write` tier, 60 requests per minute per key<br />
  **Idempotency:** send an `Idempotency-Key` header to retry safely
</Info>

Submits up to 100 candidates in one request. Each item has the same shape as the single-candidate submit body, except `resume` is `{ resumeFileId }` from a POST /resumes upload made by the same agency (ids are not referenceable across agencies) instead of inline bytes, plus three additional fields: required `onMarketConfirmed: true` (the caller's per-candidate attestation that the candidate is actively on the market; not persisted — submitting is the attestation), optional `clientReferenceId` (echoed back verbatim), and optional `recruiterEmail` (attributes the candidate to that agency member; omitted means the agency owner). Unknown, non-member, or unapproved recruiter emails reject that item — never a silent owner fallback.

Items are validated independently and the response is always 200 with an index-aligned `items` array (`queued`, `rejected` with field-level errors, or `deduplicated`). Same-person items within one request collapse onto the first occurrence (later ones come back `deduplicated`, or share the first occurrence's `enqueue_failed` rejection when it never reached the queue). Across requests, a candidate comes back `deduplicated` while an earlier submission of the same (attributed recruiter, email, LinkedIn URL) is still `queued` or `processing` — so a retry must resend the same `recruiterEmail`. Once that submission reaches a terminal outcome, resubmitting starts a fresh attempt immediately, which is what makes a `failed` item actionable; ingestion upserts idempotently either way. An `Idempotency-Key` header replays the entire stored response (including `batchId`) for 24h; replays require a byte-identical body, and after the replay window expires a retry produces a new `batchId` whose items follow the dedupe rule above. Ingestion is asynchronous: poll `GET /talent-network/batches/{batchId}` for per-item outcomes. Requires Talent Network management to be enabled for your agency; without it the whole request answers 403.

## Body

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

  <Expandable title="items properties">
    <ParamField body="name" type="string" required>
      Constraints: min length 1.
    </ParamField>

    <ParamField body="linkedinUrl" type="string" required>
      Constraints: format `uri`.
    </ParamField>

    <ParamField body="email" type="string" required>
      Constraints: format `email`.
    </ParamField>

    <ParamField body="preferences" type="object" required>
      <Expandable title="preferences properties">
        <ParamField body="locations" type="string[]" required>
          Constraints: min items 1.

          <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 body="workplaceTypes" type="string[]" required>
          Constraints: min items 1.
          Allowed values: `REMOTE`, `ON_SITE`, `HYBRID`.
        </ParamField>

        <ParamField body="salaryMin" type="integer" required>
          Constraints: greater than 0.
        </ParamField>

        <ParamField body="salaryMax" type="integer | null">
          Constraints: greater than 0.
        </ParamField>

        <ParamField body="ote" type="integer | null">
          Constraints: greater than 0.
        </ParamField>

        <ParamField body="idealFundingRounds" type="string[]" required>
          Constraints: min items 1.
          Allowed values: `PRE_SEED`, `SEED`, `SERIES_A`, `SERIES_B`, `SERIES_C`, `SERIES_D_PLUS`, `UNKNOWN`.
        </ParamField>

        <ParamField body="visaAuthorization" type="string" required>
          Allowed values: `NO_VISA_AUTHORIZATION_NEEDED`, `HAS_VISA_AUTHORIZATION`, `NEEDS_NEW_VISA_AUTHORIZATION`.
        </ParamField>

        <ParamField body="roleType" type="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 body="excludedIndustries" type="string[]">
          <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>
        </ParamField>

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

    <ParamField body="screeningCallLink" type="string">
      Constraints: format `uri`.
    </ParamField>

    <ParamField body="recruiterEmail" type="string">
      Constraints: format `email`, max length 320.
    </ParamField>

    <ParamField body="resume" type="object" required>
      <Expandable title="resume properties">
        <ParamField body="resumeFileId" type="string" required>
          Constraints: format `uuid`.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="clientReferenceId" type="string">
      Constraints: min length 1, max length 128.
    </ParamField>

    <ParamField body="onMarketConfirmed" type="boolean" required>
      Allowed values: `true`.
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="batchId" type="string" required>
  Constraints: format `uuid`.
</ResponseField>

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

    <ResponseField name="clientReferenceId" type="string" />

    <ResponseField name="status" type="string" required>
      Allowed values: `queued`, `rejected`, `deduplicated`.
    </ResponseField>

    <ResponseField name="submissionId" type="string">
      Constraints: format `uuid`.
    </ResponseField>

    <ResponseField name="errors" type="object[]">
      <Expandable title="errors properties">
        <ResponseField name="field" type="string" />

        <ResponseField name="code" type="string" required>
          Allowed values: `missing_required_field`, `invalid_value`, `unknown_resume`, `recruiter_not_found`, `recruiter_not_approved`, `agency_owner_unavailable`, `enqueue_failed`.
        </ResponseField>

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

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://external-api.paraform.com/api/external/v1/talent-network/candidates/submit-bulk" \
    -H "Authorization: Bearer $PARAFORM_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: $(uuidgen)" \
    -d '{
    "items": [
      {
        "name": "string",
        "linkedinUrl": "https://example.com",
        "email": "jane@example.com",
        "preferences": {
          "locations": [],
          "workplaceTypes": [],
          "salaryMin": 0,
          "idealFundingRounds": [],
          "visaAuthorization": "NO_VISA_AUTHORIZATION_NEEDED"
        },
        "resume": {
          "resumeFileId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        },
        "onMarketConfirmed": true
      }
    ]
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "batchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "items": [
      {
        "index": 0,
        "status": "queued"
      }
    ]
  }
  ```
</ResponseExample>


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