> ## Documentation Index
> Fetch the complete documentation index at: https://docs.collective.work/llms.txt
> Use this file to discover all available pages before exploring further.

# Searching talents

> Search the Collective talent network and retrieve full profiles via the API

## What is it

The Talent Search API lets you search the **Collective talent network** (and your own imported
[My Talents ATS](https://docs.collective.work/docs/my-talents.md) 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).

> [!NOTE]
>
> This is a paid **PRO plan** feature. Talent search and full-profile retrieval are activated
> **separately** — request access at [support@collective.work](mailto: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](https://docs.collective.work/api-reference/endpoint/search/launch.md).

**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](https://docs.collective.work/api-reference/endpoint/search/poll.md).

**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](https://docs.collective.work/api-reference/endpoint/profile/get.md).

> [!WARNING]
>
> 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](mailto: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:

```http theme={null}
X-Monthly-Quota-Remaining: 42
```

The value is a nonnegative integer for the organization's separate monthly allowance:

| Endpoint | What the remaining count includes |
| - | - |
| `POST /sherlock/search` | Completed API searches launched this calendar month, counted when the request starts. The newly launched search is still ongoing and does not reduce this balance. Failed searches do not consume quota. |
| `GET /profile/{id}` | All successful retrievals this calendar month, including this request. Retrieving the same talent again consumes another credit. |

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](https://docs.collective.work/docs/sandbox.md) and return
production-shaped **mock data** with no side effects. Use it to build your integration before
switching to production.


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