Search the talent pool for a job
Looks through the candidates already in the organization, from any job, for people whose resumes fit this job, and ranks them. It is free, uses no credits, and runs in the background for a few minutes: poll GET /v1/talent-searches/{id} until done. If a search for the job is already running, or one finished in the last 7 days, that search is returned with reused: true instead of starting another; send refresh to force a new one. Closed jobs take no search (job_closed). A job whose requirements are still being prepared answers job_not_indexed; retry in a few minutes. Searches use AI time, so an organization can have 3 running at once and start 20 an hour; past that a new search answers 429 rate_limit_exceeded (following or reusing an existing search never does). The key also needs candidates:read, because matches name candidates.
Required scope: jobs:write.
Errors
- 400:
invalid_content_type,invalid_idempotency_key,invalid_json,request_body_too_large,unknown_field - 401:
authentication_required,invalid_api_key - 403:
api_access_disabled,insufficient_scope - 404:
job_not_found - 409:
idempotency_key_reused,idempotency_request_in_progress,job_closed,job_not_indexed - 422:
invalid_parameter - 429:
rate_limit_exceeded - 500:
api_error - 503:
maintenance_mode,service_unavailable
ApiKeyAuthorizationBearer <probb_live_<id>_<secret>>id*stringThe job's ID.
1 <= length <= 200Idempotency-Key?stringMakes retries safe. Repeating a request with the same key and body within 24 hours returns the original response with Idempotent-Replayed: true. The same key with a different body, or from a different API key, returns idempotency_key_reused.
1 <= length <= 255application/json- body
refresh?booleanStart a new search even when one finished in the last 7 days. Searches use AI model time (no credits), so leave it out to reuse the existing results.
falseSuccess.
application/json- response
object*stringid*stringThe search's ID. The same ID the app uses.
job*The job the candidates were searched for.
status*stringqueued, then preparing, retrieving, evaluating and finalizing while it runs, then completed. partial finished but could not assess every shortlisted candidate; its matches are usable. failed produced nothing.
"queued""preparing""retrieving""evaluating""finalizing""completed""partial""failed"done*booleanWhether the search has stopped, successfully or not.
counts*errorMessage*|Why the search failed, when it did.
createdAt*stringWhen the search was started.
date-timecompletedAt*|When it stopped.
matches*array<>Matches, closest first. Empty while the search runs. At most 50.
totalMatches*integerThe number of matches.
-9007199254740991 <= value <= 9007199254740991reused*booleanTrue when this is a search that already existed: one still running, or a finished one under 7 days old. Send refresh to force a new search.
# Set PROBB_URL and PROBB_API_KEY. Replace any *_VALUE placeholder and any example ID (such as job_example) with a real one.# Idempotency-Key is optional. Reuse the same key and body when retrying one logical write.curl --fail-with-body -X POST "$PROBB_URL/api/v1/jobs/ID_VALUE/talent-searches" \ -H "Authorization: Bearer $PROBB_API_KEY" \ -H "Idempotency-Key: $REQUEST_KEY" \ -H 'Content-Type: application/json' \ --data-binary '{ "refresh": false}'{ "object": "talent_search", "id": "string", "job": { "id": "string", "title": "string" }, "status": "queued", "done": true, "counts": { "pool": -9007199254740991, "retrieved": -9007199254740991, "shortlisted": -9007199254740991, "evaluated": -9007199254740991, "matched": -9007199254740991, "failed": -9007199254740991 }, "errorMessage": "string", "createdAt": "2019-08-24T14:15:22Z", "completedAt": "2019-08-24T14:15:22Z", "matches": [ { "rank": -9007199254740991, "band": "strong_potential", "candidate": { "id": "string", "name": "string", "currentRole": "string", "location": "string" }, "mustHave": { "met": -9007199254740991, "partial": -9007199254740991, "total": -9007199254740991 }, "important": { "met": -9007199254740991, "partial": -9007199254740991, "total": -9007199254740991 }, "highlight": "string", "report": { "id": "string", "completed": true } } ], "totalMatches": -9007199254740991, "reused": true}