---
title: "Add people to a Play"
method: POST
path: "/plays/{id}/leads"
tags: ["Plays"]
---

# Add people to a Play

`POST /plays/{id}/leads`

## Request

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

Works on any Play. Send leads: 1 to 500 people, each with at least one of linkedinUrl, email or xUsername. They go straight into the Play's sequence and are tagged with the Play, so they show in GET /plays/{id}/leads. Each person is queued for the channels the sequence has steps for; people already known by LinkedIn, email or X handle are skipped. Your request is the approval: a draft sequence is approved and started; a paused sequence takes the people and stays paused. Nothing is sent in this call; an active sequence sends in its next working window. 409 play_has_no_sequence when the Play has none. Reusing requestId with the same body replays the stored result. The older body with candidateIds behaves exactly like POST /plays/{id}/enroll.

## Path parameters

- `id` string, uuid, required

## Headers

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

## Request body

- union
  - object
    - `requestId` string: Optional idempotency key; reuse it only to retry this exact request. Omitted means a fresh request.
    - `leads` object[], required
      - `person` string, required
      - `company` string, nullable
      - `title` string, nullable
      - `linkedinUrl` string, nullable: Public LinkedIn /in/ profile URL.
      - `email` string, email, nullable
      - `xUsername` string, nullable: X handle (with or without @) or x.com profile URL.
  - object
    - `expectedRevision` integer, required: Current saved revision. Fetch again after a 409; do not silently retry a changed plan.
    - `sequenceId` string, uuid, required
    - `sequenceRevision` integer, required: Current saved revision. Fetch again after a 409; do not silently retry a changed plan.
    - `candidateIds` string[], required

## Response `201`

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

- object
  - `playId` string, uuid, required
  - `addResult` object, required: { method: "contacts", batchId, status: "completed", sequenceId, sequenceStatus, reused, addedLeadIds[], summary: { submittedCount, addedCount, duplicatesSkipped, invalidSkipped, alreadyInvitedCount }, contacted: false, energyCharged: 0 }

## 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/leads/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)