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

# List your agency's talent-network candidates

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

Every candidate your agency currently has in the Paraform talent network, however they entered it — a direct submission (`directlySubmittedAt` set) or a submission to a role (`hasRoleSubmission` true); both can be true for the same candidate. This is the same set your team sees on the in-app Talent Network tab, and `daysRemaining` is the same number that tab shows for the candidate on the same day.

`status` is `on_market` (ParaAI is actively considering the candidate; `daysRemaining` counts down the remaining window and `expiresAt` is when it ends) or `off_market` (in your network but not currently being considered; `daysRemaining` and `expiresAt` are null). Off-market candidates are listed deliberately — they are still your network members. Whether a fresh direct submission returns one to consideration depends on why they are off market: a candidate locked off-market by an automated decision returns only via a submission to a role.

All filters are optional and combine. `status` narrows to `on_market` or `off_market`; `daysRemainingMin` and `daysRemainingMax` bound the matching window inclusively — pass both for a range, or either alone as a floor or a ceiling, so `?status=on_market&daysRemainingMax=7` is everyone about to fall off. Only on-market candidates have a `daysRemaining`, so a bound already implies on-market: pairing one with `status=off_market` is rejected rather than silently returning nothing, as is a `daysRemainingMin` above `daysRemainingMax`. Bounds are evaluated against the same clock as the `daysRemaining` in the response, so the filter and the number always agree; each page of a long walk is evaluated afresh, so a candidate sitting on a day boundary can tick past it between pages. A cursor is only meaningful alongside the filters it was issued under — replay it with the same query.

Pagination is cursor-based and stable: pass `nextCursor` back as `cursor` for the next page. A walk visits every candidate that existed when it started exactly once, even while your team keeps submitting — candidates added mid-walk appear on your next full pass, and a candidate who leaves the network mid-walk can shorten a page. `nextCursor` is absent on the last page; the cursor is opaque, so never construct or parse one. `limit` defaults to 50 and caps at 100.

Only your own agency's candidates are ever returned. A candidate another agency has in the talent network does not appear here and is indistinguishable from one who is not in it at all.

## Query parameters

<ParamField query="limit" type="integer" default={"50"}>
  Constraints: minimum 1, maximum 100.
</ParamField>

<ParamField query="cursor" type="string">
  Constraints: min length 1.
</ParamField>

<ParamField query="status" type="string">
  Allowed values: `on_market`, `off_market`.
</ParamField>

<ParamField query="daysRemainingMin" type="string">
  Constraints: pattern `^\d+$`.
</ParamField>

<ParamField query="daysRemainingMax" type="string">
  Constraints: pattern `^\d+$`.
</ParamField>

## Response

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

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

    <ResponseField name="email" type="string | null" required />

    <ResponseField name="linkedinUrl" type="string | null" required />

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

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

    <ResponseField name="expiresAt" type="string | null" required />

    <ResponseField name="directlySubmittedAt" type="string | null" required />

    <ResponseField name="hasRoleSubmission" type="boolean" required />
  </Expandable>
</ResponseField>

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

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://external-api.paraform.com/api/external/v1/talent-network/candidates?limit=50" \
    -H "Authorization: Bearer $PARAFORM_API_KEY"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "candidates": [
      {
        "candidateUserId": "string",
        "name": "string",
        "email": "string",
        "linkedinUrl": "string",
        "status": "on_market",
        "daysRemaining": 0,
        "expiresAt": "string",
        "directlySubmittedAt": "string",
        "hasRoleSubmission": true
      }
    ]
  }
  ```
</ResponseExample>


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