Manage market status

Two bulk endpoints mirror the Talent Network tab’s Set off market and Re-enable actions, so your CRM can control which candidates ParaAI considers. Both need talent_network:write and use the write rate tier.

Endpoint	Effect	Needs Talent Network management
`POST /talent-network/candidates/off-market`	Stops ParaAI from considering the candidates and removes any active boost. They stay in your network.	Yes. Otherwise the whole request answers `403`.
`POST /talent-network/candidates/re-enable`	Resumes matching for candidates who were set off market or aged out of their eligibility window.	No. Candidates expire off market automatically for every agency, so recovering them always works.

Request

Both take { "candidates": [ … ] } with 1 to 100 items. Reference each candidate by candidateUserId, or by email / linkedinUrl:

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": "clx8k2j3a0000qz8h1b2c3d4e" },
      { "linkedinUrl": "https://www.linkedin.com/in/janedoe" }
    ]
  }'

candidateUserId wins when given. Otherwise linkedinUrl beats email, the same precedence as lookup.
An identity reference (email or LinkedIn) acts on every membership row your agency holds for that person. A candidate owned by two of your recruiters changes state for both, and the result’s candidateUserIds lists every row acted on.
Duplicate references in one request collapse into a single action and report the same result at every index.

Response

A well-formed request always answers 200 with a results array aligned by index with candidates. Branch on each result’s ok, then read status.

off-market
re-enable

`status`	`ok`	Meaning
`off_market`	`true`	Was on the market, now off.
`already_off_market`	`true`	Nothing to change, including candidates Paraform has locked off the market.
`pre_excluded`	`true`	The candidate was never in the talent network. This marks them as excluded from future consideration. `/re-enable` can’t undo it. Only a fresh submit can.
`not_found`	`false`	No approved member of your agency owns a candidate matching this reference.

`status`	`ok`	Meaning
`on_market`	`true`	Matching resumed.
`already_on_market`	`true`	Nothing to do.
`locked`	`false`	Paraform locked this candidate off the market. Only a role submission restores eligibility.
`not_reenableable`	`false`	The candidate isn’t in ParaAI consideration (never submitted, or previously excluded). Submit them instead.
`not_found`	`false`	No approved member of your agency owns a candidate matching this reference.

not_found doesn’t distinguish another agency’s candidate from one that doesn’t exist. Statuses are never renamed, but new ones may be added, so treat an unknown status as informational.

Things to know

Re-enabling a candidate whom Paraform detected as off the market overrides that detected signal.
Resubmitting a candidate through submit or submit-bulk puts them back on the market after an off-market call. The exception is a candidate Paraform has locked off the market, who returns only through a submission to a role.
Retries converge on already_off_market or already_on_market, so these endpoints don’t need an Idempotency-Key.
A structurally malformed item (for example, a field with the wrong JSON type) fails the whole request with 400.

Guides

API reference

Manage market status

Request

Response

Things to know

​Request

​Response

​Things to know

Request

Response

Things to know