Find contacts by tag

Identifier and availability

• Type: action
• Stable identifier: contact:search_by_tag
• Status: Selectable — available in the new-node selector and importable.

Purpose

Finds contacts with a tag and branches on the result.

Prerequisites and context

Required configuration: contact_tag. Review the available context below before using variables.

Parameters

Unknown parameter and settings keys are rejected. Resource references use names, emails, document keys, or endpoints rather than database IDs.

Inputs and available variables

Action variables: search.tag. Context exposed on found: contact.

Templated strings use double braces, for example {{contact.first_name}}. Availability in the editor does not create runtime context; the trigger and preceding branch still need to provide it.

Connections and branches

Connect this action into a root path with branch actions or into an existing branch using that parent’s token. It then terminates its current sequential path and exposes these exact, case-sensitive branch ports: found, not_found. Put following work inside those branches; do not place a sibling after this action.

Connection fragment:

{
    "from": "action_contact_search_by_tag",
    "to": "next_action",
    "branch": "found",
    "order": 1
}

Valid JSON node example

{
    "key": "action_contact_search_by_tag",
    "type": "action",
    "name": "contact:search_by_tag",
    "display_name": null,
    "parameters": {
        "contact_tag": {
            "name": "VIP",
            "create_if_missing": false
        }
    }
}

Validation and runtime caveats

The found branch runs independently once for every matching contact; it is not a graph fan-out.

See the Automation JSON import format for the envelope, dependency resolution, graph rules, complete examples, and AI author checklist.