---
title: "Start a quick match ($2.50, one role, minutes)"
method: POST
path: "/api/v1/quick-searches"
---

# Start a quick match ($2.50, one role, minutes)

`POST /api/v1/quick-searches`

## Request

- Base URL: `https://jobherder.com`
- URL: `https://jobherder.com/api/v1/quick-searches`
- Auth: HTTP bearer

The single best current role for this candidate, with a tailored CV and cover letter. Same request body as /api/v1/searches. Paid in USDC via x402: call it unpaid to receive the challenge, then retry with a PAYMENT-SIGNATURE header. Poll GET /api/v1/searches for status. Quick credits cannot pay for a full search, and vice versa.

## Headers

- `Idempotency-Key` string

## Request body

- object: The profile, plus the CV supplied either as cv_json or as cv_base64 with cv_type.
  - `profile` Profile, required: Who the job seeker is and what they want. Twelve fields are required; the others default. cfg_seniority is retired — send cfg_seniority_level and cfg_target_titles.
    - `cfg_name` string, required: Full name, as it appears on the tailored CV
    - `cfg_email` string, email, required: Must match the address this API key is registered to
    - `cfg_location` string, required: Where they live, e.g. "Berlin, Germany"
    - `cfg_location_preference` string, required: Prose description of acceptable locations, read as intent rather than parsed
    - `cfg_work_style` 'remote_only' | 'mix', required: remote_only rejects anything needing office attendance; mix means local or hybrid near them plus remote in the chosen regions
    - `cfg_want_remote_eu` 'yes' | 'no', required: Include EU-remote roles
    - `cfg_want_remote_uk` 'yes' | 'no', required: Include UK-remote roles
    - `cfg_want_usa` 'yes' | 'no', required: Include USA roles. Say no unless they can work there legally
    - `cfg_seniority_level` string, required: Seniority band, e.g. "Director" or "Manager – Head of Department"
    - `cfg_target_titles` string, required: Comma-separated target titles, e.g. "Head of Production, COO"
    - `cfg_local_country` string, required: ISO country name for where they live, e.g. "Germany"
    - `cfg_uk_onsite` 'yes' | 'no': Also include on-site roles in the UK
    - `cfg_industries` string, required: Comma-separated sectors, not job functions
    - `cfg_languages` string[]: Working languages. Roles needing a language not listed are dropped
    - `cfg_not_interested_in` string: Comma-separated exclusions, applied as a hard filter
    - `cfg_advisory_open` 'yes' | 'no': Include advisory, fractional and board roles
    - `cfg_additional_context` string: Visa position, notice period, salary floor, companies to avoid
    - `cfg_share_with_employers` 'yes' | 'no': Consent to share the profile with employers
  - `cv_json` object: The CV as structured data in the JSON Resume schema (jsonresume.org): basics, work, education, skills, projects, certificates, awards, publications, languages, interests. Preferred when you hold the CV as data rather than a file — no need to render a document.
  - `cv_base64` string: The CV as a base64-encoded file, up to 10MB.
  - `cv_type` 'pdf' | 'docx' | 'txt': Format of cv_base64. Plain text is accepted, so an agent with no document to upload can send the CV as text rather than rendering a PDF.

## Response `201`

Quick match queued

- object
  - `ok` boolean
  - `run_id` string
  - `status` string
  - `plan` 'agent_quick'
  - `target_jobs` 1
  - `credits_remaining` integer

## Other responses

- `402`: Payment required — no quick credit
- `429`: A search is already running — poll it until terminal before starting another

---

[API](https://skmtc.dev/jobherder/apis/jobherder-agent-api.md) · [All operations](https://skmtc.dev/jobherder/apis/jobherder-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/jobherder/apis/jobherder-agent-api/revisions/3b6112c04c50?raw)