Connect Pipedrive

What you will configure

1. Pipedrive company
2. Dedicated user
3. Personal API token
4. Encrypted Agent Secret
5. pipedrive-work profile

Pipedrive company
        │
        ▼
Dedicated Pipedrive user
        │
        ├── Permission set
        ├── Data visibility
        └── Personal API token
                  │
                  ▼
       Encrypted Agent Secret
                  │
                  ▼
        Built-in Pipedrive Skill
                  │
                  ▼
         pipedrive-work profile
                  │
                  ▼
          aai-cli pipedrive

At the end of this guide, the Agent will have:

• An encrypted pipedrive credential
• The built-in Pipedrive Skill
• A generated pipedrive-work profile
• Access to CRM data visible to the token-owning Pipedrive user
• Read and write commands for supported Pipedrive resources

Supported operations

The current Pipedrive Skill exposes these operations.

The Skill does not expose every endpoint in the Pipedrive API. It provides the command surface documented above, and the token may allow more Pipedrive API operations than the Skill exposes.

Before you begin

For production use, create a dedicated Pipedrive integration user where your plan and account structure allow it.

Official references:

• Find a Pipedrive API token
• Pipedrive API authentication
• Enable API access for company users
• Find the company domain
• Pipedrive API reference
• Pipedrive API rate limits

Understand the access boundary

A personal API token is tied to:

One Pipedrive user
        +
One Pipedrive company

A user has a different token for each company they belong to. The effective Agent boundary is the combination of these layers:

1. Pipedrive user permissions Permission set, item visibility, and company membership
2. Personal API token Inherits the user’s permissions; it has no scopes of its own
3. Agent Barn Agent access Who may operate or configure the Agent
4. Pipedrive Skill Which Pipedrive commands are documented to the Agent
5. Agent instructions When the Agent should use read or write commands

Use the supported command groups

aai-cli pipedrive leads
aai-cli pipedrive persons
aai-cli pipedrive organizations
aai-cli pipedrive deals
aai-cli pipedrive labels
aai-cli pipedrive activities
aai-cli pipedrive notes
aai-cli pipedrive mailbox
aai-cli pipedrive request

Leads support list, search, get, create, update, delete, and conversion. Persons, Organizations, and Deals support list, search, record views, related records, and mutations; deals also expose stage flow. Labels, activities, notes, mailbox data, and uncommon supported endpoints are available through their matching resource groups.

aai-cli pipedrive leads list --limit 20 --profile pipedrive-work
aai-cli pipedrive persons search --term "Ada Lovelace" --limit 10 --profile pipedrive-work
aai-cli pipedrive persons view 123 --limit 20 --profile pipedrive-work
aai-cli pipedrive organizations search --term "Acme" --limit 10 --profile pipedrive-work
aai-cli pipedrive deals view 456 --include-mail --limit 20 --profile pipedrive-work
aai-cli pipedrive deals flow 456 --limit 50 --profile pipedrive-work
aai-cli pipedrive activities list --deal-id 456 --limit 20 --profile pipedrive-work
aai-cli pipedrive notes list --deal-id 456 --limit 20 --profile pipedrive-work
aai-cli pipedrive mailbox threads list --folder inbox --limit 20 --profile pipedrive-work
aai-cli pipedrive request get /api/v2/pipelines --profile pipedrive-work

Prefer composed views and explicit stage history

Use deals view, persons view, or organizations view when the Agent needs the primary record together with related activities and notes. Add --include-mail when synchronized mail is applicable; mail_messages appears only when mail inclusion is requested and available.

For deal stage-transition history, use aai-cli pipedrive deals flow <deal-id> --profile pipedrive-work. Stage changes are dealChange entries whose field_key is stage_id; a deal’s current stage_id is not its complete stage history.

Interpret response and error shapes

Successful output is JSON on stdout and includes an Agent Barn CLI _aai metadata block. Its pagination object can include continuation, has_more, instruction, next_command, returned_count, and status.

"_aai": {
  "pagination": {
    "continuation": "…",
    "has_more": false,
    "instruction": "…",
    "next_command": "…",
    "returned_count": 20,
    "status": "complete"
  }
}

• Single-record and mutation commands typically preserve { success: true, data: {} }.
• List commands typically return { success: true, data: [], additional_data: {} }; older endpoints can use offset pagination and newer v2 endpoints cursors.
• Search results use data.items[].item and data.items[].result_score.
• View commands use a composed record, activities, notes, and optional mail_messages shape.

Errors are structured JSON on stderr and exit non-zero. Use safe fields such as code, message, operation, service, status, and provider details to distinguish invalid_input, config_error, auth_error, not_found, rate_limited, provider_api_error, and internal_error. Never copy a token or full secret configuration into logs.

Access synced email history

Mailbox commands require Pipedrive email synchronization or Smart BCC data. The token-owning user must have permission to view the relevant messages.

Supported commands include:

aai-cli pipedrive mailbox threads list \
  --folder inbox \
  --limit 10 \
  --profile pipedrive-work

aai-cli pipedrive mailbox threads get THREAD_ID \
  --profile pipedrive-work

aai-cli pipedrive mailbox threads messages THREAD_ID \
  --profile pipedrive-work

aai-cli pipedrive mailbox messages get MESSAGE_ID \
  --include-body \
  --profile pipedrive-work

Associated email history can also be added to combined views:

aai-cli pipedrive deals view DEAL_ID \
  --include-mail \
  --limit 10 \
  --profile pipedrive-work

The current Skill does not send email or modify mailbox threads.

Runtime behavior

When the Agent starts, Agent Barn:

1. Decrypts the Pipedrive credential.
2. Stores the token in the encrypted aai-cli secret store.
3. Generates the pipedrive-work profile.
4. Mounts the Pipedrive Skill.
5. Adds Pipedrive to the Agent’s configured integration context.

[profiles.pipedrive-work]
auth_type = "pipedrive_personal_token"
api_token_secret = "pipedrive.api_token"

[profiles.pipedrive-work]
auth_type = "pipedrive_personal_token"
base_url = "https://acme.pipedrive.com"
api_token_secret = "pipedrive.api_token"

The token itself is not written into the profile. The profile references pipedrive.api_token.

The complete runtime path is:

Encrypted Pipedrive token
           │
           ▼
      Agent start
           │
           ├── Encrypted aai-cli secret
           ├── pipedrive-work profile
           └── Pipedrive Skill
                       │
                       ▼
              aai-cli pipedrive
                       │
                       ▼
                 Pipedrive API

Credential changes take effect after the Agent restarts.

Rotate or remove the credential

Rotate the personal API token

Pipedrive allows one active personal API token per user and company. Before rotation:

1. Inventory every integration using the current token.
2. Schedule a short migration window.
3. Open the user’s Personal preferences → API page.
4. Generate a new token.
5. Immediately replace the token in Agent Barn.
6. Restart affected Agents.
7. Validate the credential.
8. Run a read-only CRM command.
9. Update any other authorized integrations that shared the old token.

Generating the new token invalidates the old one.

Remove the credential

Before removal:

1. Remove or replace any assigned Skill that requires Pipedrive.
2. Stop the Agent, or use the website’s restart-aware apply flow.
3. Open Keys & integrations.
4. Mark the Pipedrive credential for removal.
5. Apply the change.
6. Restart and verify the Agent.

Agent Barn blocks removal while an assigned Skill still requires the pipedrive provider.

API reference

Add or replace a manual credential

The Agent must be stopped when using the raw update endpoint.

PATCH /api/v1/organizations/{organization_id}/agents/{agent_id}
Content-Type: application/json

Using the global endpoint:

{
  "secrets": [
    {
      "provider": "pipedrive",
      "content": {
        "apiToken": "REDACTED",
        "domain": ""
      }
    }
  ]
}

Using a company-specific endpoint:

{
  "secrets": [
    {
      "provider": "pipedrive",
      "content": {
        "apiToken": "REDACTED",
        "domain": "acme"
      }
    }
  ]
}

Validate the credential

POST /api/v1/organizations/{organization_id}/agents/{agent_id}/integrations/pipedrive/validate

{
  "validation_status": "valid",
  "validation_identity": "agent@example.com",
  "validation_error": null,
  "missing_scopes": []
}

Remove the credential

{
  "removed_secret_providers": [
    "pipedrive"
  ]
}

Credential operations require access to the Agent and the relevant update and secret-management permissions, including agent.secret.manage.

Rate limits

Pipedrive uses token-based API budgets and burst limits. Important characteristics include:

• API calls consume different numbers of budget tokens
• List and search operations can cost more than single-record reads
• The daily budget is shared at the Pipedrive company level
• Burst limits apply per API token
• A depleted budget can produce HTTP 429
• Continued high-volume traffic after rate-limit responses can result in temporary blocking

Reduce avoidable usage by:

• Using narrow list limits
• Applying server-side filters
• Avoiding repeated full-record scans
• Caching stable identifiers in an approved workflow
• Stopping retries after a rate-limit error
• Spacing scheduled Agent jobs
• Monitoring the company’s API Usage Dashboard

Troubleshooting

Manage users → Permission sets

Security practices

• Use a dedicated Pipedrive integration user where possible
• Restrict that user’s permission set
• Restrict record visibility
• Do not treat Agent instructions as the only write boundary
• Require confirmation for consequential CRM writes
• Prohibit deletion unless explicitly needed
• Test write workflows in a sandbox
• Use separate credentials for separate companies or authorization boundaries
• Prefer Shared Credentials when administrators should own rotation
• Do not reuse the token across unrelated integrations
• Keep the token out of source control, logs, screenshots, and conversations
• Validate after every credential change
• Run a real read operation after validation
• Monitor API usage and rate-limit errors
• Review Agent activity and logs for unexpected CRM mutations

Next steps

• Connect Zoho
• Review Agent health and logs
• Manage Skill Versions
• Configure an Agent