Pipedrive ExecModule

Overview

PipedriveModule connects ValkyrAI workflows to the tenant-scoped Pipedrive API v2 for deals, persons, organizations, activities, and pipelines. It exposes 18 bounded operations through the native map I/O ExecModule ABI and keeps the user-scoped API token in a READY IntegrationAccount.

The module constructs only https://<company>.pipedrive.com/api/v2 production URLs, sends the token in x-api-token, validates record IDs and tenant names, caps JSON requests at 256 KiB and responses at 5 MiB, returns one provider page per execution, retries transient failures only for safe GET operations, and never automatically retries create or update requests.

The official n8n Pipedrive node informed the resource and operation selection: activity, deal, organization, and person workflows are the high-value core. ValkyrAI adds tenant-host validation, the IntegrationAccount security boundary, bounded payloads, response identity checks, explicit retry safety, and normalized outputs.

Usage

1. Create a dedicated Pipedrive user with only the CRM visibility needed by the workflow.
2. Copy that user’s API token into the encrypted apiKey field of a ValkyrAI IntegrationAccount; set the account to READY.
3. Bind the account through ExecModuleConfig.authConfig.integrationAccount.
4. Set companySubdomain to only the company portion of the Pipedrive host, such as acme for acme.pipedrive.com.
5. Choose one operation and provide its conditional fields.
6. For a list, pass nextCursor unchanged into a later execution when hasMore is true.

Inputs

Name	Type	Required	Description	Constraints
operation	string	Yes	Operation listed below.	Exact allowlist of 18 values.
companySubdomain	string	Yes	Company-only Pipedrive subdomain.	Lowercase letters, digits, and internal hyphens; 1–63 characters; not a URL.
recordId	integer	Conditional	Provider ID for get_* and update_*.	Positive integer.
record	object	Conditional	Fields for create_* and update_*.	Non-empty, at most 100 top-level fields and 256 KiB serialized; credential-like field names rejected.
query	object	No	Resource-specific list filters.	At most 20 allowlisted scalar fields; values at most 2,048 characters.
cursor	string	No	Opaque API v2 continuation.	1–2,048 bounded cursor characters; passed unchanged.
limit	integer	No	Provider page size.	1–500; default 100.

Create requirements:

• create_deal: non-empty record.title.
• create_person: non-empty record.name.
• create_organization: non-empty record.name.
• create_activity: non-empty record.subject and record.type.

List-query fields are resource-specific. Common fields include filter_id, owner_id, updated_since, updated_until, sort_by, and sort_direction. Deals additionally support person, organization, pipeline, stage, and status filters. Activities support deal, lead, person, organization, completion, and type filters. Unsupported fields fail before transport.

Outputs

Name	Type	When present	Description
status	string	Always	success or error.
operation	string	Always	Normalized operation.
resource	string	After validation	deals, persons, organizations, activities, or pipelines.
data	object	Single-record success	Verified provider record.
id	integer	Single-record success	Positive provider identity.
items	array	List success	One bounded API page.
count	integer	List success	Items returned in this page.
hasMore	boolean	List success	Whether a continuation was supplied.
nextCursor	string	When another page exists	Opaque continuation for the next execution.
attempts	integer	Provider call or error	HTTP attempts consumed.
error	object	Failure	Redacted code, message, and retryable fields.

CRM responses are classified restricted. Tokens, provider bodies, and record values are never copied into progress logs.

IntegrationAccount Requirements

Setting	Requirement
Provider	Pipedrive REST API v2
Authentication	User API token in the x-api-token request header
Status	Exactly READY
accountName	Human-readable tenant/user identity
apiKey	Encrypted API token, 20–2,048 non-whitespace characters
Relationship	ExecModuleConfig.authConfig.integrationAccount

Pipedrive API tokens inherit the associated user’s company access; they do not have fine-grained OAuth scopes. Use a dedicated least-privilege user, minimize its visible pipelines and records, rotate the token deliberately, and never place it in record, query, URLs, examples, logs, or WorkflowState. Marketplace OAuth and token refresh are outside this version’s contract.

Configuration

Illustrative persisted configuration:

{
  "version": "1.0.0",
  "authConfig": {
    "authStrategy": 1,
    "integrationAccount": "integration-account:pipedrive-sales-automation"
  },
  "payloadConfig": {
    "parameters": "{\"companySubdomain\":\"acme\",\"operation\":\"list_deals\",\"limit\":100,\"query\":{\"status\":\"open\",\"pipeline_id\":3}}"
  }
}

The relationship is symbolic. The generated IntegrationAccount record owns the encrypted token.

Operations

Resource	Create	Get	List	Update
Deals	create_deal	get_deal	list_deals	update_deal
Persons	create_person	get_person	list_persons	update_person
Organizations	create_organization	get_organization	list_organizations	update_organization
Activities	create_activity	get_activity	list_activities	update_activity
Pipelines	—	get_pipeline	list_pipelines	—

Create uses POST /api/v2/{resource}, get uses GET /api/v2/{resource}/{id}, list uses GET /api/v2/{resource}, and update uses PATCH /api/v2/{resource}/{id}. API v1 fallback, lead/file/product/note operations, custom-field schema administration, followers, webhooks, merge, deletion, and OAuth lifecycle management are deferred.

Errors and Failure Modes

Failure	Cause	Retry guidance
VALIDATION_ERROR	Missing field, invalid ID/subdomain/cursor/time, unsupported query, unsafe record key, or local size/page limit.	Correct the request; no provider call was sent.
INTEGRATION_ACCOUNT_REQUIRED	No bound secure account.	Bind the intended account.
INTEGRATION_ACCOUNT_NOT_READY	Account status is not READY.	Repair or reauthorize the account.
PIPEDRIVE_HTTP_400/404	Provider validation or missing record.	Correct IDs, field shapes, pipeline/stage, or filters.
PIPEDRIVE_HTTP_401/403	Invalid token, account limitation, or insufficient user visibility.	Rotate the token or correct the Pipedrive user’s access.
PIPEDRIVE_HTTP_429	Token or account rate limit.	Reads use bounded retry; after exhaustion honor provider limits. Writes remain single-attempt.
PIPEDRIVE_HTTP_5xx / NETWORK_ERROR	Provider or transport failure.	Reads retry up to three total attempts. Reconcile create/update state before manually retrying.
RESPONSE_TOO_LARGE	Provider response exceeded 5 MiB.	Narrow filters or page size.
Invalid success envelope	success was not true, data shape was wrong, ID was missing, or requested/returned IDs differed.	Treat as failure and verify provider compatibility.

Errors are bounded to 500 characters and pass through credential redaction. A failed write may have reached Pipedrive; the module therefore refuses automatic replay.

Example

Create a deal in an existing pipeline and stage:

{
  "companySubdomain": "acme",
  "operation": "create_deal",
  "record": {
    "title": "Enterprise renewal",
    "pipeline_id": 3,
    "stage_id": 8,
    "person_id": 71,
    "value": 25000,
    "currency": "USD",
    "expected_close_date": "2026-09-30"
  }
}

Expected normalized result:

{
  "status": "success",
  "operation": "create_deal",
  "resource": "deals",
  "id": 123,
  "data": {
    "id": 123,
    "title": "Enterprise renewal",
    "status": "open"
  },
  "httpStatus": 201,
  "attempts": 1
}

Notes

• Pagination: one execution returns one page. Reuse nextCursor verbatim; no silent all-pages loop occurs.
• Rate limits: Pipedrive applies token budgets and burst limits. The module respects HTTP 429, honors bounded numeric Retry-After, and caps retries to three safe-read attempts.
• API limits: page size is capped at Pipedrive’s 500-record v2 limit; request JSON is 256 KiB and response JSON is 5 MiB maximum.
• Idempotency: GET calls are retry-safe. Creates can duplicate records and updates can have ambiguous completion after a timeout, so writes are single-attempt.
• Destructive behavior: deletion is intentionally not exposed. Creates and updates can still trigger Pipedrive automations and must be governed as outbound changes.
• Custom fields: Pipedrive custom fields are accepted inside the documented API v2 record shape, including custom_fields; credential-like top-level keys are rejected.
• External verification: deterministic tests cover validation, routing, JSON construction, authentication headers, pagination, retries, write non-retry, redaction, identity checks, and annotation discovery. Live provider execution is deferred until a separately authorized Pipedrive account is supplied.

See the official Pipedrive authentication guide, API v2 request guide, deals reference, and the official n8n Pipedrive node for the upstream functional reference.