ACTION_ID: pipedrive_upsert_record
NAME: Pipedrive : Upsert
CATEGORY: CRM
CREDITS: 0

Add a Person or Organization to Pipedrive, or update the existing one
when a match is found. Reports which of create / update / found actually
happened.

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 upsert a Person or an Organization
  Values:
    - { value: "persons", label: "Person" }
    - { value: "organizations", label: "Organization" }

mode (dropdown, required)
  Mode. Add Only: always creates a new record. Upsert: looks up the
  record first and updates it if found, otherwise creates it.
  Values:
    - { value: "add_only", label: "Insert Only" }
    - { value: "upsert", label: "Upsert (add or update)" }

record_id_optional (string, optional)
  Record ID (optional). Pipedrive record ID. If provided, skips
  email/name lookup and uses this ID directly to update the existing
  record.

name (string, optional)
  Name. Full name of the Person or Organization

email (email, optional)
  Email. Email address. Also used as the lookup key in Upsert mode.

phone (string, optional)
  Phone. Phone number

owner (dynamicDropdown, optional)
  Owner. The user who will be marked as the owner of this record

visibility (dropdown, optional)
  Visibility. Visibility setting for this record
  Values:
    - { value: 1, label: "Owner & followers" }
    - { value: 3, label: "Entire Company" }

marketing_status (dropdown, optional)
  Marketing Status. Marketing status
  Values:
    - { value: "no_consent", label: "No Consent" }
    - { value: "unsubscribed", label: "Unsubscribed" }
    - { value: "subscribed", label: "Subscribed" }
    - { value: "archived", label: "Archived" }

more_fields (dynamicJsonArray, optional)
  More Fields. Additional standard organization fields

custom_fields (dynamicJsonArray, optional)
  Custom Fields. Custom fields for the organization

2. OUTPUTS

id (number) — Pipedrive ID of the created or updated record

name (string) — Name of the person or organization

phones (raw_array) — Phone numbers (persons only)

emails (raw_array) — Email addresses (persons only)

primary_email (email) — Primary email address (persons only)

owner (number) — Owner ID of the record

organization (number) — Linked organization ID (persons only)

address (string) — Address (organizations only)

custom_fields (raw_array) — Custom fields of the record

update_time (date) — Last updated time of the record

action (string) — What action was taken: 'created' (new record),
'updated' (existing record updated), or 'found' (existing record,
add_only mode skipped update)

3. HOW TO CONFIGURE

`more_fields` and `custom_fields` resolve against the entity type, so
pass it as context:

  POST .../options/more_fields    (body: { "context": { "entity_type": "persons" } })
  POST .../options/custom_fields  (body: { "context": { "entity_type": "persons" } })

Configure Action body:

{
  "inputs": {
    "entity_type": "persons",
    "mode": "upsert",
    "name": "{{input.full_name}}",
    "email": "{{person_work_email_waterfall_01ab.work_email}}",
    "phone": "{{person_enrich_by_floqer_01cd.phone_number}}",
    "visibility": "3",
    "marketing_status": "no_consent",
    "custom_fields": [
      { "name": "<field key from options>", "value": "{{input.segment}}" }
    ]
  }
}

Field-by-field:
  - entity_type        `persons` or `organizations`.
  - mode               `add_only` always creates; `upsert` looks the
                       record up first and updates it when found.
  - record_id          Skips the lookup entirely and updates that ID.
                       Pass as a quoted string.
  - email              The upsert key in `upsert` mode for Persons.
  - visibility         `1` (owner and followers) or `3` (entire
                       company) — pass as a quoted string.
  - custom_fields      `[{name, value}]` where `name` is the Pipedrive
                       field key from the options response.

4. KEY NOTES

- The template defines separate Person and Organization variants of
  `more_fields` and `custom_fields`, and both pairs snake-case to the
  same public name. Only the Organization variant is addressable over
  the API — the Person variants are shadowed and cannot be written. Use
  `record_id` plus Pipedrive's own UI, or `http_api_call`, if you need
  Person-specific custom fields.
- Numeric-looking fields (`record_id`, `visibility`) must be passed as
  quoted strings. Configure Action ignores raw JSON numbers with an
  `unknown_field` warning.
- `action` tells you what happened: `created`, `updated`, or `found` (an
  existing record left untouched because `mode` was `add_only`). Branch
  on it with `run_if`.
- In `upsert` mode for Organizations the lookup key is the name, which
  is much weaker than an email match — expect false positives on common
  company names.

5. WHERE IT FITS IN A WORKFLOW

Pattern: enrichment chain -> pipedrive_upsert_record (entity_type
organizations) -> pipedrive_upsert_record (entity_type persons) so the
person can be linked to the org that was just created.

6. WHEN TO USE

Use pipedrive_upsert_record to keep Pipedrive in sync with enriched rows
without maintaining a separate lookup-then-create branch.

7. WHEN NOT TO USE

Only need to read from Pipedrive
  -> action-detail/pipedrive_lookup_record.txt

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

Last updated: 2026-08-03.