---
title: "Create a search job"
method: POST
path: "/searches"
---

# Create a search job

`POST /searches`

## Request

- Base URL: `https://api.instalent.io/api/v1`
- URL: `https://api.instalent.io/api/v1/searches`
- Auth: HTTP bearer and API key in header `X-Customer-Key`

Queues the job and returns 202. Poll GET /searches/{id}, stream GET /searches/{id}/events, or wait for the search.completed webhook, then page GET /searches/{id}/results.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `mode` 'candidate' | 'client'
  - `criteria` object, required
    - `titles` string[], required: Every title is searched exactly as given; none is added or rephrased.
    - `locations` string[], required
    - `industries` string[]
    - `skills` string[]
    - `companies` string[]
    - `keywords` string
    - `experience` object
      - `min` integer, required
  - `openToWork` boolean: Has no effect since 2026-10-06 (still accepted): open to work is not a search option. Every result carries `openToWork` instead, read from the person's profile: true when they say they are looking, or hold no job and the last one ended within two years; null otherwise. Never false: nobody can tell that a person is not looking.
  - `maxResults` integer: An upper bound, not a target. Candidate searches return only people who closely match the criteria, typically about 85 to 115 for a specific role and city, so a higher value rarely returns more.

## Response `200`

Replayed: this Idempotency-Key already created a job, so the original is returned.

- object
  - `id` string, required
  - `kind` 'search' | 'enrichment' | 'analysis', required
  - `status` 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled', required
  - `input` object, required
  - `progress` object, nullable, required
    - `phase` string
    - `current` number
    - `total` number
  - `summary` object, nullable, required
  - `error` object, nullable, required
    - `code` string, required
    - `message` string, required
    - `retryable` boolean
  - `createdAt` string, required
  - `startedAt` string, nullable, required
  - `finishedAt` string, nullable, required
  - `links` object
    - `self` string
    - `results` string
    - `events` string
    - `cancel` string

## Other responses

- `202`: OK
- `4XX`: Error

---

[API](https://skmtc.dev/instalent/apis/instalent-integrator-api.md) · [All operations](https://skmtc.dev/instalent/apis/instalent-integrator-api/llms.txt) · [OpenAPI document](https://skmtc.dev/instalent/apis/instalent-integrator-api/revisions/eda181144149?raw)