---
title: "Create or revise a people-search Play and optionally run it"
method: POST
path: "/people/searches"
tags: ["People search"]
---

# Create or revise a people-search Play and optionally run it

`POST /people/searches`

## Request

- Base URL: `https://app.pumpgtm.com/api/v1`
- URL: `https://app.pumpgtm.com/api/v1/people/searches`
- Auth: HTTP bearer

Find people from a targeting, the same way the PumpGTM agent does. Provide targeting (creates a Play, or revises playId at expectedRevision, the play.revision from the previous response), a playId alone (use the Play as is), or both. run: false (default) prepares and returns 200 with the targeting summary; run: true searches and returns 201 with the review batch and candidates. requestId is required when run is true: a run is billed, so a retry must carry the same requestId to replay the stored result (reused: true) instead of searching and charging again. sequenceId becomes the Play's default sequence (a draft is approved and started). A run crawls toward candidateCount, up to 100 people; each person found costs 2 Energy on metered workspaces (drawn from the partner pool for partner users) or, for partners without Energy, counts toward partner lead metering (50 free, then 403 billing_required with a checkout link in message). Finding people never contacts anyone. 409 targeting_needs_clarification with ambiguities when targeting is incomplete; company-name ambiguity never blocks (read companyResolution). 409 draft_changed when the Play changed since expectedRevision. 403 user_lead_cap_reached or billing_required for a partner user who may not search.

## Headers

- `X-PumpGTM-Client` string, uuid
- `X-PumpGTM-User` string

## Request body

- union
  - object
    - `targeting` object, required
      - `schemaVersion` unknown
      - `name` string, required: A short customer-facing name for this search.
      - `candidateCount` integer, required: The exact number of candidates to return.
      - `hardFilters` object, required
        - `currentTitleIncludesAny` string[], required: Alternative literal phrases; a person's current title must contain at least one.
        - `currentFunctionsAny` string[]: Alternative current job functions. Use only when non-negotiable. One of the listed values only.
        - `currentSenioritiesAny` string[]: Alternative current seniority levels. Use only when non-negotiable. One of the listed values only; put finer wording such as Head of or SVP in semanticQuery.
        - `personCountriesAny` string[]: Alternative countries where the person must be located.
        - `currentCompanyNamesAny` string[]: Alternative exact current-employer names, only for a named account list.
        - `currentCompanyDomainsAny` string[]: Alternative exact current-employer website domains; a domain pins one company exactly.
        - `currentCompanyLinkedInUrlsAny` string[]: Alternative current-employer LinkedIn company URLs.
        - `currentCompanyIndustriesAny` string[]: Alternative canonical company industries.
        - `currentCompanyTypesAny` string[]: Alternative canonical company ownership types.
        - `currentCompanyHeadcount` object
          - `minimum` integer
          - `maximum` integer
        - `currentCompanyInvestorsAny` string[]: Alternative canonical investors or accelerators backing the current company (Y Combinator, not YC).
        - `currentCompanyHiringRolesAny` string[]: Alternative role phrases the current company must have an open job posting for right now.
        - `currentCompanyHiringPostedWithinDays` integer: Defaults to 30 when hiring roles are given.
        - `excludedCurrentFunctionsAny` string[]: Current job functions that must be excluded. One of the listed values only.
        - `excludedCurrentSenioritiesAny` string[]: Current seniority levels that must be excluded. One of the listed values only; put finer wording such as Head of or SVP in semanticQuery.
        - `excludedCurrentCompanyNamesAny` string[]: Exact current-employer names that must be excluded.
        - `excludedCurrentCompanyTypesAny` string[]: Company ownership types that must be excluded.
      - `semanticQuery` string: Plain-language description of product, workload, responsibility and business-model fit. Descriptive requirements go here, not in hard filters.
      - `defaultSequenceId` string, uuid, nullable
    - `playId` string, uuid
    - `expectedRevision` integer: Current saved revision. Fetch again after a 409; do not silently retry a changed plan.
    - `sequenceId` string, uuid
    - `run` boolean
    - `requestId` string: Optional idempotency key; reuse it only to retry this exact request. Omitted means a fresh request.
  - object
    - `targeting` object
      - `schemaVersion` unknown
      - `name` string, required: A short customer-facing name for this search.
      - `candidateCount` integer, required: The exact number of candidates to return.
      - `hardFilters` object, required
        - `currentTitleIncludesAny` string[], required: Alternative literal phrases; a person's current title must contain at least one.
        - `currentFunctionsAny` string[]: Alternative current job functions. Use only when non-negotiable. One of the listed values only.
        - `currentSenioritiesAny` string[]: Alternative current seniority levels. Use only when non-negotiable. One of the listed values only; put finer wording such as Head of or SVP in semanticQuery.
        - `personCountriesAny` string[]: Alternative countries where the person must be located.
        - `currentCompanyNamesAny` string[]: Alternative exact current-employer names, only for a named account list.
        - `currentCompanyDomainsAny` string[]: Alternative exact current-employer website domains; a domain pins one company exactly.
        - `currentCompanyLinkedInUrlsAny` string[]: Alternative current-employer LinkedIn company URLs.
        - `currentCompanyIndustriesAny` string[]: Alternative canonical company industries.
        - `currentCompanyTypesAny` string[]: Alternative canonical company ownership types.
        - `currentCompanyHeadcount` object
          - `minimum` integer
          - `maximum` integer
        - `currentCompanyInvestorsAny` string[]: Alternative canonical investors or accelerators backing the current company (Y Combinator, not YC).
        - `currentCompanyHiringRolesAny` string[]: Alternative role phrases the current company must have an open job posting for right now.
        - `currentCompanyHiringPostedWithinDays` integer: Defaults to 30 when hiring roles are given.
        - `excludedCurrentFunctionsAny` string[]: Current job functions that must be excluded. One of the listed values only.
        - `excludedCurrentSenioritiesAny` string[]: Current seniority levels that must be excluded. One of the listed values only; put finer wording such as Head of or SVP in semanticQuery.
        - `excludedCurrentCompanyNamesAny` string[]: Exact current-employer names that must be excluded.
        - `excludedCurrentCompanyTypesAny` string[]: Company ownership types that must be excluded.
      - `semanticQuery` string: Plain-language description of product, workload, responsibility and business-model fit. Descriptive requirements go here, not in hard filters.
      - `defaultSequenceId` string, uuid, nullable
    - `playId` string, uuid, required
    - `expectedRevision` integer: Current saved revision. Fetch again after a 409; do not silently retry a changed plan.
    - `sequenceId` string, uuid
    - `run` boolean
    - `requestId` string: Optional idempotency key; reuse it only to retry this exact request. Omitted means a fresh request.

## Response `200`

Successful response. Read outcome fields; success does not imply delivery.

- object: Prepared (200): { play: { id, revision }, plan, ambiguities: [], companyResolution, readyToRun, reviewUrl?, searched: false, contacted: false }. Run (201): { play: { id, revision }, batch: { id, status: draft | sample_ready | approved | imported | rejected, ... }, candidates: [{ id, person, title, company, linkedinUrl, decision: undecided | approved | rejected, ... }], reviewUrl?, searched: true, contacted: false }.

## Other responses

- `201`: Search ran: review batch and candidates returned; nobody was contacted.
- `400`: Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User
- `401`: Missing, invalid or revoked key
- `402`: energy_exhausted: this metered workspace has no Energy left for the action; nothing changed. Follow topUpUrl.
- `403`: Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled
- `404`: Resource unavailable in this workspace
- `409`: Revision, identity or state conflict: { error, message } and nothing changed
- `429`: Rate limit; respect Retry-After when provided
- `500`: internal_error: an unexpected failure on our side; retry, then contact PumpGTM
- `503`: Dependency unavailable; identity may be unknown

## Changes

- **2026-10-12** `06d2e4d0e84b`: 9 info
  - the response property `error` became required for the status `400`
  - the response property `error` became required for the status `401`
  - the response property `error` became required for the status `402`
  - the response property `error` became required for the status `403`
  - …5 more
- **2026-10-12** `08c80059d483`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/pumpgtm/apis/pumpgtm-api/changes/people/searches/post.md)

---

[API](https://skmtc.dev/pumpgtm/apis/pumpgtm-api.md) - [All operations](https://skmtc.dev/pumpgtm/apis/pumpgtm-api/llms.txt) - [OpenAPI document](https://skmtc.dev/pumpgtm/apis/pumpgtm-api/revisions/06d2e4d0e84b?raw)