pipedrive-api

Golang Pipedrive client

A Go client for the Pipedrive API using the Pipedrive API v2 for all resources that support it, with explicit v1 fallbacks for endpoints that have no v2 equivalent.

Requires Go version 1.17 or greater.

API version routing

Pipedrive has deprecated a large set of v1 endpoints (changelog). This library routes every method explicitly:

• v2 (https://api.pipedrive.com/api/v2): Activities, Deals, Persons, Organizations, Products, Pipelines, Stages CRUD and search, item search (/itemSearch), followers and deal products deletion.
• v1 (https://api.pipedrive.com/v1): everything without a v2 equivalent. Each such method is documented in code with "This endpoint has no v2 equivalent and remains on the v1 API". This includes merge/duplicate/flow/statistics operations, person pictures, deal participants, product attached deals, and all ancillary services (fields, notes, files, filters, goals, users, webhooks, currencies, recents, user settings/connections, activity types and authorizations).

Breaking changes from the v1-only versions

• Authentication is sent via headers: x-api-token for API tokens, Authorization: Bearer for OAuth access tokens. The api_token query parameter is no longer used.
• Updates use PATCH (v2 semantics) instead of PUT for migrated resources.
• Pagination is cursor based for v2 list endpoints: pass Cursor/Limit via the embedded CursorListOptions and read AdditionalData.NextCursor from the response. An empty cursor means the last page.
• Models are v2-native: related entities are plain integer IDs (OwnerID, PersonID, OrgID), booleans replace numeric flags (IsDeleted, Busy, IsLinkable), person contacts are Emails/Phones collections, organization addresses and activity locations are nested Address objects, labels are LabelIDs and custom fields live in the CustomFields map keyed by the field API key.
• Search uses the v2 endpoints: Deals.Search, Persons.Search, Organizations.Search, Products.Search (the legacy Find methods are gone) and SearchResults.Search/SearchField wrap /itemSearch and /itemSearch/field.
• Bulk deletes (DeleteMultiple) are performed as individual v2 deletes because v2 does not expose reliable bulk delete endpoints.
• Sub-resource lists are served by filtered v2 list calls, e.g. Persons.ListDeals requests /api/v2/deals?person_id={id}.

Supported resources

• Activities (v2)
• ActivityFields (v1)
• ActivityTypes (v1)
• Authorizations (v1)
• Currencies (v1)
• Deals (v2, some v1 fallbacks)
• DealFields (v1)
• Files (v1)
• Filters (v1)
• Goals (v1)
• Notes (v1)
• NoteFields (v1)
• Organizations (v2, merge on v1)
• OrganizationFields (v1)
• Persons (v2, merge/picture on v1)
• PersonFields (v1)
• Pipelines (v2, statistics on v1)
• Products (v2, attached deals on v1)
• ProductFields (v1)
• Recents (v1)
• Item search (v2)
• Stages (v2)
• Users (v1)
• User connections (v1)
• User settings (v1)
• Webhooks (v1)

Installation

go get -v github.com/dinistavares/pipedrive-api/pipedrive

Usage

import "github.com/dinistavares/pipedrive-api/pipedrive"

Construct a new Pipedrive client, then use the various services on the client to access different parts of the API. For example:

    const apiKey = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

    client := pipedrive.NewClient(&pipedrive.Config{
        APIKey: apiKey,
    })

    // List deals, one cursor page at a time.
    deals, _, err := client.Deals.List(context.Background(), &pipedrive.DealsListOptions{
        CursorListOptions: pipedrive.CursorListOptions{Limit: 100},
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, deal := range deals.Data {
        fmt.Println(deal.Title, deal.OwnerID)
    }

    // Fetch the next page.
    if cursor := deals.AdditionalData.NextCursor; cursor != "" {
        deals, _, err = client.Deals.List(context.Background(), &pipedrive.DealsListOptions{
            CursorListOptions: pipedrive.CursorListOptions{Cursor: cursor, Limit: 100},
        })
    }

OAuth access tokens are supported through Config.AccessToken and are sent as a Bearer authorization header.

Tests

All tests live in the integration suite. Contract tests run without credentials:

go test -tags=integration ./test/integration

Set a token to include tests that exercise the live API:

PIPEDRIVE_API_TOKEN=XXXXXX go test -v -tags=integration ./test/integration

Contributions & Issues

Contributions are welcome. Please clearly explain the purpose of the PR and follow the current style.

Issues can be resolved quickest if they are descriptive and include both a reduced test case and a set of steps to reproduce.

License

This library is distributed under the MIT license found in the LICENSE file.