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

Look up a record in Salesforce.

================================================================================
PREREQUISITE — USER ACTION REQUIRED
================================================================================

This action only works if the user has connected their Salesforce org
in Floqer. The connection cannot be made via the API or by an AI agent.

The user must do this themselves before this action will run:
  1. Sign in to Floqer at https://app.floqer.com
  2. Open the Connections page from the sidebar
  3. Click Salesforce and complete the OAuth flow

If the user has not connected Salesforce, this action will fail with a
connection / authentication error. Before configuring or running this
action, confirm with the user that the Salesforce connection exists.

INDEX:
  1. Inputs
  2. Outputs
  3. How to configure
  4. Key notes
  5. Where it fits in a workflow
  6. When to use
  7. When not to use

================================================================================
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, reference the structured list output via
  the 3-segment `structured_array_reference` shape
  (`{{<this_action_instance_id>.records_found.<column>}}`).
- 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
  -> salesforce_upsert_record
     (https://floqer.com/docs/action-detail/salesforce_upsert_record.txt)

Need to create regardless
  -> salesforce_create_record
     (https://floqer.com/docs/action-detail/salesforce_create_record.txt)

Need to update by Salesforce ID
  -> salesforce_update_record
     (https://floqer.com/docs/action-detail/salesforce_update_record.txt)

================================================================================

This file is maintained manually. Last updated: 2026-04-28.
Full interactive reference: https://floqer.com/docs/reference
Action catalog: https://floqer.com/docs/action-catalog.txt