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

# Launch Sherlock search

> Launch an asynchronous talent search ("Sherlock") from a free-text brief and optional filters. Returns immediately with a `searchId` and an `ONGOING` status — poll the search to retrieve ranked results once it reaches `COMPLETED`.

This is a paid feature that must be activated on your organisation (PRO plan). Searches are metered per organisation: a monthly cap on completed searches plus a limit on concurrent in-flight searches. [Learn more](/docs/searching-talents).



## OpenAPI

````yaml POST /sherlock/search
openapi: 3.0.1
info:
  title: Collective Work Job API
  description: API for managing job postings on the Collective Work platform
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.collective.work/{environment}/v1
    description: Collective Work API server
    variables:
      environment:
        default: sandbox
        description: API environment
        enum:
          - sandbox
          - production
security:
  - bearerAuth: []
paths:
  /sherlock/search:
    post:
      description: >-
        Launch an asynchronous talent search ("Sherlock") from a free-text brief
        and optional filters. Returns immediately with a `searchId` and an
        `ONGOING` status — poll the search to retrieve ranked results once it
        reaches `COMPLETED`.


        This is a paid feature that must be activated on your organisation (PRO
        plan). Searches are metered per organisation: a monthly cap on completed
        searches plus a limit on concurrent in-flight searches. [Learn
        more](/docs/searching-talents).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LaunchSherlockSearchDto'
      responses:
        '201':
          description: Search launched successfully
          headers:
            X-Monthly-Quota-Remaining:
              description: >-
                Production only. Sherlock searches remaining for the
                organization this calendar month, based on completed API
                searches launched this month and counted when this request
                starts. The newly launched search, ongoing searches, and failed
                searches do not consume quota. Concurrent completions may change
                the balance. Omitted in sandbox.
              schema:
                type: integer
                minimum: 0
              example: 42
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LaunchSherlockSearchResponseDto'
        '400':
          description: Invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '403':
          description: >-
            Invalid API key, or organization not activated for the Talent Search
            API
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
components:
  schemas:
    LaunchSherlockSearchDto:
      type: object
      required:
        - text
      properties:
        text:
          type: string
          description: Free-text brief describing the talent you are searching for
          example: >-
            Senior fullstack engineer with 5+ years of React and Node.js, based
            in Paris, fintech experience
        contractTypes:
          type: array
          items:
            type: string
            enum:
              - FREELANCER
              - FREELANCER_OPEN_TO_PERMANENT_CONTRACT
              - PERMANENT_CONTRACT
          description: >-
            Restrict to one or more contract types: `FREELANCER`,
            `FREELANCER_OPEN_TO_PERMANENT_CONTRACT` (open to both freelance and
            permanent), or `PERMANENT_CONTRACT`. Buckets are independent and
            combine as a union (OR). Omit to include every contract type.
          example:
            - FREELANCER
            - FREELANCER_OPEN_TO_PERMANENT_CONTRACT
        excludeWithoutCv:
          type: boolean
          description: Only return talents who have a CV/resume.
        availableNow:
          type: boolean
          description: Only return talents who are available now.
        workedInStartup:
          type: boolean
          description: Only return talents who have worked in a startup.
        searchOnlyInMyTalentsATS:
          type: boolean
          description: >-
            Restrict the search to your own talents (the ones you imported into
            your ATS), excluding the wider Collective network. Scope note: this
            covers the ATS imports of the organization account this API key is
            attributed to, not necessarily every recruiter in the organization.
    LaunchSherlockSearchResponseDto:
      type: object
      required:
        - searchId
        - status
      properties:
        searchId:
          type: string
          description: Unique identifier of the launched search, used for polling
          example: cm71yqftr00000ck0bpz3hpg1
        status:
          type: string
          enum:
            - ONGOING
            - COMPLETED
            - FAILED
          description: Status of the search right after launch
          example: ONGOING
    Error400:
      type: object
      required:
        - message
        - error
        - statusCode
      properties:
        message:
          type: array
          items:
            type: string
        statusCode:
          type: integer
          example: 400
        error:
          type: string
          example: Bad Request
    Error403:
      type: object
      required:
        - message
        - error
        - statusCode
      properties:
        message:
          type: array
          items:
            type: string
        statusCode:
          type: integer
          example: 403
        error:
          type: string
          example: Forbidden
    Error500:
      type: object
      required:
        - message
        - error
        - statusCode
      properties:
        message:
          type: array
          items:
            type: string
          example:
            - Internal server error
        statusCode:
          type: integer
          example: 500
        error:
          type: string
          example: Internal Server Error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Your organization API key, available in [Organisation
        settings](https://app.collective.work/recruiter/organization/api).

````

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