---
title: "Find existing candidates by X identity"
method: POST
path: "/plays/{id}/candidates/lookup"
tags: ["Manual review"]
---

# Find existing candidates by X identity

`POST /plays/{id}/candidates/lookup`

## Request

- Base URL: `https://app.pumpgtm.com/api/v1`
- URL: `https://app.pumpgtm.com/api/v1/plays/{id}/candidates/lookup`
- Auth: HTTP bearer

Exact identity lookup across all saved Play batches. Each identity requires xUserId OR username. Ambiguous matches return 409; use numeric IDs or the candidate list. This endpoint does not check a live follower relationship.

## Path parameters

- `id` string, uuid, required

## Headers

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

## Request body

- object
  - `identities` union[], required
    - union
      - object
        - `xUserId` string, required: Numeric X user ID as a string. Never convert it to a JavaScript number.
        - `username` string: Public X handle, with optional @. Case-insensitive.
      - object
        - `xUserId` string: Numeric X user ID as a string. Never convert it to a JavaScript number.
        - `username` string, required: Public X handle, with optional @. Case-insensitive.

## Response `200`

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

- object
  - `playId` string, uuid, required
  - `results` object[], required
    - `exists` boolean
    - `candidate` object, nullable
      - `id` string, uuid, required
      - `xUserId` string, required: Numeric X user ID as a string. Never convert it to a JavaScript number.
      - `username` string, nullable, required
      - `name` string, nullable, required
      - `status` 'proposed' | 'approved' | 'imported' | 'rejected', required
      - `review` object, nullable, required
    - `enrolledInPlay` boolean
    - `currentFollowerStatus` 'unknown'
    - `existingLeads` object[]
      - `id` string, uuid, required
      - `sequenceId` string, uuid, nullable, required
      - `playId` string, uuid, nullable, required
      - `stage` string, required

## Other responses

- `400`: Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User
- `401`: Missing, invalid or revoked key
- `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`: 8 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 `403`
  - the response property `error` became required for the status `404`
  - …4 more
- **2026-10-12** `08c80059d483`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/pumpgtm/apis/pumpgtm-api/changes/plays/:id/candidates/lookup/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)