ACTION_ID: pipedrive_lookup_record
NAME: Pipedrive : Lookup
CATEGORY: CRM
CREDITS: 0

Find a Person or an Organization in Pipedrive by email or name, and
return every match as a structured array. The read half of the
lookup-then-write pattern.

PREREQUISITE: Pipedrive account connection — the user must create it in the Floqer UI
(Connections page); an agent cannot. Without it the action fails the row with
a connection / authentication error. Confirm it exists before configuring.

1. INPUTS

entity_type (dropdown, required)
  Entity Type. Whether to look up a Person or an Organization
  Values:
    - { value: "persons", label: "Person" }
    - { value: "organizations", label: "Organization" }

lookup_value (string, required)
  Lookup Value. Email address for Person lookup, or company name for
  Organization lookup

exact_match (radio, optional)
  Exact Match. When enabled, only returns results that exactly match
  the lookup value

fields (multiDropdown, optional)
  Fields. Which Pipedrive fields to search in. Defaults to all. Only
  the following custom field types are searchable: address, varchar,
  text, varchar_auto, double, monetary and phone.
  Values:
    - { value: "email", label: "Email" }
    - { value: "name", label: "Name" }
    - { value: "phone", label: "Phone" }
    - { value: "notes", label: "Notes" }
    - { value: "custom_fields", label: "Custom Fields" }

fields (multiDropdown, optional)
  Fields. Which Pipedrive fields to search in. Defaults to all. Only
  the following custom field types are searchable: address, varchar,
  text, varchar_auto, double, monetary and phone.
  Values:
    - { value: "name", label: "Name" }
    - { value: "address", label: "Address" }
    - { value: "notes", label: "Notes" }
    - { value: "custom_fields", label: "Custom Fields" }

2. OUTPUTS

records (structured_array) — All matching records found in Pipedrive

  Columns — reference as {{<action_instance_id>.records.<column>}}:
    id (number) — Pipedrive ID of the record
    name (string) — Full name or organization name
    emails (raw_array) — Email addresses (persons only)
    primary_email (string) — Primary email address (persons only)
    phones (raw_array) — Phone numbers (persons only)
    owner_id (number) — ID of the record owner
    organization_id (number) — ID of the linked organization (persons only)
    address (string) — Address (organizations only)
    custom_fields (object) — Custom field values
    notes (raw_array) — Notes attached to the record
    update_time (string) — Time of last update (persons only)

count (number) — Number of records found

3. HOW TO CONFIGURE

No dynamic dropdowns — the entity type and searchable field sets are
static enums. Configure Action body:

{
  "inputs": {
    "entity_type": "persons",
    "lookup_value": "{{person_work_email_waterfall_01ab.work_email}}",
    "exact_match": true,
    "fields": ["email"]
  }
}

Field-by-field:
  - entity_type   `persons` or `organizations`. Decides which of the two
                  `fields` enums applies.
  - lookup_value  Email address for a Person lookup, company name for an
                  Organization lookup.
  - exact_match   Boolean. `true` returns only exact matches; `false`
                  lets Pipedrive fuzzy-match.
  - fields        Which Pipedrive fields to search in. Omit for all. Note
                  BOTH `fields` variants below snake-case to the same
                  public name — see KEY NOTES.

4. KEY NOTES

- The Person and Organization field selectors are two separate template
  fields that both snake-case to `fields`, so only the Organization enum
  (`name`, `address`, `notes`, `custom_fields`) is addressable over the
  API. To search Person-only fields such as `phone`, leave `fields`
  unset — Pipedrive then searches all of them.
- `records` is a `structured_array`. Column references
  (`{{…records.primary_email}}`) work in column-mapping contexts such as
  `push_data_to_sheet`, but not inside a `formula`.
- Only these Pipedrive custom-field types are searchable: address,
  varchar, text, varchar_auto, double, monetary and phone. A lookup
  against any other custom-field type silently returns nothing.
- A miss returns `count: 0` and an empty `records` array rather than
  failing the row — branch with `run_if` on `count`.

5. WHERE IT FITS IN A WORKFLOW

Pattern: pipedrive_lookup_record -> pipedrive_upsert_record (run_if:
count is 0) for a create-if-absent branch, or -> filter (count greater
than 0) to keep only known accounts.

6. WHEN TO USE

Use pipedrive_lookup_record to check whether a person or company is
already in Pipedrive, or to pull its record ID before an update.

7. WHEN NOT TO USE

Need to write the record rather than read it
  -> action-detail/pipedrive_upsert_record.txt

The CRM is HubSpot
  -> action-detail/hubspot_lookup_object.txt

Last updated: 2026-08-03.