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

# Take candidates off the ParaAI market

<Info>
  **Required scopes:** `talent_network:write`<br />
  **Rate limit:** `write` tier, 60 requests per minute per key
</Info>

Takes up to 100 candidates off the ParaAI market in one call — the CRM-side equivalent of the Talent Network tab's "Set off market" action. Off-market candidates stay in your talent network but are not considered for ParaAI matching until re-enabled or resubmitted, and any active boost is removed.

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. An identity reference acts on every membership row your agency holds for that person, so a candidate two of your recruiters own goes off market for both — `candidateUserIds` lists every row acted on.

`results` is index-aligned with `candidates`; a well-formed request always answers 200, so branch on per-item `ok`. `status` values: `off_market` (was on market, now off), `already_off_market` (nothing to change — includes locked candidates, which stay off market), `pre_excluded` (the candidate was never in the talent network and is now excluded from future consideration; only a fresh submit — not `/re-enable` — restores them), and `not_found` (no candidate owned by an approved member of your agency matches this reference, indistinguishable from a candidate that does not exist). Statuses are never renamed but new ones may be added — branch on `ok` and treat an unknown `status` as informational.

Requires Talent Network management to be enabled for your agency; without it the whole request answers 403 (re-enabling never requires it). Retries converge on `already_off_market`, so no `Idempotency-Key` is needed. Duplicate references in one request collapse to a single action and report the same result at every index.

## Body

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

  <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="candidateUserIds" type="string[]" />

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

    <ResponseField name="status" type="string" required>
      Allowed values: `off_market`, `already_off_market`, `pre_excluded`, `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/off-market" \
    -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": "off_market"
      }
    ]
  }
  ```
</ResponseExample>


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