ACTION_ID: salesforce_lookup_record
NAME: Salesforce: Lookup Record
CATEGORY: CRM
CREDITS: 0

Look up a record in Salesforce.

PREREQUISITE: Salesforce org 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

salesforce_object (dropdown, required)
  Salesforce Object.

add_fields_and_their_values (jsonArray, required)
  Add Fields and their Values. Select Fields from the object and add
  Values to filter on.

search_operator (normalDropdown, required)
  Search Operator. AND requires all fields to match, OR requires at
  least one field to match. Values: OR, AND.

exact_match (radio, optional)
  Exact Match. Look for an exact match in all search fields. Default
  is contains-search.

2. OUTPUTS

records_found (structured_array) — Records Found. Per-record columns
  match the fields you queried under
  `add_fields_and_their_values`. Reference one column at a time via
  `{{<this_action_instance_id>.records_found.<column>}}`.
record_id (string) — Record Id.
phonenumber (string) — PhoneNumber.
websites (string) — Websites.
owner_name (string) — Owner Name.
owner_id (string) — Owner Id.
account_url (url) — Account URL. Salesforce Account URL.

3. HOW TO CONFIGURE

Resolve dynamic field values via Get Action Field Options before
configuring:

  POST /api/v1/workflows/{workflow_id}/sheets/{sheet_id}/actions/{action_instance_id}/options/salesforce_object
       (body: {})
  POST .../options/add_fields_and_their_values
       (body: { "context": { "salesforce_object": "Account" } })

Configure Action body:

{
  "inputs": {
    "salesforce_object": "Account",
    "add_fields_and_their_values": [
      { "name": "Website", "value": "{{input.domain}}" },
      { "name": "Name",    "value": "{{input.company_name}}" }
    ],
    "search_operator": "AND",
    "exact_match": false
  }
}

Field-by-field:
  - salesforce_object              Object name from the
                                   `salesforce_object` options call.
  - add_fields_and_their_values    `[{name, value}]` filter criteria.
                                   Each item is "field equals (or
                                   contains) value" depending on
                                   `exact_match`.
  - search_operator                "AND" (all criteria match) or "OR"
                                   (any criterion matches).
  - exact_match                    `true` for exact-string match;
                                   `false` (default) for contains-search.

4. KEY NOTES

- Returns up to one match per criterion in the structured `records_found`
  output (a `structured_array`); the top-level `record_id` /
  `phonenumber` / `owner_*` / `account_url` outputs reflect the FIRST
  match — convenient for the common single-record case but ambiguous
  when multiple records match.
- For multi-record results, the 3-segment `structured_array_reference`
  shape (`{{<this_action_instance_id>.records_found.<column>}}`) is
  valid in column-mapping contexts only — `push_data_to_sheet`'s
  `choose_columns_to_send_to`, `run_if` over a list, and similar
  fan-out fields. It does NOT work inside a
  `formula` formula (those refs substitute
  as empty strings, and Salesforce's per-column refs additionally
  raise `unresolved_reference` warnings on PATCH because the
  columns aren't pre-registered). To consume `records_found` in JS,
  use the responseId pattern:
  https://floqer.com/docs/use-case-detail/extract_data_from_crm.txt
  §5.4.
- The Salesforce connection must live on the API key's user
  account. If the connection lives under a different team member,
  Get Action Field Options returns a 424 — provision the API key
  from the user who owns the connection.
- Token refresh is automatic on transient `INVALID_SESSION_ID`; one
  retry, then 502.

5. WHERE IT FITS IN A WORKFLOW

Pattern: salesforce_lookup_record -> workflow_if_else (found / not
found) -> salesforce_create_record / salesforce_update_record.

6. WHEN TO USE

Use salesforce_lookup_record to read existing records.

7. WHEN NOT TO USE

Need create-or-update on an external ID
  -> action-detail/salesforce_upsert_record.txt

Need to create regardless
  -> action-detail/salesforce_create_record.txt

Need to update by Salesforce ID
  -> action-detail/salesforce_update_record.txt

Last updated: 2026-05-25.