ACTION_ID: close_crm_upsert_contact
NAME: Close CRM: Upsert Contact
CATEGORY: CRM
CREDITS: 0

Create a contact on a Close lead, or update the existing one when the name
already appears there. The re-runnable counterpart to
close_crm_add_contact — reach for this in any scheduled chain.

PREREQUISITE: Close CRM 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

lead_id (string, optional)
  Lead Id. The lead this contact belongs to. Optional in the schema, but
  in practice required — see KEY NOTES.

full_name (string, optional)
  Full Name. The name of the contact. Doubles as the MATCH KEY — the
  update half looks the contact up by name.

title (string, optional)
  Title. The title of the contact.

phones (jsonArrayWithDropDown, optional)
  Phones. The phones of the contact. Each entry pairs a number with a
  type.
  Types:
    - { value: "office", label: "Office" }
    - { value: "mobile", label: "Mobile" }
    - { value: "home", label: "Home" }
    - { value: "direct", label: "Direct" }
    - { value: "fax", label: "Fax" }
    - { value: "url", label: "URL" }
    - { value: "other", label: "Other" }

emails (jsonArrayWithDropDown, optional)
  Emails. The emails of the contact, each paired with a type from the same
  list as phones.

urls (jsonArrayWithDropDown, optional)
  Urls. The urls of the contact, each paired with a type from the same
  list as phones.

custom_fields (jsonArray, optional)
  Custom Fields. The custom fields of the contact, as `[{name, value}]`.

2. OUTPUTS

contact_id (string) — The id of the contact
lead_id (string) — The lead id of the contact
organization_id (string) — The organization id of the contact
full_name (string) — The name of the contact
display_name (string) — The display name of the contact
title (string) — The title of the contact
emails (raw_array) — The emails of the contact
phones (raw_array) — The phones of the contact
urls (raw_array) — The urls of the contact
integration_links (raw_array) — The integration links of the contact
created_by (string) — The user who created the contact
updated_by (string) — The user who updated the contact
date_created (date) — The date the contact was created
date_updated (date) — The date the contact was updated

3. HOW TO CONFIGURE

Configure Action body:

{
  "inputs": {
    "lead_id": "{{close_crm_lookup_create_lead_01ab.id}}",
    "full_name": "{{input.full_name}}",
    "title": "{{enrich_person_linkedin_profile_01cd.person_current_job_title}}",
    "emails": [
      { "value": "{{person_work_email_waterfall_01ef.work_email}}", "type": "office" }
    ]
  }
}

Field-by-field:
  - lead_id        Schema-optional, practically required. See KEY NOTES.
  - full_name      Both written and matched on. Keep it stable across
                   runs or the upsert creates duplicates.
  - emails/phones  Arrays of `{value, type}` using the types in §1.

4. KEY NOTES

- The match key is NAME, scoped to the lead — not email. Two people
  called "Chris Smith" on one lead collapse into a single contact, and a
  name that changes between runs ("Chris Smith" then "Christopher Smith")
  creates a second one. Normalise the name upstream with `formula` and
  keep that normalisation fixed.
- `lead_id` is marked optional in the template but the contact has
  nowhere to live without it. Always pass it; treat the optional flag as
  a schema artefact, not permission to omit it.
- Update mode overwrites the fields you send. An empty string is a write
  and clears the field in Close — omit a field entirely to leave it
  untouched.
- Email and phone arrays REPLACE rather than append. Send the full set
  you want the contact to end up with, not just the new entry, or the
  previously stored addresses disappear.
- Read the ID from `contact_id`, and the lead from `lead_id` —
  `organization_id` is the user's Close workspace and constant across
  rows.

5. WHERE IT FITS IN A WORKFLOW

Pattern: close_crm_lookup_create_lead -> employee finder ->
person_work_email_waterfall -> close_crm_upsert_contact. Every step is
idempotent, so the whole chain can run on a schedule.

6. WHEN TO USE

Use close_crm_upsert_contact whenever the chain can run more than once
over the same people — scheduled refreshes, re-enrichment, or any list
that grows over time.

7. WHEN NOT TO USE

A strict one-shot import where a second write should be visible
  -> action-detail/close_crm_add_contact.txt

You are writing the company record, not a person
  -> action-detail/close_crm_lookup_create_lead.txt

Last updated: 2026-08-13.