ACTION_ID: attio_lookup_record
NAME: Attio: Lookup Record
CATEGORY: CRM
CREDITS: 0

Find records in any Attio object by matching on attribute values.

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

This action only works if the user has connected their Attio workspace
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 Attio and complete the OAuth flow

If the user has not connected Attio, this action will fail with a
connection / authentication error. Before configuring or running this
action, confirm with the user that the Attio 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
================================================================================

attio_object (dynamicDropdown, required)
  Attio Object. Choose the Attio object to search in (People,
  Companies, Deals, or any custom object). Value is the object's
  api_slug — "people", "companies", "deals", or a custom slug.

add_attributes_and_their_values (jsonArray, required)
  Add Attributes and their Values. Select attributes from the object
  and add the values to match on. Read-only attributes (created_at,
  formulas) can be searched too — this is the readable catalogue, not
  the writable one.

search_operator (dropdown, required)
  Search Operator. "AND" requires every attribute to match, "OR"
  requires at least one. Default "AND".

exact_match (radio, optional)
  Exact Match. Default ON. ON matches the value exactly. OFF does a
  contains search, which Attio supports only on text, domain, email,
  phone and personal-name attributes — every other attribute type
  still matches exactly regardless of this toggle.

limit (text, optional)
  Limit. Maximum number of records to return. Default 10, maximum
  10000. Accepts a {{reference}}.

output_columns (dynamicMultiDropdown, optional)
  Output Columns. Which Attio attributes come back as columns on each
  row of `records_found`. Leave empty to return every attribute on the
  object.

================================================================================
2. OUTPUTS
================================================================================

records_found (structured_array) — Records Found. One row per matched
record. Columns are the attributes chosen in `output_columns` (every
attribute when that is empty), plus the record's id and URL.
  The columns are minted when you configure the action, so
  `{{<action_instance_id>.records_found.<column>}}` references can be
  written straight away — no test run needed. Re-selecting
  `output_columns` keeps the ids of columns that survive, so references
  to them stay valid; Get Action Outputs lists the current set.
record_ids (string) — Record IDs. Comma-separated Attio record IDs
for each matched record.
record_urls (url) — Record URLs. Comma-separated Attio links for
each matched record.
records_found_count (number) — Records Found Count. How many records
matched.

================================================================================
3. HOW TO CONFIGURE
================================================================================

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

  POST /api/v1/workflows/{workflow_id}/sheets/{sheet_id}/actions/{action_instance_id}/options/attio_object
       (body: {})
       → the objects in the connected Attio workspace.

  POST .../options/add_attributes_and_their_values
       (body: { "context": { "attio_object": "people" } })
       → every readable attribute on the chosen object. Each option's
         `extras` carries the Attio `type`, whether it accepts
         multiple values, and a `reference` token when its values come
         from a list.

  POST .../options/add_attributes_and_their_values
       (body: { "context": { "reference": "<token from extras>" } })
       → the selectable values behind that token (select options,
         status values, workspace members, referenced records).

  POST .../options/output_columns
       (body: { "context": { "attio_object": "people" } })
       → the same readable attribute catalogue, for choosing columns.

Configure Action body:

{
  "inputs": {
    "attio_object": "people",
    "add_attributes_and_their_values": [
      { "name": "email_addresses", "value": "{{input.work_email}}" }
    ],
    "search_operator": "AND",
    "exact_match": true,
    "limit": "10",
    "output_columns": ["name", "job_title", "company"]
  }
}

Field-by-field:
  - attio_object                     Object api_slug from the
                                     `attio_object` options call.
  - add_attributes_and_their_values  `[{name, value}]` — `name` is the
                                     attribute api_slug, `value`
                                     accepts `{{ref}}` tokens or
                                     literals. Every entry becomes a
                                     match condition joined by
                                     `search_operator`.
  - search_operator                  "AND" or "OR".
  - exact_match                      `false` switches text-like
                                     attributes to a contains search.
  - limit                            String or number; capped at 10000.
  - output_columns                   Attribute api_slugs. Omit to get
                                     every attribute.

================================================================================
4. KEY NOTES
================================================================================

- The Attio 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.
- An attribute the selected object does not have comes back as a
  `warnings[]` entry (`unknown_field`) from Configure Action, and the row
  is ignored at run time — check `warnings` after configuring rather than
  waiting for the run.
- `exact_match: false` only widens the attributes whose Attio type
  supports a contains search (text, domain, email-address,
  phone-number, personal-name). A number, date, select or checkbox
  attribute keeps matching exactly, because Attio rejects a contains
  operator on those outright.
- Composite attributes are matched on their meaningful sub-field —
  `name` on `full_name`, `domains` on `domain`, `email_addresses` on
  `email_address`, `phone_numbers` on `phone_number` — so pass the
  plain value ("ada@acme.com"), not a nested object.
- Attio's tokens do not expire, so there is no refresh step; a 401
  means the workspace revoked the connection and the user has to
  reconnect.
- Zero matches is a successful run: `records_found_count` is 0 and
  `record_ids` is empty. Branch on it with `run_if` rather than
  treating it as a failure.
- `records_found` is a structured_array — reference a column downstream as
  `{{attio_lookup_record_1.records_found.name}}`.

================================================================================
5. WHERE IT FITS IN A WORKFLOW
================================================================================

Pattern: input row -> attio_lookup_record -> workflow_if_else
(run_if: {{lookup.record_ids}} is empty) -> attio_create_record on
the empty branch, attio_update_record on the other.

================================================================================
6. WHEN TO USE
================================================================================

Use attio_lookup_record to check whether a record already exists, to
pull attributes off an existing record for enrichment, or to fetch a
record id for a later update.

================================================================================
7. WHEN NOT TO USE
================================================================================

You want create-or-update in one step
  -> attio_upsert_record
     (https://floqer.com/docs/action-detail/attio_upsert_record.txt)

You want to import an Attio object into a list, not look records up
per row
  -> import_from_attio source
     (https://floqer.com/docs/source-detail/import_from_attio.txt)

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

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