---
title: "Import external leads for review"
method: POST
path: "/plays/{id}/import"
tags: ["Manual review"]
---

# Import external leads for review

`POST /plays/{id}/import`

## Request

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

Requires an enabled, non-archived, manual-review Play. Resolve known handles first, then submit numeric IDs. Names are caller-provided display labels, not verified identity evidence. The operation is atomic: 1–100 unique IDs. requestId is scoped to workspace + Play; retry the exact same normalized payload for the stored result. Reusing it with changed inputs returns 409. Existing candidates retain their review state. Import does not verify followers, enroll, change sequence status or send. Duplicate candidate records produce 409.

## Path parameters

- `id` string, uuid, required

## Headers

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

## Request body

- object
  - `requestId` string, required
  - `expectedRevision` integer, required: Current saved revision. Fetch again after a 409; do not silently retry a changed plan.
  - `leads` object[], required
    - `xUserId` string, required: Numeric X user ID as a string. Never convert it to a JavaScript number.
    - `name` string
    - `reference` string

## Response `200`

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

- object
  - `playId` string, uuid, required
  - `batchId` string, uuid, required
  - `requestId` string, required
  - `replayed` boolean, required
  - `results` object[], required
    - `xUserId` string, required: Numeric X user ID as a string. Never convert it to a JavaScript number.
    - `reference` string, nullable, required
    - `candidateId` string, uuid, required
    - `result` 'imported' | 'existing_candidate', required
  - `enrolled` unknown, required
  - `sendsMessages` unknown, 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/import/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)