> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firsttouch.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> For API operations, fetch https://gateway.firsttouch.ai/api/public/openapi.json for the complete input/output schemas, internal references, and x-mcp-annotations. Endpoint Markdown intentionally omits generated schema fragments. Select /api/public/tools/<tool_name> using the exact underscore-separated name. Send requests to https://gateway.firsttouch.ai; the canonical document currently omits servers. Start at https://docs.firsttouch.com/api-reference/agent-start.md.

# Variables and Personalization

> Use exact variable syntax, HubSpot custom properties, and research outputs, and understand which CSV fields can personalize messages.

Use variables to insert prospect-specific data into a message. Use AI messaging when you want FirstTouch to generate text from that data and your instructions.

## Choose a Personalization Method

| Method | Use it for | What to know |
| - | - | - |
| FirstTouch variables | Saved contact and company details, such as first name or company name. | A supported field can still be empty for a particular prospect. |
| Sender variables | The sender's name or company name. | Select these from the **Sender** group where available. |
| HubSpot variables | Available Contact and Company properties, including custom properties. | Requires a connected HubSpot account and a matching record with a value. |
| Research outputs | Findings from an earlier advanced Research Agent on the same path. | These are generated findings, not imported CSV notes. |
| Signal context | The engagement or website visit that triggered outreach. | Available fields depend on the Flow Plan's source. |
| AI instructions | A different opening or message based on available context. | Enable **AI messaging** before using instructions in square brackets. |
| Static text | Fixed wording, links, and sign-offs. | Use alongside variables when you want to control the message's wording. |

To send different messages to different segments, use a [Conditional Split](https://docs.firsttouch.com/WebApp/Flows/Available-Flow-Actions/Conditional-Split.md). A split chooses a path; it does not create or populate a variable.

## Insert a Variable

1. Open the message editor for an email, connection note, LinkedIn message, or available InMail step.
2. Open the variable menu by typing `{`.
3. Choose a group, search for the field, and select it.
4. Preview the message for a contact before publishing.

The menu shows fields available in that editor and flow context. **Flow** appears when contextual fields are available; **HubSpot** requires a connected integration. Call scripts also support the variable editor. Conditional Split uses a property selector rather than message-template syntax.

For example, with **AI messaging** off:

```text theme={null}
Hi {ft.flow.prospect_first_name},
I'd like to learn more about your work at {ft.flow.company_name}.
```

For Alex at Example Company, this renders as:

```text theme={null}
Hi Alex,
I'd like to learn more about your work at Example Company.
```

Use the inserted token exactly. Typing an arbitrary placeholder such as `{hyperscaler}` does not create a field or supply its value.

## Common Variables

The tables below are a practical reference for common personalization fields. Use the editor's variable menu for the current list available to your step. Field availability does not guarantee data coverage.

### Contact

| Field | Token | Example value |
| - | - | - |
| First Name | `{ft.flow.prospect_first_name}` | Alex |
| Last Name | `{ft.flow.prospect_last_name}` | Example |
| Email | `{ft.flow.prospect_email}` | [alex@example.com](mailto:alex@example.com) |
| Mobile Phone | `{ft.flow.prospect_phone}` | A saved or unlocked phone number |
| Role | `{ft.flow.prospect_role}` | VP of Engineering |
| Location | `{ft.flow.prospect_location}` | London |
| About | `{ft.flow.prospect_about}` | A description of the prospect |
| Background Summary | `{ft.flow.prospect_background_summary}` | A summary of the prospect's background |

These fields use saved Flow Enrollment values. Supported imports can supply basic identity fields; richer profile information depends on available enrichment. Configure [enrichment](https://docs.firsttouch.com/WebApp/Data-Enrichment/Overview.md) before the step that needs its results.

### Company

| Field | Token | Example value |
| - | - | - |
| Name | `{ft.flow.company_name}` | Example Company |
| Domain | `{ft.flow.company_domain}` | example.com |
| Industry | `{ft.flow.company_industry}` | Software |
| Size | `{ft.flow.company_size}` | An available company-size range |
| Location | `{ft.flow.company_location}` | London |
| Description | `{ft.flow.company_description}` | A description of the business |
| Technologies | `{ft.flow.company_technologies}` | Available technology-stack information |

Company fields use saved enrollment data and available company enrichment. **Technologies** can contain multiple technologies or be empty. It is not a dedicated cloud-provider field and does not preserve a custom value from your CSV.

### Sender

| Field | Token |
| - | - |
| First Name | `{sender_first_name}` |
| Last Name | `{sender_last_name}` |
| Company Name | `{sender_company_name}` |

Sender tokens use a different syntax from FirstTouch contact and company tokens. Insert them from the **Sender** group and preview with the intended sender context.

### Signals and Research

| Field | Token or selection | Prerequisite |
| - | - | - |
| Signal Context | `{ft.flow.signal_context}` | A Signal source. Website Visit Signal flows label this **Website visitor captured url(s)**. |
| Engagement Type | `{ft.flow.engagement_type}` | A Social Engagement Signal source. |
| Post Text | `{ft.flow.post_text}` | A Social Engagement Signal source. |
| Post URL | `{ft.flow.post_url}` | A Social Engagement Signal source. |
| Research output | Select the configured output from **Flow**. | An earlier advanced Research Agent on the same execution path. |

Post-related variables and Post Text Conditional Split properties require a Social Engagement Signal source. See [Social Engagement](https://docs.firsttouch.com/WebApp/Signals/Social-Engagement.md) for setup.

## Use a HubSpot Custom Property

HubSpot Contact and Company variables use these forms:

```text theme={null}
{hs.contact.property_internal_name}
{hs.company.property_internal_name}
```

The property must exist in your connected HubSpot account and be available in the variable menu. Use its internal name, not its display label, and choose the correct object.

For example, if a Contact property has the internal name `hyperscaler` and contains your verified value `AWS`:

```text theme={null}
Hi {ft.flow.prospect_first_name}, my notes show that you use {hs.contact.hyperscaler}.
```

1. Confirm the property is populated on the relevant HubSpot Contact.
2. Select that property from the editor's **HubSpot** group.
3. Preview using a contact whose matching HubSpot record contains the value.
4. Check a contact with no value and adjust the message or flow before publishing.

This example applies only when that property and record context exist. If the property belongs to a Company, select the Company property instead.

HubSpot variables are separate from FirstTouch variables saved on an enrollment. [Property mapping](https://docs.firsttouch.com/WebApp/HubSpot/Property-Mapping.md) controls FirstTouch-to-HubSpot writes; it does not automatically copy arbitrary HubSpot values into FirstTouch variables.

## Create a Custom Research Output

An advanced Research Agent can make named outputs available to later steps on the same execution path. Select the output from the editor's **Flow** group; its display label is not necessarily its token. Follow [Use a Named Output in Messaging](https://docs.firsttouch.com/WebApp/Flows/Agents/researcher.md#use-a-named-output-in-messaging) to configure a question and use its result.

## Can CSV Columns Become Custom Variables?

No. The standard importer maps a fixed set of fields; extra headers such as `hyperscaler` do not create variables. See [CSV fields and personalization](https://docs.firsttouch.com/WebApp/Audiences.md#csv-fields-and-personalization) for supported mappings and alternatives.

## Missing Values and Preview

A recognized token can still lack a value. Missing required data can cause validation or execution issues; do not assume every missing variable becomes an empty string.

Preview a contact with the field populated and one without it. Use the step's available fallback settings, change the wording, or route contacts through an appropriate Conditional Split. For source-specific checks, see [Flow Plan Variable Did Not Resolve](https://docs.firsttouch.com/WebApp/Data-Enrichment/Troubleshooting.md#flow-plan-variable-did-not-resolve).

## Next Steps

* [Messaging Guide](https://docs.firsttouch.com/WebApp/Flows/Master-Messaging-Guide.md): choose authored or AI-generated messaging and preview the result.
* [Personalize LinkedIn Connection Notes](https://docs.firsttouch.com/WebApp/Flows/personalized-linkedin-connection-notes.md): build a complete CSV-to-outreach flow.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.