---
title: "Create an end user's workspace"
method: POST
path: "/users"
tags: ["Partner"]
---

# Create an end user's workspace

`POST /users`

## Request

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

Creates the isolated workspace for one end user before any MCP or REST traffic. Idempotent: 201 when created, 200 unchanged when the user already existed (monthlyLeadCap is then not applied; use PATCH). The response carries the user's mcpUrl (https://mcp.pumpgtm.com/mcp/u/{externalUserId}) and, once outreach is enabled on the partner account, rest: { header: "X-PumpGTM-User", value } and outreach: "enabled"; until then rest is null and outreach is "disabled". 400 invalid_external_user_id, 400 invalid_monthly_lead_cap.

## Request body

- object
  - `externalUserId` string, required: Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters.
  - `name` string
  - `monthlyLeadCap` integer, nullable: People search cap for this user per period; null means no cap.

## Response `200`

The user already existed; returned unchanged.

- object
  - `externalUserId` string, required: Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters.
  - `name` string, nullable, required
  - `createdAt` string, required
  - `status` 'active' | 'disabled', required
  - `monthlyLeadCap` integer, nullable, required: People search cap for this user per period; null means no cap.
  - `mcpUrl` string, required: https://mcp.pumpgtm.com/mcp/u/{externalUserId}
  - `rest` object, nullable, required: The header to add to /api/v1 requests to act for this user. null until outreach is enabled on the partner account.
    - `header` 'X-PumpGTM-User', required
    - `value` string, required
  - `outreach` 'enabled' | 'disabled', required: disabled until PumpGTM enables outreach on the partner account.

## Other responses

- `201`: Successful response. Read outcome fields; success does not imply delivery.
- `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/users/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)