Skip to main content

What is it

The Talent Search API lets you search the Collective talent network (and your own imported My Talents ATS data) from a free-text brief and structured filters, then retrieve ranked talent profiles. It is an asynchronous API made of three steps: you launch a search, poll it until it completes, then fetch the full profile of the talents you are interested in (with their contact details and CV).
This is a paid PRO plan feature. Talent search and full-profile retrieval are activated separately — request access at support@collective.work. Calls to a capability your organization isn’t activated for return a 403.

How it works

1

Launch a search

POST /sherlock/search with a free-text text brief (and optional filters). You get back a searchId and status: "ONGOING" immediately — the search runs in the background. See Launch Sherlock search.
2

Poll for results

GET /sherlock/search/{searchId} — poll roughly every 10 seconds. While the search runs, status is ONGOING and results is null. Once status is COMPLETED, results is an array of ranked matches. FAILED means the search errored. See Get Sherlock search results.
3

Retrieve a full profile

GET /profile/{id} with a talent id from the results to get the full profile, including contact details and CV. See Get Profile.
Poll results are short profile summaries only — they do not contain contact details, the CV, or full profile fields like education, certifications, etc. Use the Get Profile endpoint to retrieve the full profile.

Search filters

Beyond the free-text text brief, POST /sherlock/search accepts optional filters:
  • contractTypes — an array of one or more independent buckets: FREELANCER, FREELANCER_OPEN_TO_PERMANENT_CONTRACT (open to both freelance and permanent), or PERMANENT_CONTRACT. They combine as a union (OR). Omit it to include every contract type.
  • excludeWithoutCv — only return talents who have a CV/resume.
  • availableNow — only return talents who are available now.
  • workedInStartup — only return talents who have worked in a startup.
  • searchOnlyInMyTalentsATS — restrict the search to your own imported ATS talents, excluding the wider Collective network. This covers the ATS imports of the organization account the API key belongs to.

Results

  • Results are returned ranked by descending match score and capped at 30 profiles per call by default. If you need a higher cap, ask support at support@collective.work.
  • Each result contains a score (0–100), a list of reasons explaining the match, and a summary profile.
The summary profile includes identity, picture, linkedinUrl, collectiveUrl, title, daily rate / salary range, availability, work preference, desired contract type, location + mobilities, skills, featured skills, and the last 3 work experiences (company name, logo and dates only).

The full profile

Call GET /profile/{id} to get everything in the summary plus the talent’s intro, full work experiences (with descriptions and location), educations, languages, certifications, links, contact details, and CV.

Contact details

We return the talent’s emails and phone numbers when we have them. Each phone number carries a WhatsApp reachability status via whatsappValidity:
  • VALID — reachable on WhatsApp
  • INVALID — not reachable on WhatsApp
  • UNKNOWN — could not be determined

CV

The CV is returned inline as base64 (fileName, contentType, data). It is included only when we have a CV for the talent — cv is null otherwise (we don’t have one for everyone).

Other useful fields

  • availability — AVAILABLE when the talent is available now, or null otherwise.
  • featuredSkills — the skills the talent is best at (a highlighted subset of skills).
  • linkedinUrl — the talent’s LinkedIn profile (may be null).
  • collectiveUrl — a deep link to open the talent directly inside the Collective recruiter app.

A note on locations

A talent’s primary location and mobilities are fully structured — label, country, countryCode, Google Maps place id, and latitude/longitude. For work experiences, only the label is populated today (the structured fields are reserved for future geocoding), and summary experiences carry no location at all.

Quotas, concurrency & usage

Usage is metered per organization across two independent quotas:
  • Search — a monthly cap on completed searches, plus a limit on the number of concurrent in-flight searches.
  • Profile retrieval — a monthly cap on GET /profile/{id} calls. Every successful call counts (there is no de-duplication); once you hit the cap, calls return a 402.
You can track your usage and limits in the Collective app, on the Usage page under the API tab — one card per quota.

Remaining monthly quota header

Successful production responses from Launch Sherlock search (201) and Get Profile (200) include the X-Monthly-Quota-Remaining response header:
The value is a nonnegative integer for the organization’s separate monthly allowance: These balances are snapshots, not reservations: concurrent requests or search completions can change them. The header is exposed to browser clients from permitted origins through CORS. The header is absent from errors, Sherlock polling, MegaSearch, other endpoints, and sandbox responses. Quota enforcement continues to return 402 when the relevant monthly allowance is exhausted.

Sandbox

Both the search and profile endpoints are available in the sandbox and return production-shaped mock data with no side effects. Use it to build your integration before switching to production.