ACTION_ID: close_crm_lookup_create_lead
NAME: Close CRM: Create or Update Lead
CATEGORY: CRM
CREDITS: 0

Look a lead up by name in Close and update it, or create it when nothing
matches. The single-step version of lookup-then-branch-then-create, and
the safe default for any chain that runs more than once over the same
companies.

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

full_name (string, required)
  Full Name. The name of the lead. Doubles as the MATCH KEY — this is
  what the lookup half searches on.

website_url (string, optional)
  Website URL. The website URL of the lead.

description (string, optional)
  Description. The description of the lead.

status (dynamicDropdown, optional)
  Status. The lead status to set. Resolve the allowed values through Get
  Action Field Options — Close statuses are per-organisation.

mailing_address_1 (string, optional)
  Mailing Address 1. Mailing Address 1 of the lead.

mailing_address_2 (string, optional)
  Mailing Address 2. Mailing Address 2 of the lead.

mailing_city (string, optional)
  Mailing City. Mailing City of the lead.

mailing_state (string, optional)
  Mailing State. Mailing State of the lead.

mailing_zipcode (string, optional)
  Mailing Zipcode. Mailing Zipcode of the lead.

mailing_country (string, optional)
  Mailing Country. Mailing Country of the lead.

business_address_1 (string, optional)
  Business Address 1. Business Address 1 of the lead.

business_address_2 (string, optional)
  Business Address 2. Business Address 2 of the lead.

business_city (string, optional)
  Business City. Business City of the lead.

business_state (string, optional)
  Business State. Business State of the lead.

business_zipcode (string, optional)
  Business Zipcode. Business Zipcode of the lead.

business_country (string, optional)
  Business Country. Business Country of the lead.

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

2. OUTPUTS

id (string) — ID of the Lead. The value downstream Close actions need as
their `lead_id`.
isnew (boolean) — Is New. True when the lead was created, false when an
existing lead was updated. The branch key for "did we just add this
company?"
full_name (string) — Name of the Lead
display_name (string) — Display Name of the Lead
organization_id (string) — Organization ID of the Lead
status_id (string) — Status ID of the Lead
status_label (string) — Status Label of the Lead
description (string) — Description of the Lead
url (url) — URL of the Lead
html_url (url) — HTML URL of the Lead
addresses (raw_array) — Addresses of the Lead
contacts (raw_array) — Contacts of the Lead
opportunities (raw_array) — Opportunities of the Lead
tasks (raw_array) — Tasks of the Lead
integration_links (raw_array) — Integration Links
custom (json) — Custom of the Lead
created_by (string) — Created By
created_by_name (string) — Created By Name
updated_by (string) — Updated By
updated_by_name (string) — Updated By Name
date_created (string) — Date Created
date_updated (string) — Date Updated

3. HOW TO CONFIGURE

`status` is a dynamic dropdown — resolve it before configuring:

  POST /api/v1/workflows/{workflow_id}/sheets/{sheet_id}/actions/{action_instance_id}/options/status
       (body: {})
       → the lead statuses defined in the connected Close organisation.

Configure Action body:

{
  "inputs": {
    "full_name": "{{input.company_name}}",
    "website_url": "{{input.company_domain}}",
    "status": "<status id from the options call>",
    "business_country": "{{floqer_company_firmographics_01ab.country}}"
  }
}

Field-by-field:
  - full_name   Both the value written and the key matched on. Normalise
                it upstream so re-runs match instead of duplicating.
  - status      Pass the status ID from the options call, not the label.

4. KEY NOTES

- The match is on NAME. "Acme", "Acme Inc" and "Acme, Inc." are three
  different leads to Close, so a chain that builds the name differently on
  a later run creates a second lead instead of updating the first.
  Normalise with `formula` before this step and keep that normalisation
  stable.
- `isnew` is the useful branch: gate onboarding-only work (send an intro
  task, add to a "new logos" sequence) on `isnew is true` so re-runs stay
  quiet.
- Update mode overwrites the fields you send and leaves the rest alone.
  Sending an empty string is a write — it clears the field in Close rather
  than skipping it.
- Read the lead ID off `id`, not `organization_id`. `organization_id` is
  the user's Close workspace and is identical on every row.

5. WHERE IT FITS IN A WORKFLOW

Pattern: enrichment -> close_crm_lookup_create_lead ->
close_crm_upsert_contact (lead_id:
{{close_crm_lookup_create_lead_01ab.id}}). Safe to re-run end to end.

6. WHEN TO USE

Use close_crm_lookup_create_lead for any scheduled or repeated chain, and
whenever you cannot be sure the company is absent from Close.

7. WHEN NOT TO USE

The lead is definitely new and you want the cheaper single write
  -> action-detail/close_crm_create_lead.txt

You only need the ID and must not write anything
  -> action-detail/close_crm_lookup_lead.txt

Last updated: 2026-08-13.