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. 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 action-catalog.txt. Last updated: 2026-06-02. Reference: https://floqer.com/docs/reference