{ "openapi": "3.1.0", "info": { "title": "PumpGTM API", "version": "1.1.0", "description": "Run outreach from your own backend or agent: plain REST for sequences, leads, people search, replies and webhooks; adding people to any Play in one call; X follower checks; and the Partner API for agencies and platforms that run PumpGTM for many end users from one account (hosted LinkedIn connect links, per-user workspaces, X-PumpGTM-User). The workspace MCP key also authenticates REST. Start at https://app.pumpgtm.com/docs/api. No browser session required. Versioning: the major version is in the path (/api/v1); v1 only gains fields. A breaking change ships under a new major path while v1 keeps working, and anything scheduled for removal answers with Deprecation: true and a Sunset header at least 90 days ahead (policy: https://pumpgtm.com/docs/api#versioning).", "contact": { "url": "https://pumpgtm.com" } }, "servers": [ { "url": "https://app.pumpgtm.com/api/v1", "description": "Production" }, { "url": "https://app.pumpgtm.com/api/partner/v1", "description": "Partner API (partner workspace key)" } ], "security": [ { "WorkspaceKey": [] } ], "tags": [ { "name": "Plays", "description": "A Play finds or receives people and messages them with its sequence. Add your own people to any Play with POST /plays/{id}/leads." }, { "name": "Sequences", "description": "The messages a Play or lead list sends, across LinkedIn, email and X." }, { "name": "Leads", "description": "Add people straight to a sequence, read and stop leads, and look up X identities." }, { "name": "Replies", "description": "Read replies waiting on you and answer them." }, { "name": "Results", "description": "Pace, funnel and the activity ledger." }, { "name": "Webhooks", "description": "Signed events for replies, leads and connections." }, { "name": "People search", "description": "Find and enrich people, and read buying signals." }, { "name": "Account", "description": "Workspaces, connected accounts, sending limits and Energy." }, { "name": "Manual review", "description": "Advanced. Approve people one by one before a Play messages them. Most integrations never need this; use POST /plays/{id}/leads instead." }, { "name": "Partner", "description": "Run PumpGTM for many clients with one key." } ], "paths": { "/plays/{id}/leads": { "post": { "operationId": "addPlayLeads", "tags": [ "Plays" ], "summary": "Add people to a Play", "description": "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.", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "requestId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{7,119}$", "description": "Optional idempotency key; reuse it only to retry this exact request. Omitted means a fresh request." }, "leads": { "type": "array", "items": { "type": "object", "properties": { "person": { "type": "string", "minLength": 1, "maxLength": 200 }, "company": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "linkedinUrl": { "anyOf": [ { "type": "string", "maxLength": 500, "description": "Public LinkedIn /in/ profile URL." }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string", "format": "email", "maxLength": 320 }, { "type": "null" } ] }, "xUsername": { "anyOf": [ { "type": "string", "maxLength": 500, "description": "X handle (with or without @) or x.com profile URL." }, { "type": "null" } ] } }, "required": [ "person" ], "additionalProperties": false }, "minItems": 1, "maxItems": 500 } }, "required": [ "leads" ], "additionalProperties": false }, { "type": "object", "properties": { "expectedRevision": { "type": "integer", "minimum": 1, "description": "Current saved revision. Fetch again after a 409; do not silently retry a changed plan." }, "sequenceId": { "type": "string", "format": "uuid" }, "sequenceRevision": { "type": "integer", "minimum": 1, "description": "Current saved revision. Fetch again after a 409; do not silently retry a changed plan." }, "candidateIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 200, "uniqueItems": true } }, "required": [ "expectedRevision", "sequenceId", "sequenceRevision", "candidateIds" ], "additionalProperties": false } ] }, "example": { "requestId": "crm-sync-20261012-001", "leads": [ { "person": "Jane Doe", "xUsername": "janedoe", "email": "jane@acme.com" } ] } } } }, "responses": { "201": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "playId": { "type": "string", "format": "uuid" }, "addResult": { "type": "object", "additionalProperties": true, "description": "{ method: \"contacts\", batchId, status: \"completed\", sequenceId, sequenceStatus, reused, addedLeadIds[], summary: { submittedCount, addedCount, duplicatesSkipped, invalidSkipped, alreadyInvitedCount }, contacted: false, energyCharged: 0 }" } }, "required": [ "playId", "addResult" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "listEnrolledPlayLeads", "tags": [ "Plays" ], "summary": "List the Play's leads", "description": "Leads in the selected Play, from its runs or added with POST /plays/{id}/leads, with stable cursor pagination. Use each lead ID to read detailed state or stop its automation.", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Pass nextCursor from the previous response until null." } ], "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "playId": { "type": "string", "format": "uuid" }, "leads": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "linkedinUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "xUserId": { "anyOf": [ { "type": "string", "pattern": "^[1-9][0-9]{0,19}$", "description": "Numeric X user ID as a string. Never convert it to a JavaScript number." }, { "type": "null" } ] }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sequenceId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "stage": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "name", "linkedinUrl", "email", "xUserId", "username", "sequenceId", "stage", "createdAt" ] } }, "nextCursor": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "hasMore": { "type": "boolean" } }, "required": [ "playId", "leads", "nextCursor", "hasMore" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/x/watches": { "post": { "operationId": "createXWatch", "tags": [ "Plays" ], "summary": "Create an X Play", "description": "From now on, people who follow the account (followers), engage with any post (every_post) or engage with one post (post, with postUrl) are collected for review and then DMed with the sequence. Pass exactly one of message (a one-step DM sequence is created; customer credential required) or sequenceId (an existing X sequence). Nothing is sent in this call. 409 x_not_connected when the account is not connected.", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "enum": [ "followers", "every_post", "post" ] }, "postUrl": { "type": "string", "format": "uri", "description": "Required when source is post: an x.com/{user}/status/{id} URL." }, "message": { "type": "string", "maxLength": 2000 }, "sequenceId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "as": { "type": "string", "pattern": "^@?[A-Za-z0-9_]{1,15}$", "description": "Connected account to act as; defaults to the workspace's account." } }, "required": [ "source" ], "oneOf": [ { "required": [ "message" ] }, { "required": [ "sequenceId" ] } ] }, "example": { "source": "followers", "message": "Thanks for the follow, {{firstName}}! What are you building?" } } } }, "responses": { "201": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "source": { "type": "string" }, "postId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sequenceId": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "as": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "peopleSeen": { "type": "integer" }, "waitingForReview": { "type": "integer" }, "createdAt": { "type": "string" } }, "required": [ "id", "source", "postId", "sequenceId", "status", "as", "peopleSeen", "waitingForReview", "createdAt" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "listXWatches", "tags": [ "Plays" ], "summary": "List X Plays with people waiting and funnels", "description": "Every X Play (a follower or post-engager watch plus its DM sequence) with how many people are waiting for review and the sequence funnel. Requires the X channel (403 x_channel_disabled otherwise).", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." } ], "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "watches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "source": { "enum": [ "followers", "every_post", "post" ] }, "postId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sequenceId": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "as": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "peopleSeen": { "type": "integer" }, "waitingForReview": { "type": "integer" }, "createdAt": { "type": "string" }, "funnel": { "type": "object", "additionalProperties": true } }, "required": [ "id", "source", "postId", "sequenceId", "status", "as", "peopleSeen", "waitingForReview", "createdAt", "funnel" ], "additionalProperties": true } } }, "required": [ "watches" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/workspaces": { "get": { "operationId": "listWorkspaces", "tags": [ "Account" ], "summary": "List accessible workspaces", "description": "Use the MCP key without X-PumpGTM-Client. Returns only its workspace and permitted Team workspaces. Select a returned ID on subsequent requests; a header never grants access.", "parameters": [], "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workspaces": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "role": { "enum": [ "owner", "admin", "member" ] } }, "required": [ "id" ] } } }, "required": [ "workspaces" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/x/accounts": { "get": { "operationId": "listXAccounts", "tags": [ "Account" ], "summary": "List connected X identities", "description": "Read saved account identities. No provider health check or OAuth refresh.", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." } ], "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$", "description": "Numeric X user ID as a string. Never convert it to a JavaScript number." }, "handle": { "type": "string" } }, "required": [ "userId", "handle" ] } } }, "required": [ "accounts" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/x/readiness": { "get": { "operationId": "getXReadiness", "tags": [ "Account" ], "summary": "Read account, billing and Energy state", "description": "Read-only snapshot. Check each section's state/issues; data may be null. Provider health is unverified. A connection or positive follower result does not guarantee delivery.", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." } ], "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" }, "asOf": { "type": "string" }, "accounts": { "type": "object", "properties": { "state": { "enum": [ "complete", "partial", "unavailable" ] }, "observedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "data": { "anyOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ] }, "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "message", "retryable" ] } } }, "required": [ "state", "observedAt", "data", "issues" ] }, "billing": { "type": "object", "properties": { "state": { "enum": [ "complete", "partial", "unavailable" ] }, "observedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "data": { "anyOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ] }, "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "message", "retryable" ] } } }, "required": [ "state", "observedAt", "data", "issues" ] }, "energy": { "type": "object", "properties": { "state": { "enum": [ "complete", "partial", "unavailable" ] }, "observedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "data": { "anyOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ] }, "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "message", "retryable" ] } } }, "required": [ "state", "observedAt", "data", "issues" ] }, "providerHealthChecked": { "const": false }, "deliveryGuaranteed": { "const": false }, "note": { "type": "string" } }, "required": [ "workspaceId", "asOf", "accounts", "billing", "energy", "providerHealthChecked", "deliveryGuaranteed", "note" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/energy": { "get": { "operationId": "getEnergy", "tags": [ "Account" ], "summary": "Read this period's Energy balance", "description": "Energy for the current month on a metered workspace: allowance, used, remaining, per-action costs and cents per Energy. { enabled: false } when the workspace is not metered. Partner end users draw from the partner's pool. A balance is not a reservation.", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." } ], "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "used": { "type": "integer" }, "remaining": { "type": "integer" }, "periodStart": { "type": "string" }, "costs": { "type": "object", "additionalProperties": true }, "centsPerEnergy": { "type": "number" } }, "required": [ "enabled" ], "additionalProperties": true } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/x/users/resolve": { "post": { "operationId": "resolveXIdentity", "tags": [ "Leads" ], "summary": "Resolve a handle to a numeric X ID", "description": "One exact public handle lookup through the public X data provider. No email-to-X enrichment or fuzzy identity matching. An unverified or unavailable profile returns HTTP 503 with status unknown and user null. No official X fallback.", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string", "pattern": "^@?[A-Za-z0-9_]{1,15}$", "description": "Public X handle, with optional @. Case-insensitive." } }, "required": [ "username" ], "additionalProperties": false }, "example": { "username": "example_handle" } } } }, "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "resolved" }, "user": { "type": "object", "properties": { "xUserId": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$", "description": "Numeric X user ID as a string. Never convert it to a JavaScript number." }, "username": { "type": "string" }, "name": { "type": "string" }, "checkedAt": { "type": "string" }, "evidence": { "const": "public_profile" } }, "required": [ "xUserId", "username", "name", "checkedAt", "evidence" ] }, "provider": { "const": "twitterapi" }, "sendsMessages": { "const": false } }, "required": [ "status", "user", "provider", "sendsMessages" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/x/eligibility": { "post": { "operationId": "checkXFollowerEligibility", "tags": [ "Leads" ], "summary": "Check whether leads follow your account", "description": "Direction: the lead follows the connected account. Supply exactly one X identity per lead. Handles use direct relationship evidence. Numeric IDs use a bounded public follower snapshot: presence is true; absence is null, never a verified false. null means unknown, not eligible or ineligible. Provider errors can produce HTTP 200 with unknown individual results. Up to 100 leads; sequential work is time bounded, so small batches are preferable. Per-instance short cache may be reused; checkedAt is evidence time. No messages are sent.", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "type": "string", "pattern": "^@?[A-Za-z0-9_]{1,15}$", "description": "Public X handle, with optional @. Case-insensitive." }, "leads": { "type": "array", "items": { "type": "object", "properties": { "reference": { "type": "string", "maxLength": 200 }, "xUsername": { "type": "string", "pattern": "^@?[A-Za-z0-9_]{1,15}$", "description": "Public X handle, with optional @. Case-insensitive." }, "xUserId": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$", "description": "Numeric X user ID as a string. Never convert it to a JavaScript number." } }, "required": [], "additionalProperties": false, "oneOf": [ { "required": [ "xUsername" ] }, { "required": [ "xUserId" ] } ] }, "minItems": 1, "maxItems": 100 } }, "required": [ "account", "leads" ], "additionalProperties": false }, "example": { "account": "mastra", "leads": [ { "reference": "crm-123", "xUsername": "example_handle" } ] } } } }, "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "properties": { "reference": { "type": "string" }, "xUsername": { "type": "string" }, "xUserId": { "anyOf": [ { "type": "string", "pattern": "^[1-9][0-9]{0,19}$", "description": "Numeric X user ID as a string. Never convert it to a JavaScript number." }, { "type": "null" } ] }, "followsAccount": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "checkedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "evidence": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "xUserId", "followsAccount", "checkedAt", "reason", "evidence" ] } }, "provider": { "const": "twitterapi" }, "sendsMessages": { "const": false } }, "required": [ "account", "results", "provider", "sendsMessages" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/leads/enrich": { "post": { "operationId": "enrichLeadIdentities", "tags": [ "Leads" ], "summary": "Bridge emails or LinkedIn URLs to X identities", "description": "Up to 20 leads, each with one email or one public LinkedIn profile URL. Emails resolve to a LinkedIn identity first; only exact, source-governed public profile links then bridge LinkedIn to X. No name matching or fuzzy identity guesses. Results may be unavailable per lead; nothing is enrolled or sent.", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "leads": { "type": "array", "items": { "type": "object", "properties": { "reference": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "maxLength": 320 }, "linkedinUrl": { "type": "string", "maxLength": 1500, "description": "Public linkedin.com/in/... profile URL." } }, "required": [], "additionalProperties": false, "oneOf": [ { "required": [ "email" ] }, { "required": [ "linkedinUrl" ] } ] }, "minItems": 1, "maxItems": 20 } }, "required": [ "leads" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/signals": { "get": { "operationId": "listSignalTypes", "tags": [ "People search" ], "summary": "Discover Signals API availability", "description": "Lists available event types and coming-soon roadmap categories. Only available types can be read.", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." } ], "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/signals/events": { "post": { "operationId": "listSignalEvents", "tags": [ "People search" ], "summary": "Read events for an available signal type", "description": "Read-only shared-index developer preview. No Energy charged or paid collection. Stable event IDs, workspace/filter-bound cursors. start=now bootstraps future observations; recent reads up to 30 days. Cursor expires after 7 days. Collection is demand-driven; no coverage or cadence guarantee.", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "const": "hiring.job_observed" }, "filters": { "type": "object", "properties": { "roles": { "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 100 }, "minItems": 1, "maxItems": 10 }, "companyDomains": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 253 }, "minItems": 1, "maxItems": 20 }, "minHeadcount": { "type": "integer", "minimum": 1 }, "maxHeadcount": { "type": "integer", "minimum": 1 } }, "required": [], "additionalProperties": false }, "cursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 3000 }, { "type": "null" } ] }, "start": { "enum": [ "now", "recent" ], "default": "recent" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired cursor; bootstrap again and deduplicate event IDs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request larger than 8 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Index temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/people/enrich": { "post": { "operationId": "enrichPerson", "tags": [ "People search" ], "summary": "Enrich one person by email or LinkedIn URL", "description": "Send exactly one of email or linkedin; an email is matched to a LinkedIn profile first. Returns { id, person, missing?, energyUsed }. person is null when nobody matches; otherwise name, title, headline, location, company {name, domain}, linkedin, x, workEmail, and connections when any are observed. find adds paid extras: x (their X account, only with public evidence it is theirs) and work_email. A requested extra that did not come back appears in missing with a reason. Energy-priced on metered workspaces (402 when exhausted, nothing charged). Request body is limited to 4 KB (413). Nothing is stored on a lead or sent.", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 320, "description": "Email address to match to a LinkedIn profile. Omit when sending linkedin." }, "linkedin": { "type": "string", "maxLength": 1500, "description": "Public linkedin.com/in/... profile URL. Omit when sending email." }, "find": { "type": "array", "items": { "enum": [ "x", "work_email" ] }, "maxItems": 2, "default": [] } }, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "energy_exhausted: this metered workspace has no Energy left for the action; nothing changed. Follow topUpUrl.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body larger than 4 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/x/plays": { "get": { "operationId": "listXPlays", "tags": [ "Manual review" ], "summary": "Discover X Plays and their revisions", "description": "Use reviewApiEnabled to identify Plays supporting candidate review, import, lookup and enrollment. Plays must be explicitly enabled for review APIs. Autopilot Plays cannot use manual import/enrollment.", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." } ], "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "plays": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "enum": [ "active", "paused", "archived" ] }, "revision": { "type": "integer", "minimum": 1, "description": "Current saved revision. Fetch again after a 409; do not silently retry a changed plan." }, "sequenceId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "accountUserId": { "anyOf": [ { "type": "string", "pattern": "^[1-9][0-9]{0,19}$", "description": "Numeric X user ID as a string. Never convert it to a JavaScript number." }, { "type": "null" } ] }, "reviewApiEnabled": { "type": "boolean" }, "autopilot": { "type": "boolean" } }, "required": [ "id", "name", "status", "revision", "sequenceId", "accountUserId", "reviewApiEnabled", "autopilot" ] } } }, "required": [ "plays" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/plays/{id}/candidates": { "get": { "operationId": "listPlayCandidates", "tags": [ "Manual review" ], "summary": "Page through review candidates", "description": "Saved review candidates, not evidence of a current follow relationship. Returns Play and sequence revisions for guarded enrollment. Cursor paging covers all batches.", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Pass nextCursor from the previous response until null." }, { "name": "filter", "in": "query", "schema": { "enum": [ "all", "unreviewed", "good_fit", "not_a_good_fit" ], "default": "all" } } ], "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "counts": { "type": "object", "properties": { "total": { "type": "integer" }, "unreviewed": { "type": "integer" }, "goodFit": { "type": "integer" }, "notAGoodFit": { "type": "integer" } }, "required": [ "total", "unreviewed", "goodFit", "notAGoodFit" ] }, "candidates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "xUserId": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$", "description": "Numeric X user ID as a string. Never convert it to a JavaScript number." }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "enum": [ "proposed", "approved", "imported", "rejected" ] }, "review": { "anyOf": [ { "type": "object" }, { "type": "null" } ] } }, "required": [ "id", "xUserId", "username", "name", "status", "review" ] } }, "nextCursor": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "play": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "revision": { "type": "integer", "minimum": 1, "description": "Current saved revision. Fetch again after a 409; do not silently retry a changed plan." }, "status": { "type": "string" } }, "required": [ "id", "name", "revision", "status" ] }, "sequence": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "revision": { "type": "integer", "minimum": 1, "description": "Current saved revision. Fetch again after a 409; do not silently retry a changed plan." }, "status": { "type": "string" }, "approved": { "type": "boolean" } }, "required": [ "id", "name", "revision", "status", "approved" ] }, { "type": "null" } ] }, "reviewUrl": { "type": "string" } }, "required": [ "counts", "candidates", "nextCursor", "play", "sequence", "reviewUrl" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/plays/{id}/candidates/lookup": { "get": { "operationId": "lookupPlayCandidate", "tags": [ "Manual review" ], "summary": "Find one existing candidate by X identity", "description": "Single-identity form of the POST lookup: pass xUserId or username as a query parameter. Exact lookup across all saved Play batches; ambiguous matches return 409. Does not check a live follower relationship.", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "xUserId", "in": "query", "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$", "description": "Numeric X user ID as a string. Never convert it to a JavaScript number." } }, { "name": "username", "in": "query", "schema": { "type": "string", "pattern": "^@?[A-Za-z0-9_]{1,15}$", "description": "Public X handle, with optional @. Case-insensitive." } } ], "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "exists": { "type": "boolean" }, "candidate": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "xUserId": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$", "description": "Numeric X user ID as a string. Never convert it to a JavaScript number." }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "enum": [ "proposed", "approved", "imported", "rejected" ] }, "review": { "anyOf": [ { "type": "object" }, { "type": "null" } ] } }, "required": [ "id", "xUserId", "username", "name", "status", "review" ] }, { "type": "null" } ] }, "enrolledInPlay": { "type": "boolean" }, "currentFollowerStatus": { "const": "unknown" }, "existingLeads": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sequenceId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "playId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "stage": { "type": "string" } }, "required": [ "id", "sequenceId", "playId", "stage" ] } } }, "required": [ "exists", "candidate", "enrolledInPlay", "currentFollowerStatus", "existingLeads" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "lookupPlayCandidates", "tags": [ "Manual review" ], "summary": "Find existing candidates by X identity", "description": "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.", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "identities": { "type": "array", "items": { "type": "object", "properties": { "xUserId": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$", "description": "Numeric X user ID as a string. Never convert it to a JavaScript number." }, "username": { "type": "string", "pattern": "^@?[A-Za-z0-9_]{1,15}$", "description": "Public X handle, with optional @. Case-insensitive." } }, "required": [], "additionalProperties": false, "oneOf": [ { "required": [ "xUserId" ] }, { "required": [ "username" ] } ] }, "minItems": 1, "maxItems": 200 } }, "required": [ "identities" ], "additionalProperties": false }, "example": { "identities": [ { "xUserId": "123456789" } ] } } } }, "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "playId": { "type": "string", "format": "uuid" }, "results": { "type": "array", "items": { "type": "object", "properties": { "exists": { "type": "boolean" }, "candidate": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "xUserId": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$", "description": "Numeric X user ID as a string. Never convert it to a JavaScript number." }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "enum": [ "proposed", "approved", "imported", "rejected" ] }, "review": { "anyOf": [ { "type": "object" }, { "type": "null" } ] } }, "required": [ "id", "xUserId", "username", "name", "status", "review" ] }, { "type": "null" } ] }, "enrolledInPlay": { "type": "boolean" }, "currentFollowerStatus": { "const": "unknown" }, "existingLeads": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sequenceId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "playId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "stage": { "type": "string" } }, "required": [ "id", "sequenceId", "playId", "stage" ] } } } } } }, "required": [ "playId", "results" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/plays/{id}/import": { "post": { "operationId": "importPlayCandidates", "tags": [ "Manual review" ], "summary": "Import external leads for review", "description": "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\u2013100 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.", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{7,119}$" }, "expectedRevision": { "type": "integer", "minimum": 1, "description": "Current saved revision. Fetch again after a 409; do not silently retry a changed plan." }, "leads": { "type": "array", "items": { "type": "object", "properties": { "xUserId": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$", "description": "Numeric X user ID as a string. Never convert it to a JavaScript number." }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "reference": { "type": "string", "maxLength": 200 } }, "required": [ "xUserId" ], "additionalProperties": false }, "minItems": 1, "maxItems": 100 } }, "required": [ "requestId", "expectedRevision", "leads" ], "additionalProperties": false }, "example": { "requestId": "crm-import-20261003-001", "expectedRevision": 1, "leads": [ { "xUserId": "123456789", "reference": "crm-123" } ] } } } }, "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "playId": { "type": "string", "format": "uuid" }, "batchId": { "type": "string", "format": "uuid" }, "requestId": { "type": "string" }, "replayed": { "type": "boolean" }, "results": { "type": "array", "items": { "type": "object", "properties": { "xUserId": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$", "description": "Numeric X user ID as a string. Never convert it to a JavaScript number." }, "reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "candidateId": { "type": "string", "format": "uuid" }, "result": { "enum": [ "imported", "existing_candidate" ] } }, "required": [ "xUserId", "reference", "candidateId", "result" ] } }, "enrolled": { "const": false }, "sendsMessages": { "const": false } }, "required": [ "playId", "batchId", "requestId", "replayed", "results", "enrolled", "sendsMessages" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/plays/{id}/enroll": { "post": { "operationId": "enrollPlayCandidates", "tags": [ "Manual review" ], "summary": "Approve candidates and enroll through the existing engine", "description": "Mutating action: marks selected candidates good fit and queues newly enrolled leads. Requires exact Play and sequence revisions and the Play's own connected sender/sequence. An active eligible sequence can send on its next engine run. Does not activate, approve or change the sequence itself. Existing leads (including stopped/replied leads) keep their original state and sequence. Repeating a completed good-fit review returns already_reviewed; conflicting review decisions return 409. POST /plays/{id}/leads with this same candidateIds body does the same.", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedRevision": { "type": "integer", "minimum": 1, "description": "Current saved revision. Fetch again after a 409; do not silently retry a changed plan." }, "sequenceId": { "type": "string", "format": "uuid" }, "sequenceRevision": { "type": "integer", "minimum": 1, "description": "Current saved revision. Fetch again after a 409; do not silently retry a changed plan." }, "candidateIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 200, "uniqueItems": true } }, "required": [ "expectedRevision", "sequenceId", "sequenceRevision", "candidateIds" ], "additionalProperties": false }, "example": { "expectedRevision": 1, "sequenceId": "00000000-0000-4000-8000-000000000001", "sequenceRevision": 1, "candidateIds": [ "00000000-0000-4000-8000-000000000002" ] } } } }, "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "candidateId": { "type": "string", "format": "uuid" }, "result": { "enum": [ "enrolled", "existing_lead", "already_reviewed", "rejected" ] }, "leadId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] } }, "required": [ "candidateId", "result", "leadId" ] } }, "sequenceStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sequenceStatusChanged": { "const": false }, "reviewUrl": { "type": "string" } }, "required": [ "results", "sequenceStatus", "sequenceStatusChanged", "reviewUrl" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/x/actions": { "post": { "operationId": "performXAction", "tags": [ "Leads" ], "summary": "Follow, like or repost as a connected account", "description": "One write as a connected X account: follow a profile URL or @handle, or like/repost a post URL. Never sends a DM or writes a post. Each successful write is one activity row and one Energy charge on metered workspaces (402 when exhausted). Requires the X channel; 409 x_not_connected when the account is not connected.", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "enum": [ "follow", "like", "repost" ] }, "target": { "type": "string", "description": "Profile URL or @handle for follow; post URL for like and repost." }, "as": { "type": "string", "pattern": "^@?[A-Za-z0-9_]{1,15}$", "description": "Connected account to act as; defaults to the workspace's account." } }, "required": [ "action", "target" ] }, "example": { "action": "follow", "target": "@example_handle" } } } }, "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string" }, "as": { "type": "string" }, "username": { "type": "string" }, "postId": { "type": "string" }, "done": { "const": true } }, "required": [ "action", "as", "done" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "energy_exhausted: this metered workspace has no Energy left for the action; nothing changed. Follow topUpUrl.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/x/leads/{id}": { "get": { "operationId": "getXLeadStatus", "tags": [ "Leads" ], "summary": "Read one lead's saved progress", "description": "Tenant-owned X lead only. Stage/milestones are saved observations, not a live provider probe. automationStopped means the sequence is done/stopped; it does not distinguish normal completion from a manual stop.", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "lead": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "xUserId": { "anyOf": [ { "type": "string", "pattern": "^[1-9][0-9]{0,19}$", "description": "Numeric X user ID as a string. Never convert it to a JavaScript number." }, { "type": "null" } ] }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "accountUserId": { "anyOf": [ { "type": "string", "pattern": "^[1-9][0-9]{0,19}$", "description": "Numeric X user ID as a string. Never convert it to a JavaScript number." }, { "type": "null" } ] }, "playId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "sequenceId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "stage": { "type": "string" }, "automationStopped": { "type": "boolean" }, "currentStep": { "type": "integer" }, "nextActionAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "followedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "followedBackAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "messagedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "repliedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "optedOutAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "deliveryGuaranteed": { "const": false } }, "required": [ "id", "xUserId", "username", "accountUserId", "playId", "sequenceId", "stage", "automationStopped", "currentStep", "nextActionAt", "followedAt", "followedBackAt", "messagedAt", "repliedAt", "optedOutAt", "deliveryGuaranteed" ] } }, "required": [ "lead" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/x/leads/{id}/stop": { "post": { "operationId": "stopXLead", "tags": [ "Leads" ], "summary": "Stop this lead's future automation", "description": "Idempotent stop using the existing removal controls. Stops all sequence lanes for this lead, preserving contacted history; uncontacted queued leads become skipped. Available even after X is disabled. Does not recall dispatched actions, permanently suppress the identity, or delete history.", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true }, "lead": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "xUserId": { "anyOf": [ { "type": "string", "pattern": "^[1-9][0-9]{0,19}$", "description": "Numeric X user ID as a string. Never convert it to a JavaScript number." }, { "type": "null" } ] }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "accountUserId": { "anyOf": [ { "type": "string", "pattern": "^[1-9][0-9]{0,19}$", "description": "Numeric X user ID as a string. Never convert it to a JavaScript number." }, { "type": "null" } ] }, "playId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "sequenceId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "stage": { "type": "string" }, "automationStopped": { "type": "boolean" }, "currentStep": { "type": "integer" }, "nextActionAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "followedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "followedBackAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "messagedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "repliedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "optedOutAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "deliveryGuaranteed": { "const": false } }, "required": [ "id", "xUserId", "username", "accountUserId", "playId", "sequenceId", "stage", "automationStopped", "currentStep", "nextActionAt", "followedAt", "followedBackAt", "messagedAt", "repliedAt", "optedOutAt", "deliveryGuaranteed" ] }, { "type": "null" } ] }, "scope": { "const": "lead_automation" }, "permanentSuppression": { "const": false }, "note": { "type": "string" } }, "required": [ "ok", "lead", "scope", "permanentSuppression", "note" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/sequences": { "get": { "operationId": "listSequences", "tags": [ "Sequences" ], "summary": "List existing sequences", "description": "Read tenant-owned sequences, ordered steps and exact lead counts in a compact shape: steps use index and message and there is no executionModel. GET /sequences/{id} returns the full shape (stepIndex, messageTmpl, executionModel); read it before PUT. Create with POST /sequences, replace steps with PUT /sequences/{id}, pause or resume with PATCH /sequences/{id}/status.", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." } ], "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sequences": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "type": "string" }, "revision": { "type": "integer" }, "approvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedRevision": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "executionBlockReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "leadCount": { "type": "integer" }, "channels": { "type": "array", "items": { "type": "string" } }, "steps": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "kind": { "enum": [ "connect", "message", "engage", "email", "x_dm", "x_engage", "instagram_dm" ] }, "delayDays": { "type": "integer" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "actions": { "anyOf": [ { "type": "array", "items": { "type": "object", "additionalProperties": true } }, { "type": "null" } ] }, "variants": { "anyOf": [ { "type": "array", "items": { "type": "object", "additionalProperties": true } }, { "type": "null" } ] }, "tool": { "anyOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ] } }, "required": [ "index", "kind", "delayDays", "subject", "message", "actions", "variants", "tool" ] } } }, "required": [ "id", "name", "status", "revision", "approvedAt", "approvedRevision", "executionBlockReason", "leadCount", "channels", "steps" ], "description": "Compact list item. Steps use index and message; there is no executionModel. Do not build a PUT body from it: read GET /sequences/{id} first." } } }, "required": [ "sequences" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createSequence", "tags": [ "Sequences" ], "summary": "Create a complete sequence", "description": "Save a complete sequence with the same step rules and approval rule as the PumpGTM agent tools. Your request is the approval: with a workspace or partner key the sequence is approved and live when this returns (live: true). Nothing is sent until people are added, and sends follow working hours, account limits and reply freezes. X steps need the X channel and executionModel tracks needs multichannel_tracks (403 feature_disabled). requestId (8-120 characters, first alphanumeric) replays the stored result with replayed: true when reused with the same body; 409 sequence_create_request_conflict when reused with different content; 409 sequence_steps_invalid with detail when step rules are broken.", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{7,119}$", "description": "Optional idempotency key; reuse it only to retry this exact request. Omitted means a fresh request." }, "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "steps": { "type": "array", "items": { "type": "object", "properties": { "stepIndex": { "type": "integer", "minimum": 0, "maximum": 19, "description": "Optional zero-based position; when supplied it must match the array index." }, "kind": { "enum": [ "connect", "message", "engage", "email", "x_dm", "x_engage", "instagram_dm" ] }, "delayDays": { "type": "integer", "minimum": 0, "maximum": 30, "description": "Days after the previous step; the step after connect waits for acceptance." }, "subject": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200, "description": "Email steps only; required on the first email." }, { "type": "null" } ] }, "messageTmpl": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 8000, "description": "Required for email, x_dm and instagram_dm; a LinkedIn message may instead put text on every variant. {{firstName}} {{fullName}} {{company}} {{title}} render on every channel." }, { "type": "null" } ] }, "sendIf": { "anyOf": [ { "enum": [ "followed_back", "not_followed_back" ], "description": "x_dm only: DM only people who followed back after an earlier x_engage follow, or only those who did not." }, { "type": "null" } ] }, "actions": { "type": "array", "items": { "type": "object", "properties": { "type": { "enum": [ "follow", "unfollow", "view_profile", "like_last_post", "endorse_first_skill", "comment_last_post" ] }, "count": { "type": "integer", "minimum": 1, "maximum": 3 }, "reaction": { "enum": [ "like", "celebrate", "support", "love", "insightful", "funny" ] }, "text": { "type": "string", "maxLength": 1250 } }, "required": [ "type" ], "additionalProperties": false }, "maxItems": 10, "description": "Required and non-empty for engage or x_engage; x_engage supports follow and unfollow only." }, "variants": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 5 }, "weight": { "type": "integer", "minimum": 1, "maximum": 10000 }, "messageTmpl": { "type": "string", "maxLength": 2000 } }, "required": [ "key", "weight" ], "additionalProperties": false }, "maxItems": 10 }, { "type": "null" } ] }, "tool": { "anyOf": [ { "type": "object", "additionalProperties": true, "description": "Message steps only. Either { kind: \"customer_input\", tokens: [\"video_url\"] } (1-5 lowercase tokens the customer supplies per person through POST /leads/{id}/input) or a personalised video generated by the connected video tool: { kind: \"sendspark\", params, outputToken?: \"video_url\", timeoutHours?: 1-168, fallback?: \"send_without\" | \"skip_step\" }.", "properties": { "kind": { "enum": [ "customer_input", "sendspark" ] } }, "required": [ "kind" ] }, { "type": "null" } ] } }, "required": [ "kind", "delayDays" ], "additionalProperties": false }, "minItems": 1, "maxItems": 20, "description": "The complete ordered list. With any LinkedIn step, step 0 must be connect." }, "executionModel": { "enum": [ "linear", "tracks" ], "description": "linear (default) runs steps in order; tracks runs LinkedIn, email and X steps as parallel lanes per person and needs the multichannel_tracks feature." }, "xThreadCheck": { "type": "boolean", "description": "Workspace-wide X setting, applies to every sequence: check the conversation before each X DM so nobody the customer already talks to is messaged (5 Energy per DM instead of 0.6). Default off." } }, "required": [ "name", "steps" ], "additionalProperties": false }, "example": { "name": "Founders in fintech", "steps": [ { "kind": "connect", "delayDays": 0 }, { "kind": "message", "delayDays": 1, "messageTmpl": "Hi {{firstName}}, thanks for connecting." } ] } } } }, "responses": { "201": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sequence": { "type": "object", "additionalProperties": true, "description": "Full sequence: { id, name, status, revision, approvedAt, approvedRevision, executionBlockReason, executionModel, leadCount, channels, steps: [{ stepIndex, kind, delayDays, subject, messageTmpl, actions, variants, tool }], updatedAt }. Steps use the same names as the request body (stepIndex, messageTmpl), unlike the compact GET /sequences list (index, message)." }, "reviewUrl": { "type": "string" }, "live": { "type": "boolean" } }, "required": [ "sequence", "reviewUrl", "live" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/sequences/{id}": { "get": { "operationId": "getSequence", "tags": [ "Sequences" ], "summary": "Read one sequence with its revision", "description": "One owned sequence in the full shape (steps use stepIndex and messageTmpl, executionModel included) with its exact revision, needed before PUT. 404 not_found (resource sequence) outside this workspace.", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sequence": { "type": "object", "additionalProperties": true, "description": "Full sequence: { id, name, status, revision, approvedAt, approvedRevision, executionBlockReason, executionModel, leadCount, channels, steps: [{ stepIndex, kind, delayDays, subject, messageTmpl, actions, variants, tool }], updatedAt }. Steps use the same names as the request body (stepIndex, messageTmpl), unlike the compact GET /sequences list (index, message)." } }, "required": [ "sequence" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "replaceSequence", "tags": [ "Sequences" ], "summary": "Replace a sequence's steps as a new revision", "description": "Complete revisioned replacement: read GET /sequences/{id} first and send the full step list (stepIndex, messageTmpl) with the current revision from that response; the compact list shape is not accepted. With a customer credential the new revision is re-approved and the sequence returns to its previous status (active stays active, paused stays paused, a draft goes live). Omitted executionModel keeps the current one and may change only on a draft nobody has been worked through. 409 with nothing changed: sequence_revision_conflict, sequence_edit_request_conflict, sequence_has_progress, archived_sequence_is_read_only, sequence_must_be_draft, sequence_steps_invalid; the body carries update.currentRevision where known.", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{7,119}$", "description": "Optional idempotency key; reuse it only to retry this exact request. Omitted means a fresh request." }, "expectedRevision": { "type": "integer", "minimum": 1, "description": "Current saved revision. Fetch again after a 409; do not silently retry a changed plan." }, "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "steps": { "type": "array", "items": { "type": "object", "properties": { "stepIndex": { "type": "integer", "minimum": 0, "maximum": 19, "description": "Optional zero-based position; when supplied it must match the array index." }, "kind": { "enum": [ "connect", "message", "engage", "email", "x_dm", "x_engage", "instagram_dm" ] }, "delayDays": { "type": "integer", "minimum": 0, "maximum": 30, "description": "Days after the previous step; the step after connect waits for acceptance." }, "subject": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200, "description": "Email steps only; required on the first email." }, { "type": "null" } ] }, "messageTmpl": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 8000, "description": "Required for email, x_dm and instagram_dm; a LinkedIn message may instead put text on every variant. {{firstName}} {{fullName}} {{company}} {{title}} render on every channel." }, { "type": "null" } ] }, "sendIf": { "anyOf": [ { "enum": [ "followed_back", "not_followed_back" ], "description": "x_dm only: DM only people who followed back after an earlier x_engage follow, or only those who did not." }, { "type": "null" } ] }, "actions": { "type": "array", "items": { "type": "object", "properties": { "type": { "enum": [ "follow", "unfollow", "view_profile", "like_last_post", "endorse_first_skill", "comment_last_post" ] }, "count": { "type": "integer", "minimum": 1, "maximum": 3 }, "reaction": { "enum": [ "like", "celebrate", "support", "love", "insightful", "funny" ] }, "text": { "type": "string", "maxLength": 1250 } }, "required": [ "type" ], "additionalProperties": false }, "maxItems": 10, "description": "Required and non-empty for engage or x_engage; x_engage supports follow and unfollow only." }, "variants": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 5 }, "weight": { "type": "integer", "minimum": 1, "maximum": 10000 }, "messageTmpl": { "type": "string", "maxLength": 2000 } }, "required": [ "key", "weight" ], "additionalProperties": false }, "maxItems": 10 }, { "type": "null" } ] }, "tool": { "anyOf": [ { "type": "object", "additionalProperties": true, "description": "Message steps only. Either { kind: \"customer_input\", tokens: [\"video_url\"] } (1-5 lowercase tokens the customer supplies per person through POST /leads/{id}/input) or a personalised video generated by the connected video tool: { kind: \"sendspark\", params, outputToken?: \"video_url\", timeoutHours?: 1-168, fallback?: \"send_without\" | \"skip_step\" }.", "properties": { "kind": { "enum": [ "customer_input", "sendspark" ] } }, "required": [ "kind" ] }, { "type": "null" } ] } }, "required": [ "kind", "delayDays" ], "additionalProperties": false }, "minItems": 1, "maxItems": 20, "description": "The complete ordered list. With any LinkedIn step, step 0 must be connect." }, "executionModel": { "enum": [ "linear", "tracks" ], "description": "linear (default) runs steps in order; tracks runs LinkedIn, email and X steps as parallel lanes per person and needs the multichannel_tracks feature." }, "xThreadCheck": { "type": "boolean", "description": "Workspace-wide X setting, applies to every sequence: check the conversation before each X DM so nobody the customer already talks to is messaged (5 Energy per DM instead of 0.6). Default off." } }, "required": [ "expectedRevision", "steps" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "update": { "type": "object", "additionalProperties": true, "description": "{ ok: true, replayed, sequence, live, change: { previousRevision, revision, currentRevision, previousStatus, nameChanged, stepCountBefore, stepCountAfter, changedStepIndexes, approvalInvalidated } }" }, "reviewUrl": { "type": "string" } }, "required": [ "update", "reviewUrl" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/sequences/{id}/status": { "patch": { "operationId": "setSequenceStatus", "tags": [ "Sequences" ], "summary": "Pause or resume an existing sequence", "description": "Affects every lead in this sequence. active may enable sending, subject to existing approval, billing, budget and provider controls. paused halts future sequence work; already dispatched actions cannot be recalled. Does not edit or approve content. 400 { error: \"status must be one of active, paused, draft\" } for any other value; 404 { error: \"sequence not found\" } outside this workspace; 409 { ok: false, error: sequence_approval_required | archived_sequence_is_read_only } when the change is refused.", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "enum": [ "active", "paused", "draft" ] } }, "required": [ "status" ] }, "example": { "status": "paused" } } } }, "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true }, "sequenceId": { "type": "string", "format": "uuid" }, "previousStatus": { "enum": [ "draft", "active", "paused", "archived" ] }, "status": { "enum": [ "active", "paused", "draft" ] } }, "required": [ "ok", "sequenceId", "previousStatus", "status" ] } } } }, "400": { "description": "{ error: \"status must be one of active, paused, draft\" }", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "{ error: \"sequence not found\" }", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "{ ok: false, error: \"sequence_approval_required\" | \"archived_sequence_is_read_only\" }; nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/sequences/{id}/leads": { "post": { "operationId": "addSequenceLeads", "tags": [ "Leads" ], "summary": "Add people to a sequence", "description": "Queue people into one sequence. Nothing is sent in this call: people enter the paced engine and are contacted later inside working hours and account limits.\n\n**Choose a method**\n\n- `contacts`: 1 to 500 people, each with any mix of `linkedinUrl`, `email` and `xUsername`. Needs a connected LinkedIn account only when LinkedIn people go into a sequence with LinkedIn steps.\n- `manual`: 1 to 500 people with LinkedIn URLs. Always needs a connected LinkedIn account.\n- `csv`: CSV text with a header row, at most 500 rows. Always needs a connected LinkedIn account.\n- `sales_navigator`: a saved Sales Navigator list URL. Imports in the background; poll `GET /leads/imports/{batchId}`. Always needs a connected LinkedIn account.\n\n**How `contacts` routes people**\n\n- Each person is queued only for the channels the sequence has steps for: connect steps are the LinkedIn lane, email steps the email lane, X DM or engage steps the X lane.\n- A person with no identity for any of the sequence's channels is counted in `invalidSkipped` and not added.\n- People already known by LinkedIn profile, email or X handle are counted in `duplicatesSkipped`.\n- X handles are at most 15 characters. An X-only person becomes sendable once their handle has been resolved to an X account, which happens automatically shortly after the add.\n- No paid lookups and no Energy charged.\n\n**Approval and replay**\n\n- Your request is the approval: a draft sequence is approved and started as part of the add. A paused sequence takes the people and stays paused.\n- `requestId` is optional. Reusing it with the same body replays the stored result (`reused: true`); reusing it with a different body is refused.\n- `expectedRevision` is optional on `contacts`. When given it must equal the sequence's current revision.\n\n**Refusals (409, nothing added)**\n\n`idempotency_conflict`, `sequence_not_active`, `sequence_not_ready`, `sequence_revision_conflict`, `linkedin_not_connected` (partners: complete a hosted connect link first) and the `lead_import_csv_*` mapping refusals, which carry `details`.", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "method": { "const": "contacts" }, "requestId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{7,119}$", "description": "Optional idempotency key; reuse it only to retry this exact request. Omitted means a fresh request." }, "expectedRevision": { "type": "integer", "minimum": 1, "description": "Optional. When given it must equal the sequence's current revision (409 sequence_revision_conflict otherwise); omitted means the current revision." }, "leads": { "type": "array", "items": { "type": "object", "properties": { "person": { "type": "string", "minLength": 1, "maxLength": 200 }, "company": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "linkedinUrl": { "anyOf": [ { "type": "string", "maxLength": 500, "description": "Public LinkedIn /in/ profile URL." }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string", "format": "email", "maxLength": 320 }, { "type": "null" } ] }, "xUsername": { "anyOf": [ { "type": "string", "maxLength": 500, "description": "X handle (with or without @) or x.com profile URL." }, { "type": "null" } ] } }, "required": [ "person" ], "additionalProperties": false }, "minItems": 1, "maxItems": 500, "description": "1 to 500 people, each with at least one of linkedinUrl, email or xUsername. A person is queued only for the channels the sequence has steps for; someone with no identity for any of its channels is counted in invalidSkipped." } }, "required": [ "method", "leads" ], "additionalProperties": false }, { "type": "object", "properties": { "method": { "const": "manual" }, "requestId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{7,119}$", "description": "Optional idempotency key; reuse it only to retry this exact request. Omitted means a fresh request." }, "leads": { "type": "array", "items": { "type": "object", "properties": { "linkedinUrl": { "type": "string", "minLength": 1, "maxLength": 500 }, "person": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "company": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "customFields": { "type": "object", "propertyNames": { "pattern": "^[a-z][a-z0-9_]{0,39}$" }, "additionalProperties": { "type": "string", "maxLength": 1000 }, "description": "Per-person values from your own list, keyed by a lowercase token such as personalized_message; written verbatim wherever a message uses {{personalized_message}}." } }, "required": [ "linkedinUrl" ], "additionalProperties": false }, "minItems": 1, "maxItems": 500 } }, "required": [ "method", "leads" ], "additionalProperties": false }, { "type": "object", "properties": { "method": { "const": "csv" }, "requestId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{7,119}$", "description": "Optional idempotency key; reuse it only to retry this exact request. Omitted means a fresh request." }, "csvContent": { "type": "string", "minLength": 1, "maxLength": 200000, "description": "CSV with a header row; at most 500 rows and 100 columns. Person, LinkedIn URL, Company and Title columns are recognised by name." }, "customColumns": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$" }, "description": "Extra CSV header \u2192 lowercase token it fills, for example { \"personalizedMessage\": \"personalized_message\" }." } }, "required": [ "method", "csvContent" ], "additionalProperties": false }, { "type": "object", "properties": { "method": { "const": "sales_navigator" }, "requestId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{7,119}$", "description": "Optional idempotency key; reuse it only to retry this exact request. Omitted means a fresh request." }, "accountId": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Connected LinkedIn account to import with; defaults to the workspace's account." }, "listUrl": { "type": "string", "format": "uri", "maxLength": 500 } }, "required": [ "method", "listUrl" ], "additionalProperties": false } ], "discriminator": { "propertyName": "method" } }, "example": { "method": "contacts", "requestId": "acme-add-2026-10-13-001", "leads": [ { "person": "Jane Doe", "company": "Acme", "title": "Founder", "linkedinUrl": "https://www.linkedin.com/in/example", "email": "jane@acme.com", "xUsername": "janedoe" }, { "person": "Sam Lee", "email": "sam@acme.com" }, { "person": "Ada Ng", "xUsername": "@ada_ng" } ] } } } }, "responses": { "201": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "addResult": { "type": "object", "properties": { "method": { "enum": [ "contacts", "manual", "csv", "sales_navigator" ] }, "batchId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "status": { "type": "string" }, "sequenceId": { "type": "string", "format": "uuid" }, "sequenceStatus": { "enum": [ "active", "paused" ] }, "reused": { "type": "boolean" }, "addedLeadIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "addedLeads": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "person": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "linkedinUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "person", "linkedinUrl" ] }, "description": "manual and csv only." }, "summary": { "type": "object", "properties": { "submittedCount": { "type": "integer", "minimum": 1 }, "addedCount": { "type": "integer", "minimum": 0 }, "duplicatesSkipped": { "type": "integer", "minimum": 0 }, "invalidSkipped": { "type": "integer", "minimum": 0 }, "alreadyInvitedCount": { "type": "integer", "minimum": 0 } }, "required": [ "submittedCount", "addedCount", "duplicatesSkipped", "invalidSkipped", "alreadyInvitedCount" ] }, "contacted": { "const": false }, "energyCharged": { "type": "integer", "minimum": 0, "description": "contacts only; always 0." } }, "required": [ "method", "sequenceId", "sequenceStatus", "reused", "contacted" ], "description": "contacts, manual and csv finish in this call (status \"completed\"). sales_navigator returns the initial import status instead; poll GET /leads/imports/{batchId}." }, "reviewUrl": { "type": "string", "description": "Where the customer reviews or pauses the sequence." } }, "required": [ "addResult", "reviewUrl" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/leads/imports/{batchId}": { "get": { "operationId": "getLeadImport", "tags": [ "Leads" ], "summary": "Read a Sales Navigator import's status", "description": "Status of an import started by POST /sequences/{id}/leads with method sales_navigator. status is processing (still fetching), waiting (fetched; enrollment is waiting on errorCode and retries automatically), finalizing (fetched; valid people are being added), completed (queued in the sequence) or failed (stopped; read errorCode). Poll until completed or failed. Manual and CSV adds finish in their own call and return 404 here (resource import).", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." }, { "name": "batchId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "importStatus": { "type": "object", "additionalProperties": true, "description": "{ method: \"sales_navigator\", batchId, requestId, status: processing | waiting | finalizing | completed | failed, sequence, progress: { fetchState, fetchedCount, providerTotalCount, validCandidateCount, providerLimitReached, nextAttemptAt }, summary: { addedCount, duplicatesSkipped, alreadyInvitedCount }, errorCode, createdAt, updatedAt }", "properties": { "status": { "enum": [ "processing", "waiting", "finalizing", "completed", "failed" ] } } } }, "required": [ "importStatus" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/leads": { "get": { "operationId": "listLeads", "tags": [ "Leads" ], "summary": "List leads across channels", "description": "The same view as the Leads screen: who is engaged, who booked, who went quiet. engaged=1 or sinceDays>0 limits to people with recent activity; booked=1 to booked meetings; q searches person and company. Bounded by limit (max 500).", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." }, { "name": "stage", "in": "query", "schema": { "type": "string" }, "description": "Lead stage, e.g. queued, invited, connected, messaged, replied, meeting_booked." }, { "name": "engaged", "in": "query", "schema": { "enum": [ "1" ] } }, { "name": "sinceDays", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "booked", "in": "query", "schema": { "enum": [ "1" ] } }, { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 200 } } ], "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "returned": { "type": "integer" }, "leads": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "required": [ "count", "returned", "leads" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/leads/{id}": { "get": { "operationId": "getLead", "tags": [ "Leads" ], "summary": "Read one lead", "description": "One lead in the same shape as GET /leads: identity, account, sequence, stage, milestones, reply sentiment and last error. 404 not_found (resource lead) outside this workspace.", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "lead": { "type": "object", "additionalProperties": true } }, "required": [ "lead" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/leads/{id}/input": { "post": { "operationId": "setLeadInput", "tags": [ "Leads" ], "summary": "Supply per-person values for a held message step", "description": "Store the customer's values for a message step declared with tool { kind: \"customer_input\", tokens }, for example a link to a video they recorded. 1-5 entries; keys are the sequence's token names; a *_url key must be an http(s) URL. Nothing is sent in this call: the paced engine sends on its next run. 409 with nothing changed: lead_input_already_replied, lead_input_sequence_finished, lead_input_step_already_sent, lead_input_no_sequence, lead_input_sequence_has_no_input_step, lead_input_unknown_key, lead_input_invalid_value, lead_input_step_uses_generated_asset.", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "values": { "type": "object", "propertyNames": { "pattern": "^[a-z][a-z0-9_]{0,39}$" }, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 2000 }, "minProperties": 1, "maxProperties": 5 } }, "required": [ "values" ], "additionalProperties": false }, "example": { "values": { "video_url": "https://example.com/videos/jane" } } } } }, "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "stored": { "type": "object", "additionalProperties": true, "description": "{ leadId, person, company, linkedinUrl, sequenceId, sequenceName, stepIndex, storedKeys, complete, stillMissing, willSendOn, stillWaitingInSequence }" } }, "required": [ "stored" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/leads/remove": { "post": { "operationId": "removeLeads", "tags": [ "Leads" ], "summary": "Remove leads, cancel an import or block companies", "description": "The bounded undo. Uncontacted leads leave the queue; contacted leads keep their stage and milestones and get no further automated steps. Sent invitations and messages are never reversed. target companies also puts those employers on the do-not-contact list. 404 not_found (resource import) when batchId is not one of this workspace's imports.", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "target": { "const": "leads" }, "leadIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 500 } }, "required": [ "target", "leadIds" ], "additionalProperties": false }, { "type": "object", "properties": { "target": { "const": "import" }, "batchId": { "type": "string", "format": "uuid" } }, "required": [ "target", "batchId" ], "additionalProperties": false }, { "type": "object", "properties": { "target": { "const": "companies" }, "companies": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 240 }, "minItems": 1, "maxItems": 100, "description": "Employers to put on the workspace do-not-contact list; everyone queued there is stopped and Plays stop finding people there." } }, "required": [ "target", "companies" ], "additionalProperties": false } ], "discriminator": { "propertyName": "target" } }, "example": { "target": "leads", "leadIds": [ "00000000-0000-4000-8000-000000000003" ] } } } }, "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "removal": { "type": "object", "additionalProperties": true, "description": "{ ok: true, selectedCount, removedBeforeContact, automationStoppedAfterContact, alreadyStopped, notFoundCount, importCancelled, excludedCompanies?, historyPreserved: true, sentActionsReversed: false, summary }" } }, "required": [ "removal" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/people/searches": { "post": { "operationId": "createPeopleSearch", "tags": [ "People search" ], "summary": "Create or revise a people-search Play and optionally run it", "description": "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.", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "targeting": { "type": "object", "properties": { "schemaVersion": { "const": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "A short customer-facing name for this search." }, "candidateCount": { "type": "integer", "minimum": 10, "maximum": 100, "description": "The exact number of candidates to return." }, "hardFilters": { "type": "object", "properties": { "currentTitleIncludesAny": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 }, "minItems": 1, "maxItems": 40, "description": "Alternative literal phrases; a person's current title must contain at least one." }, "currentFunctionsAny": { "type": "array", "items": { "type": "string", "enum": [ "Engineering", "Sales", "Consulting", "Marketing", "Operations", "Finance", "Research", "Customer Success and Support", "Arts and Design", "Human Resources", "Legal", "Product Management" ] }, "maxItems": 40, "description": "Alternative current job functions. Use only when non-negotiable. One of the listed values only." }, "currentSenioritiesAny": { "type": "array", "items": { "type": "string", "enum": [ "Owner / Partner", "CXO", "Vice President", "Director", "Experienced Manager", "Entry Level Manager", "Strategic", "Senior", "Entry Level", "In Training" ] }, "maxItems": 40, "description": "Alternative current seniority levels. Use only when non-negotiable. One of the listed values only; put finer wording such as Head of or SVP in semanticQuery." }, "personCountriesAny": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 240 }, "maxItems": 40, "description": "Alternative countries where the person must be located." }, "currentCompanyNamesAny": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 240 }, "maxItems": 40, "description": "Alternative exact current-employer names, only for a named account list." }, "currentCompanyDomainsAny": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 240 }, "maxItems": 40, "description": "Alternative exact current-employer website domains; a domain pins one company exactly." }, "currentCompanyLinkedInUrlsAny": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 240 }, "maxItems": 40, "description": "Alternative current-employer LinkedIn company URLs." }, "currentCompanyIndustriesAny": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 240 }, "maxItems": 40, "description": "Alternative canonical company industries." }, "currentCompanyTypesAny": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 240 }, "maxItems": 40, "description": "Alternative canonical company ownership types." }, "currentCompanyHeadcount": { "type": "object", "properties": { "minimum": { "type": "integer", "minimum": 1, "maximum": 10000000 }, "maximum": { "type": "integer", "minimum": 1, "maximum": 10000000 } }, "required": [], "additionalProperties": false }, "currentCompanyInvestorsAny": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 240 }, "maxItems": 40, "description": "Alternative canonical investors or accelerators backing the current company (Y Combinator, not YC)." }, "currentCompanyHiringRolesAny": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 240 }, "maxItems": 40, "description": "Alternative role phrases the current company must have an open job posting for right now." }, "currentCompanyHiringPostedWithinDays": { "type": "integer", "minimum": 1, "maximum": 365, "description": "Defaults to 30 when hiring roles are given." }, "excludedCurrentFunctionsAny": { "type": "array", "items": { "type": "string", "enum": [ "Engineering", "Sales", "Consulting", "Marketing", "Operations", "Finance", "Research", "Customer Success and Support", "Arts and Design", "Human Resources", "Legal", "Product Management" ] }, "maxItems": 40, "description": "Current job functions that must be excluded. One of the listed values only." }, "excludedCurrentSenioritiesAny": { "type": "array", "items": { "type": "string", "enum": [ "Owner / Partner", "CXO", "Vice President", "Director", "Experienced Manager", "Entry Level Manager", "Strategic", "Senior", "Entry Level", "In Training" ] }, "maxItems": 40, "description": "Current seniority levels that must be excluded. One of the listed values only; put finer wording such as Head of or SVP in semanticQuery." }, "excludedCurrentCompanyNamesAny": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 240 }, "maxItems": 40, "description": "Exact current-employer names that must be excluded." }, "excludedCurrentCompanyTypesAny": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 240 }, "maxItems": 40, "description": "Company ownership types that must be excluded." } }, "required": [ "currentTitleIncludesAny" ], "additionalProperties": false }, "semanticQuery": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Plain-language description of product, workload, responsibility and business-model fit. Descriptive requirements go here, not in hard filters." }, "defaultSequenceId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] } }, "required": [ "name", "candidateCount", "hardFilters" ], "additionalProperties": false }, "playId": { "type": "string", "format": "uuid" }, "expectedRevision": { "type": "integer", "minimum": 1, "description": "Current saved revision. Fetch again after a 409; do not silently retry a changed plan." }, "sequenceId": { "type": "string", "format": "uuid" }, "run": { "type": "boolean", "default": false }, "requestId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{7,119}$", "description": "Optional idempotency key; reuse it only to retry this exact request. Omitted means a fresh request." } }, "required": [], "additionalProperties": false, "anyOf": [ { "required": [ "targeting" ] }, { "required": [ "playId" ] } ], "if": { "properties": { "run": { "const": true } }, "required": [ "run" ] }, "then": { "required": [ "requestId" ] } }, "example": { "run": true, "requestId": "people-search-2026-10-06-001", "targeting": { "name": "Heads of sales at mid-market SaaS", "candidateCount": 20, "hardFilters": { "currentTitleIncludesAny": [ "Head of Sales", "VP Sales" ] }, "semanticQuery": "B2B SaaS selling to mid-market" } } } } }, "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "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 }." } } } }, "201": { "description": "Search ran: review batch and candidates returned; nobody was contacted.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "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 }." } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "energy_exhausted: this metered workspace has no Energy left for the action; nothing changed. Follow topUpUrl.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/people/searches/{playId}/run": { "post": { "operationId": "runPeopleSearch", "tags": [ "People search" ], "summary": "Run an existing people-search Play", "description": "Runs a saved people-search Play as is; same metering and result as createPeopleSearch with run: true. requestId is required: a run is billed, so a retry must carry the same requestId to replay the stored result instead of searching and charging again. 404 not_found (resource play) when the Play does not exist or is not a people-search Play.", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." }, { "name": "playId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{7,119}$", "description": "Optional idempotency key; reuse it only to retry this exact request. Omitted means a fresh request." }, "sequenceId": { "type": "string", "format": "uuid" } }, "required": [ "requestId" ], "additionalProperties": false }, "example": { "requestId": "people-search-rerun-2026-10-06-001" } } } }, "responses": { "201": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "energy_exhausted: this metered workspace has no Energy left for the action; nothing changed. Follow topUpUrl.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/people/reviews/{batchId}": { "get": { "operationId": "getPeopleReview", "tags": [ "People search" ], "summary": "Read a review batch and its candidates", "description": "One review batch: batch counts, the targeting summary and each candidate with its current decision (undecided, approved or rejected). batch.status is draft (being prepared), sample_ready (ready to review), approved, imported (finished; good fits queued) or rejected. 404 not_found (resource review).", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." }, { "name": "batchId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "{ batch: { id, status: draft | sample_ready | approved | imported | rejected, planId, planRevision, proposedCount, approvedCount, importedCount, ... }, target, candidates: [{ id, person, title, company, linkedinUrl, location, matchReason, evidence, linkedinVerified, recentActivityAt, decision: undecided | approved | rejected, sequenceId }] }" } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/people/reviews/{batchId}/decisions": { "post": { "operationId": "decidePeopleReview", "tags": [ "People search" ], "summary": "Record good-fit decisions and enroll", "description": "Record the customer's good-fit decisions on a review batch. 1-100 decisions per call; good_fit approves, not_a_fit rejects. Partial decisions persist. finish: true requires every candidate decided and queues the good fits into their sequence (the call's sequenceId, a per-decision override, or the Play's default); summary, addedLeadIds, addedLeads and sequences are present only on that finishing call, and reviewUrl is then present. Nothing is sent in this call. 409 all_candidates_require_a_decision when finishing with undecided people.", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." }, { "name": "batchId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decisions": { "type": "array", "items": { "type": "object", "properties": { "candidateId": { "type": "string", "format": "uuid" }, "decision": { "enum": [ "good_fit", "not_a_fit" ] }, "sequenceId": { "type": "string", "format": "uuid", "description": "Optional per-person override of the sequence this good fit goes into." }, "feedbackReason": { "type": "string", "minLength": 1, "maxLength": 120 }, "feedbackNote": { "type": "string", "maxLength": 1000 } }, "required": [ "candidateId", "decision" ], "additionalProperties": false }, "minItems": 1, "maxItems": 100 }, "sequenceId": { "type": "string", "format": "uuid", "description": "Applies to every good fit in this call." }, "finish": { "type": "boolean", "default": false }, "requestId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{7,119}$", "description": "Optional idempotency key; reuse it only to retry this exact request. Omitted means a fresh request." } }, "required": [ "decisions" ], "additionalProperties": false }, "example": { "sequenceId": "00000000-0000-4000-8000-000000000001", "finish": true, "decisions": [ { "candidateId": "00000000-0000-4000-8000-000000000004", "decision": "good_fit" }, { "candidateId": "00000000-0000-4000-8000-000000000005", "decision": "not_a_fit", "feedbackReason": "wrong seniority" } ] } } } }, "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "{ batch, candidates: [{ ..., decision: undecided | approved | rejected }], reviewUrl?, contacted: false } plus, only when finish is true: summary: { approvedCount, rejectedCount, addedCount, duplicatesSkipped, alreadyInvitedCount }, addedLeadIds, addedLeads, sequences" } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/progress": { "get": { "operationId": "getProgress", "tags": [ "Results" ], "summary": "Read LinkedIn pace and outcomes", "description": "Current LinkedIn sending pace and outcome counts over the last sinceDays days (default 7): invites, acceptances, messages, replies and meetings per account. Saved observations, not a live provider probe.", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." }, { "name": "sinceDays", "in": "query", "schema": { "type": "number", "minimum": 0, "default": 7 } } ], "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/reports/funnel": { "get": { "operationId": "getFunnelReport", "tags": [ "Results" ], "summary": "Read the lead funnel by sequence or account", "description": "Funnel outcomes grouped by sequence (default) or by connected account, plus split-test arms, so a backend can report or decide without scraping a screen. excludedWarmupAccounts is a compatibility field and is always empty.", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." }, { "name": "group_by", "in": "query", "schema": { "enum": [ "sequence", "account" ], "default": "sequence" } } ], "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "groupBy": { "type": "string" }, "excludedWarmupAccounts": { "type": "array", "items": { "type": "string" } }, "total": { "type": "object", "additionalProperties": true }, "groups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "funnel": { "type": "object", "additionalProperties": true } }, "required": [ "id", "name", "funnel" ] } }, "experimentArms": { "type": [ "array", "object" ] } }, "required": [ "groupBy", "excludedWarmupAccounts", "total", "groups", "experimentArms" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/replies": { "get": { "operationId": "listReplies", "tags": [ "Replies" ], "summary": "Read pending replies", "description": "Includes X and LinkedIn replies. X rows have channel x, no draft and no allowedDecisions; answer in X. Encrypted text can be unavailable. This is a bounded pending queue, not a complete conversation archive.", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "replies": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "required": [ "replies" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/replies/{id}/decide": { "post": { "operationId": "decideReply", "tags": [ "Replies" ], "summary": "Decide a pending reply", "description": "Runs exactly the same code as the inbox buttons. send posts the draft (text overrides it); invite, booking_link and start_sequence act on the thread; snooze waits days; meeting_booked, dismiss and opt_out close it. by is recorded for the audit trail. 404 when the reply is not pending in this workspace; 409 with the result when the decision could not be applied.", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "enum": [ "send", "invite", "booking_link", "snooze", "start_sequence", "meeting_booked", "dismiss", "opt_out" ] }, "text": { "type": "string", "description": "send only: replaces the generated draft." }, "days": { "type": "integer", "minimum": 1, "description": "snooze only." }, "by": { "type": "string", "description": "Who decided; defaults to api." } }, "required": [ "decision" ] }, "example": { "decision": "snooze", "days": 14, "by": "crm-bot" } } } }, "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "additionalProperties": true } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/activity": { "get": { "operationId": "listActivity", "tags": [ "Results" ], "summary": "Read the activity ledger", "description": "Use action=x_dm and outcome=ok to inspect confirmed X sends. Other actions may be skipped/failed. Bounded recent ledger; polling supplements best-effort webhook delivery.", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." }, { "name": "action", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated action names, e.g. x_dm,x_follow" }, { "name": "outcome", "in": "query", "schema": { "enum": [ "ok", "failed", "skipped" ] } }, { "name": "sinceDays", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 200 } } ], "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks": { "get": { "operationId": "listWebhooks", "tags": [ "Webhooks" ], "summary": "List enabled subscriptions", "description": "Lists workspace webhook URLs and events; never returns signing secrets.", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." } ], "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhooks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string" } }, "required": [ "id", "url", "events", "createdAt" ] } }, "events": { "type": "array", "items": { "type": "string" } } }, "required": [ "webhooks", "events" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createWebhook", "tags": [ "Webhooks" ], "summary": "Subscribe to signed events", "description": "Maximum 10 enabled hooks. Save the returned secret securely; it is shown only at creation. HTTPS port 443 and publicly resolving IPv4 DNS required. Private/mixed IPs, URL credentials, fragments and redirects are rejected. Registration is not idempotent: list before retrying after a timeout; 409 webhook_limit_reached at the maximum. Delivery is best-effort: up to three attempts, retried on network errors, 5xx and 429; not a durable replay queue. Verify signatures on the exact raw body (X-PumpGTM-Signature, t=,v1=; reject t older than 5 minutes) and deduplicate event IDs. x.followed means an inbound follow of your connected account. lead.messaged includes successful x_dm with channel x; reply.received can include unreadable encrypted content. linkedin.connected fires on the partner workspace when an end user completes a hosted connect link; register it with the partner key. linkedin.disconnected fires when a connected LinkedIn identity stops being usable (source: provider, dashboard or api), on the owning workspace and, for a partner end user, on the partner workspace. linkedin.limited fires once when LinkedIn declines an account's connection requests and invites are held (data.account{id,displayName}, reason invite_limit, heldSince, retryAt = earliest automatic retry, attempt 1..3; a failed retry fires it again with the next attempt); linkedin.resumed fires when a retry goes through (data.account, resumedAt, warmupRestarted true: the account re-enters the six-day warm-up ramp). Messages and other steps keep running during a hold; nothing to do on your side.", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2000 }, "events": { "type": "array", "items": { "enum": [ "reply.received", "lead.invited", "lead.accepted", "lead.messaged", "lead.emailed", "lead.meeting_booked", "x.followed", "linkedin.connected", "linkedin.disconnected", "linkedin.limited", "linkedin.resumed", "linkedin.watched_post", "x.competitor_follower", "x.intent_detected", "ping" ] }, "minItems": 1, "maxItems": 15 } }, "required": [ "url", "events" ] }, "example": { "url": "https://hooks.example.com/pump", "events": [ "reply.received", "lead.messaged", "x.followed" ] } } } }, "responses": { "201": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "secret": { "type": "string" } }, "required": [ "id", "url", "events", "secret" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks/{id}/test": { "post": { "operationId": "testWebhook", "tags": [ "Webhooks" ], "summary": "Schedule a signed ping", "description": "202 means the ping was scheduled, not that the receiver accepted it. Verify the event at your receiver.", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" }, "event": { "const": "ping" } }, "required": [ "ok", "id", "event" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks/{id}": { "delete": { "operationId": "deleteWebhook", "tags": [ "Webhooks" ], "summary": "Disable a subscription", "description": "Only an enabled hook belonging to the selected workspace can be disabled. A subsequent delete returns 404. Already queued delivery may still complete.", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" } }, "required": [ "ok", "id" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/signup": { "post": { "operationId": "partnerSignup", "tags": [ "Partner" ], "summary": "Create a partner account", "description": "Self-serve partner account for agent platforms and agencies; no browser step. The response carries the partner API key once (it is also the partner's MCP key). The email owns the account and can sign in later with a login link. acceptedPolicies must equal the current policy version. 409 email_in_use when the email already has an account: sign in and copy the key from the install page instead.", "parameters": [], "servers": [ { "url": "https://app.pumpgtm.com/api/partner/v1", "description": "Partner API (partner workspace key)" } ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 254 }, "company": { "type": "string", "minLength": 1, "maxLength": 200 }, "website": { "type": "string", "format": "uri", "maxLength": 2000 }, "acceptedPolicies": { "const": "2026-09-18", "description": "The current legal policy version, confirming acceptance of /terms and /privacy." } }, "required": [ "email", "company", "acceptedPolicies" ] }, "example": { "email": "ops@agency.example", "company": "Example Agency", "website": "https://agency.example", "acceptedPolicies": "2026-09-18" } } } }, "responses": { "201": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "apiKey": { "type": "string" }, "mcpUrlTemplate": { "type": "string" }, "freeLeads": { "type": "integer" }, "accountUrl": { "type": "string" }, "usersUrl": { "type": "string" }, "docsUrl": { "type": "string" } }, "required": [ "apiKey", "mcpUrlTemplate", "freeLeads", "accountUrl", "usersUrl", "docsUrl" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/account": { "get": { "operationId": "getPartnerAccount", "tags": [ "Partner" ], "summary": "Read the partner account, capabilities and usage", "description": "Partner id and name; enterprise capabilities enabled by PumpGTM (outreach, linkedinConnect); hosted connect-link settings; the REST policy for this key (rest.requireUserHeader); the MCP URL template; active user count; this period's leads, free allowance and billing state.", "parameters": [], "servers": [ { "url": "https://app.pumpgtm.com/api/partner/v1", "description": "Partner API (partner workspace key)" } ], "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "partner": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "enterprise": { "type": "object", "properties": { "outreach": { "type": "boolean" }, "linkedinConnect": { "type": "boolean" } }, "required": [ "outreach", "linkedinConnect" ] }, "linkedinConnect": { "type": "object", "properties": { "successRedirectUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failureRedirectUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "brandName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "successRedirectUrl", "failureRedirectUrl", "brandName" ] }, "rest": { "type": "object", "properties": { "requireUserHeader": { "type": "boolean", "description": "When true, every /api/v1 request made with this partner key must carry X-PumpGTM-User; without it the request is 400 user_header_required instead of acting on the partner workspace. Default false." } }, "required": [ "requireUserHeader" ] }, "mcpUrlTemplate": { "type": "string" }, "users": { "type": "integer" }, "accounts": { "type": "object", "properties": { "connected": { "type": "integer" }, "included": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "remaining": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [ "connected", "included", "remaining" ] }, "periodStart": { "type": "string" }, "leadsThisPeriod": { "type": "integer" }, "freeLeads": { "type": "integer" }, "freeLeadsRemaining": { "type": "integer" }, "billing": { "type": "object", "properties": { "status": { "enum": [ "metered", "billing_required", "free" ] }, "checkoutUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "status", "checkoutUrl" ] } }, "required": [ "partner", "enterprise", "linkedinConnect", "rest", "mcpUrlTemplate", "users", "accounts", "periodStart", "leadsThisPeriod", "freeLeads", "freeLeadsRemaining", "billing" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "updatePartnerAccount", "tags": [ "Partner" ], "summary": "Set brand name, connect-link return URLs and the REST policy", "description": "Two groups, each behind its own capability (GET /account enterprise). Connect settings (enterprise.linkedinConnect): where end users land after a hosted LinkedIn connect link resolves, and the white-label name shown on that page (1-60 characters; null uses your workspace name). An absent field is kept, null or \"\" clears it. The end user id and link id are appended to the redirect as externalUserId and connectLinkId; only expired or revoked links use the failure URL. REST policy (enterprise.outreach): requireUserHeader true makes every /api/v1 request with this key that lacks X-PumpGTM-User fail with 400 user_header_required, so a missing header can never act on your own workspace; /api/partner/v1 and the per-user MCP URL are unaffected. Nothing is written when any group is refused. 400 { error, field } on a bad value (invalid_url, https_required, host_not_allowed, url_too_long, invalid_brand_name, invalid_require_user_header); 400 nothing_to_update or invalid_body with field null; 403 enterprise_required when the needed capability is off.", "parameters": [], "servers": [ { "url": "https://app.pumpgtm.com/api/partner/v1", "description": "Partner API (partner workspace key)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "successRedirectUrl": { "anyOf": [ { "type": "string", "format": "uri", "maxLength": 2000, "description": "Absolute https URL to a public host, no credentials or fragment. null or \"\" clears it; an absent field is left as it is." }, { "type": "null" } ] }, "failureRedirectUrl": { "anyOf": [ { "type": "string", "format": "uri", "maxLength": 2000, "description": "Absolute https URL to a public host, no credentials or fragment. null or \"\" clears it; an absent field is left as it is." }, { "type": "null" } ] }, "brandName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 60 }, { "type": "null" } ] }, "requireUserHeader": { "type": "boolean" } }, "required": [], "minProperties": 1 }, "example": { "brandName": "Your Agency", "successRedirectUrl": "https://your-app.example/linkedin/done", "failureRedirectUrl": "https://your-app.example/linkedin/failed", "requireUserHeader": true } } } }, "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "linkedinConnect": { "type": "object", "properties": { "successRedirectUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failureRedirectUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "brandName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "successRedirectUrl", "failureRedirectUrl", "brandName" ] }, "rest": { "type": "object", "properties": { "requireUserHeader": { "type": "boolean", "description": "When true, every /api/v1 request made with this partner key must carry X-PumpGTM-User; without it the request is 400 user_header_required instead of acting on the partner workspace. Default false." } }, "required": [ "requireUserHeader" ] } }, "required": [ "linkedinConnect", "rest" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/users": { "get": { "operationId": "listPartnerUsers", "tags": [ "Partner" ], "summary": "List end users with this period's usage", "description": "One row per end user with the same fields as GET /users/{externalUserId} (name, status, lead cap, mcpUrl, rest, outreach) plus people found and tool calls since periodStart, and last use.", "parameters": [], "servers": [ { "url": "https://app.pumpgtm.com/api/partner/v1", "description": "Partner API (partner workspace key)" } ], "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "periodStart": { "type": "string" }, "users": { "type": "array", "items": { "type": "object", "properties": { "externalUserId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$", "description": "Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "status": { "enum": [ "active", "disabled" ] }, "monthlyLeadCap": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "People search cap for this user per period; null means no cap." }, { "type": "null" } ] }, "mcpUrl": { "type": "string", "description": "https://mcp.pumpgtm.com/mcp/u/{externalUserId}" }, "rest": { "anyOf": [ { "type": "object", "properties": { "header": { "const": "X-PumpGTM-User" }, "value": { "type": "string" } }, "required": [ "header", "value" ], "description": "The header to add to /api/v1 requests to act for this user. null until outreach is enabled on the partner account." }, { "type": "null" } ] }, "outreach": { "enum": [ "enabled", "disabled" ], "description": "disabled until PumpGTM enables outreach on the partner account." }, "leadsFound": { "type": "integer" }, "toolCalls": { "type": "integer" }, "lastUsedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "externalUserId", "name", "createdAt", "status", "monthlyLeadCap", "mcpUrl", "rest", "outreach", "leadsFound", "toolCalls", "lastUsedAt" ] } } }, "required": [ "periodStart", "users" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createPartnerUser", "tags": [ "Partner" ], "summary": "Create an end user's workspace", "description": "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.", "parameters": [], "servers": [ { "url": "https://app.pumpgtm.com/api/partner/v1", "description": "Partner API (partner workspace key)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "externalUserId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$", "description": "Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters." }, "name": { "type": "string", "maxLength": 200 }, "monthlyLeadCap": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "People search cap for this user per period; null means no cap." }, { "type": "null" } ] } }, "required": [ "externalUserId" ] }, "example": { "externalUserId": "acme", "name": "Acme Robotics" } } } }, "responses": { "200": { "description": "The user already existed; returned unchanged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "externalUserId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$", "description": "Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "status": { "enum": [ "active", "disabled" ] }, "monthlyLeadCap": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "People search cap for this user per period; null means no cap." }, { "type": "null" } ] }, "mcpUrl": { "type": "string", "description": "https://mcp.pumpgtm.com/mcp/u/{externalUserId}" }, "rest": { "anyOf": [ { "type": "object", "properties": { "header": { "const": "X-PumpGTM-User" }, "value": { "type": "string" } }, "required": [ "header", "value" ], "description": "The header to add to /api/v1 requests to act for this user. null until outreach is enabled on the partner account." }, { "type": "null" } ] }, "outreach": { "enum": [ "enabled", "disabled" ], "description": "disabled until PumpGTM enables outreach on the partner account." } }, "required": [ "externalUserId", "name", "createdAt", "status", "monthlyLeadCap", "mcpUrl", "rest", "outreach" ] } } } }, "201": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "externalUserId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$", "description": "Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "status": { "enum": [ "active", "disabled" ] }, "monthlyLeadCap": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "People search cap for this user per period; null means no cap." }, { "type": "null" } ] }, "mcpUrl": { "type": "string", "description": "https://mcp.pumpgtm.com/mcp/u/{externalUserId}" }, "rest": { "anyOf": [ { "type": "object", "properties": { "header": { "const": "X-PumpGTM-User" }, "value": { "type": "string" } }, "required": [ "header", "value" ], "description": "The header to add to /api/v1 requests to act for this user. null until outreach is enabled on the partner account." }, { "type": "null" } ] }, "outreach": { "enum": [ "enabled", "disabled" ], "description": "disabled until PumpGTM enables outreach on the partner account." } }, "required": [ "externalUserId", "name", "createdAt", "status", "monthlyLeadCap", "mcpUrl", "rest", "outreach" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/users/{externalUserId}": { "get": { "operationId": "getPartnerUser", "tags": [ "Partner" ], "summary": "Read one end user", "description": "The user's status, lead cap, MCP URL and REST header. 404 user_not_found.", "parameters": [ { "name": "externalUserId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$", "description": "Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters." } } ], "servers": [ { "url": "https://app.pumpgtm.com/api/partner/v1", "description": "Partner API (partner workspace key)" } ], "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "externalUserId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$", "description": "Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "status": { "enum": [ "active", "disabled" ] }, "monthlyLeadCap": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "People search cap for this user per period; null means no cap." }, { "type": "null" } ] }, "mcpUrl": { "type": "string", "description": "https://mcp.pumpgtm.com/mcp/u/{externalUserId}" }, "rest": { "anyOf": [ { "type": "object", "properties": { "header": { "const": "X-PumpGTM-User" }, "value": { "type": "string" } }, "required": [ "header", "value" ], "description": "The header to add to /api/v1 requests to act for this user. null until outreach is enabled on the partner account." }, { "type": "null" } ] }, "outreach": { "enum": [ "enabled", "disabled" ], "description": "disabled until PumpGTM enables outreach on the partner account." } }, "required": [ "externalUserId", "name", "createdAt", "status", "monthlyLeadCap", "mcpUrl", "rest", "outreach" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "updatePartnerUser", "tags": [ "Partner" ], "summary": "Change a lead cap, disable or reactivate", "description": "monthlyLeadCap sets or clears (null) the user's people-search cap (400 invalid_monthly_lead_cap); status disabled is the same as DELETE (sequences paused, 403 user_disabled on MCP and REST, nothing more billed) and status active reactivates. At least one field is required (400 nothing_to_update; a non-object body is 400 invalid_body; both carry field null).", "parameters": [ { "name": "externalUserId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$", "description": "Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters." } } ], "servers": [ { "url": "https://app.pumpgtm.com/api/partner/v1", "description": "Partner API (partner workspace key)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "monthlyLeadCap": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "People search cap for this user per period; null means no cap." }, { "type": "null" } ] }, "status": { "enum": [ "active", "disabled" ] } }, "required": [], "minProperties": 1 }, "example": { "monthlyLeadCap": 250 } } } }, "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "externalUserId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$", "description": "Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters." }, "status": { "enum": [ "active", "disabled" ] }, "monthlyLeadCap": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "People search cap for this user per period; null means no cap." }, { "type": "null" } ] } }, "required": [ "externalUserId", "status", "monthlyLeadCap" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "disablePartnerUser", "tags": [ "Partner" ], "summary": "Disable an end user", "description": "The user's workspace loses the partner's entitlement and Energy, its active sequences are paused, and its MCP URL and X-PumpGTM-User requests answer 403 user_disabled. Data is kept and nothing more is billed for them. PATCH { status: \"disabled\" } is equivalent; reactivate with PATCH { status: \"active\" }.", "parameters": [ { "name": "externalUserId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$", "description": "Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters." } } ], "servers": [ { "url": "https://app.pumpgtm.com/api/partner/v1", "description": "Partner API (partner workspace key)" } ], "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "externalUserId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$", "description": "Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters." }, "status": { "enum": [ "active", "disabled" ] }, "monthlyLeadCap": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "People search cap for this user per period; null means no cap." }, { "type": "null" } ] } }, "required": [ "externalUserId", "status", "monthlyLeadCap" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/users/{externalUserId}/linkedin/accounts": { "get": { "operationId": "listPartnerLinkedInAccounts", "tags": [ "Partner" ], "summary": "List an end user's connected LinkedIn accounts", "description": "Enterprise. The user's LinkedIn identities with status (connected or disconnected) and display name. A saved connection does not prove live provider health. 404 user_not_found for a user that has not been created.", "parameters": [ { "name": "externalUserId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$", "description": "Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters." } } ], "servers": [ { "url": "https://app.pumpgtm.com/api/partner/v1", "description": "Partner API (partner workspace key)" } ], "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "externalUserId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$", "description": "Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters." }, "status": { "enum": [ "connected", "disconnected", "pending", "failed" ], "description": "connected or disconnected in steady state; treat anything but connected as not usable for sending." }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pictureUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "connectedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "externalUserId", "status", "displayName", "pictureUrl", "connectedAt", "timezone" ] } } }, "required": [ "accounts" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/users/{externalUserId}/linkedin/accounts/{accountId}": { "delete": { "operationId": "disconnectPartnerLinkedInAccount", "tags": [ "Partner" ], "summary": "Disconnect one LinkedIn account", "description": "Enterprise. Sequences stop sending from this identity; its history is kept. Idempotent: an already disconnected account also returns 200. 404 user_not_found for a user that has not been created; 404 account_not_found; 503 disconnect_failed (retry in a minute).", "parameters": [ { "name": "externalUserId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$", "description": "Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters." } }, { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "servers": [ { "url": "https://app.pumpgtm.com/api/partner/v1", "description": "Partner API (partner workspace key)" } ], "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "externalUserId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$", "description": "Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters." }, "status": { "const": "disconnected" } }, "required": [ "id", "externalUserId", "status" ] } }, "required": [ "account" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/linkedin/accounts/{accountId}/sending-limits": { "get": { "operationId": "getLinkedInSendingLimits", "tags": [ "Account" ], "summary": "Read a LinkedIn account's daily invite cap and warm-up state", "description": "accountId is the LinkedIn account id (partners: from GET /api/partner/v1/users/{id}/linkedin/accounts). Returns the configured daily cap (1 to 30), the mode, warm-up progress, and the numbers the engine uses today: effective cap, invites already sent in the account's local day, and what remains. A week is bounded by 7 \u00d7 the daily cap; there is no separate weekly setting. 404 account_not_found outside this workspace.", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." }, { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid" }, "dailyInviteCap": { "type": "integer", "minimum": 1, "maximum": 30, "description": "Configured full-pace cap: connection requests per account-local day once warm-up is over." }, "mode": { "enum": [ "warmup", "outreach" ] }, "warmup": { "type": "object", "properties": { "startedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isWarming": { "type": "boolean" }, "daysRemaining": { "type": "integer" }, "ramp": { "type": "array", "items": { "type": "integer" } } }, "required": [ "startedAt", "isWarming", "daysRemaining", "ramp" ] }, "effectiveDailyCapToday": { "type": "integer", "description": "What the engine will allow today: the warm-up ramp value or the configured cap, whichever is lower." }, "invitesSentToday": { "type": "integer" }, "remainingToday": { "type": "integer" }, "workspaceDailyInviteCapTotal": { "anyOf": [ { "type": "integer", "description": "Workspace-wide ceiling across all connected accounts, when one is set." }, { "type": "null" } ] }, "limits": { "type": "object", "properties": { "minDailyInviteCap": { "type": "integer" }, "maxDailyInviteCap": { "type": "integer" } }, "required": [ "minDailyInviteCap", "maxDailyInviteCap" ] } }, "required": [ "accountId", "dailyInviteCap", "mode", "warmup", "effectiveDailyCapToday", "invitesSentToday", "remainingToday", "workspaceDailyInviteCapTotal", "limits" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "setLinkedInSendingLimits", "tags": [ "Account" ], "summary": "Set a LinkedIn account's daily invite cap or warm-up mode", "description": "dailyInviteCap 1 to 30 (the same range as the dashboard). mode warmup restarts the 6-day ramp (5, 7, 10, 15, 16, 20 a day) and is always allowed; mode outreach graduates the account to its configured cap. Graduating while the ramp is still running is refused with 409 warmup_in_progress, because LinkedIn restricts fresh accounts that burst; send acknowledgeEarlyGraduation: true to do it anyway. Returns the same shape as GET after the change. 400 nothing_to_update with an empty body.", "parameters": [ { "name": "X-PumpGTM-Client", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional authorized Team workspace ID from GET /workspaces. Omit to use the key's home workspace." }, { "name": "X-PumpGTM-User", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$" }, "description": "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." }, { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "dailyInviteCap": { "type": "integer", "minimum": 1, "maximum": 30 }, "mode": { "enum": [ "warmup", "outreach" ] }, "acknowledgeEarlyGraduation": { "type": "boolean", "default": false } }, "required": [], "additionalProperties": false }, "example": { "dailyInviteCap": 20 } } } }, "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid" }, "dailyInviteCap": { "type": "integer", "minimum": 1, "maximum": 30, "description": "Configured full-pace cap: connection requests per account-local day once warm-up is over." }, "mode": { "enum": [ "warmup", "outreach" ] }, "warmup": { "type": "object", "properties": { "startedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isWarming": { "type": "boolean" }, "daysRemaining": { "type": "integer" }, "ramp": { "type": "array", "items": { "type": "integer" } } }, "required": [ "startedAt", "isWarming", "daysRemaining", "ramp" ] }, "effectiveDailyCapToday": { "type": "integer", "description": "What the engine will allow today: the warm-up ramp value or the configured cap, whichever is lower." }, "invitesSentToday": { "type": "integer" }, "remainingToday": { "type": "integer" }, "workspaceDailyInviteCapTotal": { "anyOf": [ { "type": "integer", "description": "Workspace-wide ceiling across all connected accounts, when one is set." }, { "type": "null" } ] }, "limits": { "type": "object", "properties": { "minDailyInviteCap": { "type": "integer" }, "maxDailyInviteCap": { "type": "integer" } }, "required": [ "minDailyInviteCap", "maxDailyInviteCap" ] } }, "required": [ "accountId", "dailyInviteCap", "mode", "warmup", "effectiveDailyCapToday", "invitesSentToday", "remainingToday", "workspaceDailyInviteCapTotal", "limits" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "{ error: \"warmup_in_progress\", message }: the ramp has not finished and acknowledgeEarlyGraduation was not true; nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/users/{externalUserId}/linkedin/connect-links": { "post": { "operationId": "createPartnerConnectLink", "tags": [ "Partner" ], "summary": "Mint a hosted LinkedIn connect link", "description": "409 account_limit_reached when every LinkedIn account included in your plan is already connected (see accounts on GET /account). Enterprise. Returns a PumpGTM-hosted url (shown once, never stored in clear) where this end user signs in to LinkedIn themselves; open it in a popup, never an iframe. Links are single use and expire after 7 days by default (expiresInMinutes 10 to 43200). Completion is announced through your linkedin.connected webhook and the redirect URLs from PATCH /account; GET the link to poll. Webhook, redirect and poll have no ordering guarantee: treat all three as idempotent on connectLink.id. This route creates the user's workspace if it does not exist yet. A user may hold at most 10 open links (409 connect_link_limit_reached). 400 invalid_expires_in_minutes with field. A 409 saying the link cannot be minted because of a problem with your partner account creates nothing; contact PumpGTM rather than retrying.", "parameters": [ { "name": "externalUserId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$", "description": "Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters." } } ], "servers": [ { "url": "https://app.pumpgtm.com/api/partner/v1", "description": "Partner API (partner workspace key)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expiresInMinutes": { "anyOf": [ { "type": "integer", "minimum": 10, "maximum": 43200 }, { "type": "null" } ] } }, "required": [], "additionalProperties": false }, "example": { "expiresInMinutes": 10080 } } } }, "responses": { "201": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "connectLink": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "externalUserId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$", "description": "Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters." }, "status": { "enum": [ "pending", "connected", "expired", "revoked" ], "description": "expired and revoked are final; mint a new link." }, "expiresAt": { "type": "string" }, "connectedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" } }, "required": [ "id", "externalUserId", "status", "expiresAt", "connectedAt", "revokedAt", "createdAt" ] }, "url": { "type": "string" } }, "required": [ "connectLink", "url" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "listPartnerConnectLinks", "tags": [ "Partner" ], "summary": "List an end user's connect links", "description": "Enterprise. Newest first, at most 25. The hosted url is never returned again. 404 user_not_found for a user that has not been created.", "parameters": [ { "name": "externalUserId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$", "description": "Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters." } } ], "servers": [ { "url": "https://app.pumpgtm.com/api/partner/v1", "description": "Partner API (partner workspace key)" } ], "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "connectLinks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "externalUserId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$", "description": "Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters." }, "status": { "enum": [ "pending", "connected", "expired", "revoked" ], "description": "expired and revoked are final; mint a new link." }, "expiresAt": { "type": "string" }, "connectedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" } }, "required": [ "id", "externalUserId", "status", "expiresAt", "connectedAt", "revokedAt", "createdAt" ] } } }, "required": [ "connectLinks" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/users/{externalUserId}/linkedin/connect-links/{linkId}": { "get": { "operationId": "getPartnerConnectLink", "tags": [ "Partner" ], "summary": "Poll one connect link", "description": "Enterprise. status is pending, connected, expired or revoked (expired and revoked are final). Polling rule: every 3 seconds, stop when status is not pending, give up after 15 minutes; this GET is not rate limited. 404 connect_link_not_found; 404 user_not_found for a user that has not been created.", "parameters": [ { "name": "externalUserId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$", "description": "Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters." } }, { "name": "linkId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "servers": [ { "url": "https://app.pumpgtm.com/api/partner/v1", "description": "Partner API (partner workspace key)" } ], "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "connectLink": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "externalUserId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$", "description": "Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters." }, "status": { "enum": [ "pending", "connected", "expired", "revoked" ], "description": "expired and revoked are final; mint a new link." }, "expiresAt": { "type": "string" }, "connectedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" } }, "required": [ "id", "externalUserId", "status", "expiresAt", "connectedAt", "revokedAt", "createdAt" ] } }, "required": [ "connectLink" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "revokePartnerConnectLink", "tags": [ "Partner" ], "summary": "Revoke an open connect link", "description": "Enterprise. Only a pending link can be revoked; already connected, expired or revoked links return 409 connect_link_not_pending with the current link. 404 connect_link_not_found; 404 user_not_found for a user that has not been created.", "parameters": [ { "name": "externalUserId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$", "description": "Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters." } }, { "name": "linkId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "servers": [ { "url": "https://app.pumpgtm.com/api/partner/v1", "description": "Partner API (partner workspace key)" } ], "responses": { "200": { "description": "Successful response. Read outcome fields; success does not imply delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "boolean" }, "connectLink": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "externalUserId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$", "description": "Your own id for the end user: letters, digits and _ . : @ -, up to 120 characters." }, "status": { "enum": [ "pending", "connected", "expired", "revoked" ], "description": "expired and revoked are final; mint a new link." }, "expiresAt": { "type": "string" }, "connectedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" } }, "required": [ "id", "externalUserId", "status", "expiresAt", "connectedAt", "revokedAt", "createdAt" ] }, { "type": "null" } ] } }, "required": [ "revoked", "connectLink" ] } } } }, "400": { "description": "Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Revision, identity or state conflict: { error, message } and nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After when provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error: an unexpected failure on our side; retry, then contact PumpGTM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable; identity may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "string" }, "reason": { "type": "string" } }, "additionalProperties": true, "required": [ "error" ], "description": "Every error response. error is a stable machine-readable code (for example invalid_request, sequence_not_active, energy_exhausted); message is plain language for a person." } }, "securitySchemes": { "WorkspaceKey": { "type": "http", "scheme": "bearer", "bearerFormat": "Workspace MCP key", "description": "Keep the key in a server-side secret. Do not send Pump keys to X or data vendors. For partners this is the partner workspace key from signup (shown and rotated on /api-keys): it authenticates /api/partner/v1 and, with X-PumpGTM-User, acts on an end user's workspace under /api/v1. Only a workspace key or a Team owner key can act for end users; a personal key issued through an OAuth sign-in gets 403 partner_key_required." } } } }