Configuration
Find your token under your account name → Company settings → Personal
preferences → API. The token reads whatever that user can see in Pipedrive.
If the API tab is missing, an admin must
enable API access.
Pipedrive recommends
https://<company>.pipedrive.com as the host, where
<company> is the subdomain you sign in with. The default host works for every
account. Connection testing makes one request to the users endpoint.
Resources
Selected by default: users, deals, persons, organizations, activities, leads,
notes, pipelines, stages, the deal, person, and organization field definitions,
activity types, and lead labels. The rest are optional. No resource depends on
another.
Each row is one Pipedrive record. Numeric IDs are
int64 columns, lead and
lead label IDs are UUID strings, optional fields are nullable, and the raw
column keeps fields without their own column.
Custom fields use 40-character keys. The v2 endpoints return them in a
custom_fields JSON column keyed by that key. Map a key to its label with the
field_code and field_name columns of the matching field-definition resource.
Leads come from the v1 API, so their custom field keys stay in raw. See
Pipedrive’s custom field guide.
deals and leads exclude deleted and archived records, matching Pipedrive’s
default listings. The _archived resources read archived records with the same
columns. activities includes attendees. notes keeps the HTML body in
content. files rows are metadata and a download URL, not file contents.
Pipedrive marks the tasks endpoint as beta.
Not included: mail, the recents feed, per-record flow and changelog histories,
search, deal products and installments, organization relationships, call logs,
goals, roles, permission sets, and webhook configuration, which exposes HTTP
auth credentials.
Modes
Deals, archived deals, persons, organizations, activities, products, and leads support incremental reads onupdate_time. Each run sends the saved timestamp
as updated_since, which Pipedrive applies inclusively, with a one-minute
lookback by default. Checkpoint keys are <resource>_update_time and use the
time comparator. A returned record without an update_time fails the run
rather than being skipped.
Incremental reads cannot detect deletions. Use full replace to remove rows
that Pipedrive no longer returns, or full upsert to refresh rows in place.
Notes are read in full. The v1 notes endpoint accepts updated_since, but its
update_time values use Pipedrive’s older YYYY-MM-DD HH:MM:SS format, which
the incremental engine cannot compare. Every other resource is read in full.
Behavior
- Auth: every request sends the token in the
x-api-tokenheader. An empty list can mean the token’s user cannot see those records. - Pagination: v2 endpoints follow
additional_data.next_cursor, 500 records per page. Leads, notes, and files use v1 offset pagination, 100 per page, and stop after a short page. The other v1 endpoints return everything at once. Empty v1 lists can return"data": null, which Filament reads as no rows. - Recovery: interrupted top-level reads resume from a saved page cursor or offset. If that request fails, the read restarts from the beginning.
- Rate limiting: five requests per second, shared across resources in this connection. Pipedrive’s burst limit is per token and depends on the plan, from 20 requests per 2 seconds on Lite to 120 on Ultimate. Pipedrive also charges a daily token budget per company, 10 tokens per v2 list page and 20 per v1 list page. Filament retries throttled requests but does not track the daily budget. See Pipedrive’s rate limiting guide.
- Timestamps: v2 endpoints return RFC 3339. v1 endpoints return
YYYY-MM-DD HH:MM:SSin UTC, which Filament reads as UTC. - API versions: deals, persons, organizations, activities, products, pipelines, stages, and field definitions use v2 endpoints. Pipedrive stopped supporting their v1 versions on August 1, 2026. Leads, notes, users, and the remaining reference tables have no v2 equivalent and use their supported v1 endpoints.