People search

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

Changed on

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.

post/people/searches

Request

  • Base URL
    https://app.pumpgtm.com/api/v1
  • Auth
    HTTP bearer

Headers

X-PumpGTM-Clientstring uuid

Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace.

X-PumpGTM-Userstring

Enterprise partners: act on one end user's workspace using the partner key (a workspace or Team owner key; a personal key gets 403 partner_key_required). Requires the outreach capability on the partner account (403 enterprise_required otherwise); the user must exist and be active (404 user_not_found, 403 user_disabled). Never send it together with X-PumpGTM-Client (400 invalid_request). Omit to use the key's own workspace, unless the partner account has rest.requireUserHeader on (PATCH /api/partner/v1/account): then any /api/v1 request without it is 400 user_header_required and nothing runs.

Request body

OR

Response

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

object required

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

Changes

    • info

      the response property became required for the status

    • info

      the response property became required for the status

    • info

      the response property became required for the status

    • info

      the response property became required for the status

    • info

      the response property became required for the status

    • info

      the response property became required for the status

    • info

      the response property became required for the status

    • info

      the response property became required for the status

    • info

      the response property became required for the status

    • info

      endpoint added