SOURCE_ID: import_from_pipedrive NAME: Import Pipedrive Records CATEGORY: CRM Pull Pipedrive persons, organizations, or deals into Floqer — either as a one-time import or as an ongoing source that re-pulls on a schedule. Imported records become available to your Floqer workflows for enrichment, scoring, outreach, and the like. INDEX: 1. Endpoints 2. Pull mode (one-time vs ongoing) 3. Body shape (preview + create) 4. Field catalogue 5. Filter shape 6. Dynamic options 7. How to configure end-to-end 8. Key notes 9. Where it fits 10. When to use ================================================================================ 1. ENDPOINTS ================================================================================ Source identifier (used in every endpoint path): `import_from_pipedrive`. POST /api/v1/sources/import_from_pipedrive/preview Scope: sources:read Returns a sample page of records that WOULD be imported for the given body, without creating anything. Use this to validate object type / properties / filters before committing. POST /api/v1/sources/import_from_pipedrive Scope: sources:write Creates the source, imports matching records immediately (when `pull_existing`), and — for an active source — keeps re-importing on a schedule. Returns `source_instance_id` (the new source's UUID). POST /api/v1/sources/import_from_pipedrive/options/ Scope: sources:read Resolves dynamic option values for a field. For Pipedrive the one `field_name` that matters is `properties` (see §6). GET /api/v1/sources//data Scope: sources:read Paginated rows imported into the created source. `` is the UUID returned by Create. Query: `page_no` (default 1), `page_size` (default 20, max 200). Source-agnostic; see concepts.txt §10. POST /api/v1/sources//sync Scope: sources:write Connects the created source to a workflow and (by default) backfills it with the source's current rows. `` here is the UUID returned by Create. Body: { workflow_id, field_mapping, push_existing?, run? } — `field_mapping` keys are `input.` references on the target workflow, values are the source fields to pull. This step is source-agnostic; see concepts.txt §10 for the full shape. PATCH /api/v1/sources//status Scope: sources:write Pause or resume an active source by UUID. Body: {"status": "active" | "paused"}. Source-agnostic. Every endpoint for this source first verifies the API-key user has an active Pipedrive connection. Missing connection → 424. ================================================================================ 2. PULL MODE (ONE-TIME VS ONGOING) ================================================================================ `pull_mode` is required on the create endpoint (not on preview). Values: "static" One-time import. The source imports matching records once (when `pull_existing`) and stops — no recurring schedule. "active" Ongoing source. Imports matching records initially (when `pull_existing`) AND re-imports on the cadence in `schedule` (a cron string), continuing until `expiration_date`. `schedule` is required when `pull_mode: active`. Otherwise it's ignored. ================================================================================ 3. BODY SHAPE (PREVIEW + CREATE) ================================================================================ Field names are snake_case. Unknown top-level keys are rejected with 400 — the body is strict. Preview accepts: object_type required: e.g. "persons", "organizations", "deals" properties required: non-empty array of Pipedrive field names properties_metadata array<{name, label, field_type?}>; optional filters filter groups (see §5); optional Create accepts all the preview fields plus: name required: display name for the new source pull_mode required: "static" | "active" schedule cron string; required when pull_mode === "active" expiration_date ISO date (YYYY-MM-DD); optional (active source only) pull_existing boolean; optional, defaults to true (backfill existing records on create) ================================================================================ 4. FIELD CATALOGUE ================================================================================ object_type (string) — required The Pipedrive object to pull. Common values: "persons", "organizations", "deals". The chosen object type also drives which field names are valid in `properties` and which the `properties` dynamic-options call returns (see §6). properties (string[]) — required Non-empty array of Pipedrive field names (keys) to import for each record. Resolve the available field names with the `properties` dynamic-options call for the chosen `object_type`. properties_metadata (array) — optional Each item is `{ name, label, field_type? }`. Supplying it gives each imported cell a human `label` (the field's display name) instead of the raw field key. Pass the array returned by the `properties` dynamic-options call straight through. filters (object) — optional Restrict the import to records matching a filter expression (see §5). Omit to import every record of the chosen object type. name (string) — required on create only Human-readable display name for the source. pull_mode (string) — required on create only "static" (one-time) or "active" (ongoing). See §2. schedule (string) — required on create when pull_mode === "active" Cron string for the re-import cadence (e.g. "0 12 * * *"). expiration_date (string) — optional, active only ISO date (YYYY-MM-DD) after which an active source stops re-importing. pull_existing (boolean) — optional, create only Defaults to true. When true, existing matching records are imported on create; when false, the source only picks up records going forward. ================================================================================ 5. FILTER SHAPE ================================================================================ `filters` (optional) is a group-based filter expression. The shape: filters: { operator?: "AND" | "OR", // how the groups combine conditions?: [ { operator?: "AND" | "OR", // how leaves within a group combine conditions?: [ { variable: "", condition?: "", variable_type?: "", values?: [, ...], operator?: "", case_sensitive?: } ] } ] } Each leaf names a Pipedrive field (`variable`), a comparison, and the value(s) to match. Leaves within one group combine by that group's `operator`; groups combine by the top-level `operator`. Omit `filters` entirely to import all records of the object type. ================================================================================ 6. DYNAMIC OPTIONS ================================================================================ One dynamic-options field name is available for this source. POST to /api/v1/sources/import_from_pipedrive/options/properties with body `{ "context": { "object_type": "" } }`. properties Context: requires `object_type` in the context (the call returns the field catalogue for that object). Set the same `object_type` you will send on preview / create. Returns: {value: , label: , extras: }. Use the `value`s inside `properties[]`. To get labeled cells in the imported rows, pass the full returned array into `properties_metadata`. Connection check: the call verifies the API-key user has an active Pipedrive connection first. Missing connection → 424. ================================================================================ 7. HOW TO CONFIGURE END-TO-END ================================================================================ Typical flow for an AI agent building a Pipedrive import source: Step 1 — Resolve the property catalog POST /api/v1/sources/import_from_pipedrive/options/properties Body: {"context": {"object_type": "persons"}} Stash the full response array as `properties_metadata` (gets you labeled cells). Pick a subset of `.value`s as `properties`. Step 2 — Preview before committing POST /api/v1/sources/import_from_pipedrive/preview Body: { "object_type": "persons", "properties": ["name", "email", "org_name"], "properties_metadata": [...], // from step 1 "filters": { ... } } // optional Check the returned `data[]` and `metadata.total_results`. Iterate the body until you're happy — preview never creates anything. Step 3 — Create the source POST /api/v1/sources/import_from_pipedrive Body: + the create-only fields: "name": "", "pull_mode": "static" | "active", "schedule": "0 12 * * *", // only when pull_mode=active "expiration_date": "2027-01-01", // optional, active only "pull_existing": true // optional, defaults true Response: { "status": 201, "data": { "source_instance_id": "", "name", "created_at" }} Step 3b — (Optional) Poll imported rows while the import runs GET /api/v1/sources//data?page_no=1&page_size=20 ( = UUID from Step 3) Row keys match the property names you imported. `total_count` grows until the import finishes. Step 4 — Sync the source into a workflow (so its records flow downstream) POST /api/v1/sources//sync ( = UUID from Step 3 ) First build `field_mapping`: a. GET /api/v1/workflows → pick the destination workflow_id. b. GET /api/v1/workflows//sheets//inputs → each input has a `reference` like `{{input.email}}`. c. Map each workflow input (reference WITHOUT braces) to a source field — the source fields are the Pipedrive field keys you imported. Body: { "workflow_id": "", "field_mapping": { "input.email": "email", "input.name": "name" }, "push_existing": true, "run": "all" } See concepts.txt §10 for the full sync semantics (source-agnostic). The initial import runs asynchronously — the create call returns as soon as the source is created and the import has started, not when records have finished arriving. ================================================================================ 8. KEY NOTES ================================================================================ - Pipedrive connection is mandatory. If the API-key user has no active Pipedrive connection, every endpoint (preview, create, options) returns 424 ("User is not connected to 'pipedrive'."). Surface this as a "connect Pipedrive first" CTA. - `object_type` and `properties` are both required on preview and create. Always resolve `properties` from the dynamic-options call for the chosen `object_type` — a field key that doesn't exist for that object errors. - Preview returns a sample page (up to ~100 rows, scanning a bounded number of Pipedrive pages). It does not create anything. - `filters` is optional — omit it to import every record of the object type. - `properties_metadata` is optional but recommended: it labels imported cells with the field's display name instead of the raw key. - Credits are consumed when the source is created. If credit consumption fails (e.g. insufficient balance), the source is still created but its import can't start; the API returns 402 so you can top up and retry. - Use PATCH /status to pause an active source and resume it later without recreating it. ================================================================================ 9. WHERE IT FITS ================================================================================ UPSTREAM (in Pipedrive) Persons, organizations, and deals live in the user's Pipedrive account. Field values and filter results come from Pipedrive's own data model. THIS SOURCE Creates a Pipedrive import source. On creation it imports matching records immediately (when `pull_existing`); an active source also re-imports on the `schedule` cron until `expiration_date`. DOWNSTREAM (in Floqer) Imported records become available to your Floqer workflows — wire the source into a workflow to enrich, score, or run outreach on each record. ================================================================================ 10. WHEN TO USE ================================================================================ - One-time export of Pipedrive records matching filters for enrichment / outreach: `pull_mode: static`. - Keep a Pipedrive segment in sync with a Floqer workflow on a schedule: `pull_mode: active`, `schedule: "0 12 * * *"`. When you instead want to push data OUT of Floqer INTO Pipedrive, use the Pipedrive action templates inside a workflow — see the action catalog in llms-full.txt. ================================================================================ Last updated: 2026-06-02. Reference: https://floqer.com/docs/reference