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

# Trigger Context Reference

> Complete reference for all workflow trigger types and their available Liquid fields.

When a workflow runs, contextual data about what triggered it is available through the `trigger` object. This page documents every trigger type and the fields available for each.

## Using Trigger Context

Access trigger data in any workflow node that supports Liquid:

```liquid theme={null}
{% if trigger.type == "form_submission" %}
  Thanks for submitting {{ trigger.form_submission.form_name }}!
{% endif %}
```

The `trigger.type` field identifies what triggered the workflow, allowing you to create conditional content that adapts to different trigger sources.

***

## Trigger Types

| Trigger Type                  | Description                          |
| :---------------------------- | :----------------------------------- |
| `form_submission`             | A form was submitted                 |
| `page_visit`                  | A page was visited                   |
| `email_sent`                  | An email was sent                    |
| `email_delivered`             | An email was delivered               |
| `email_opened`                | An email was opened                  |
| `email_bounced`               | An email bounced                     |
| `email_link_clicked`          | A link in an email was clicked       |
| `contact_created`             | A new contact was created            |
| `contact_updated`             | A contact field value changed        |
| `company_updated`             | A company field value changed        |
| `added_to_audience`           | Contact was added to an audience     |
| `removed_from_audience`       | Contact was removed from an audience |
| `opportunity_created`         | An opportunity was created           |
| `opportunity_updated`         | An opportunity was updated           |
| `opportunity_role_added`      | Contact was added to an opportunity  |
| `opportunity_role_changed`    | Contact's opportunity role changed   |
| `object_created`              | A custom object was created          |
| `object_updated`              | A custom object was updated          |
| `object_relationship_changed` | A custom object relationship changed |
| `custom_event`                | A custom event was tracked           |
| `api`                         | Workflow was triggered via API       |

***

## Form Submissions

Triggered when a contact submits a form.

```liquid theme={null}
{% if trigger.type == "form_submission" %}
  Thanks for submitting {{ trigger.form_submission.form_name }}!
{% endif %}
```

### Available Fields

| Field                                  | Description                           |
| :------------------------------------- | :------------------------------------ |
| `trigger.form_submission.form_name`    | Name of the form                      |
| `trigger.form_submission.form_id`      | Unique identifier of the form         |
| `trigger.form_submission.page_url`     | URL where the form was submitted      |
| `trigger.form_submission.submitted_at` | Timestamp of submission (ISO 8601)    |
| `trigger.form_submission.utm_source`   | UTM source parameter (if available)   |
| `trigger.form_submission.utm_medium`   | UTM medium parameter (if available)   |
| `trigger.form_submission.utm_campaign` | UTM campaign parameter (if available) |
| `trigger.form_submission.utm_term`     | UTM term parameter (if available)     |
| `trigger.form_submission.utm_content`  | UTM content parameter (if available)  |

### Submitted Field Values

Access any field from the form submission through the `.fields` namespace:

```liquid theme={null}
{{ trigger.form_submission.fields.company_size }}
{{ trigger.form_submission.fields.use_case }}
{{ trigger.form_submission.fields.phone }}
```

<Info>
  Field values are nested under `.fields` to avoid conflicts between submission data and form metadata. For example, if a form has a field named "form\_name", it's accessible at `trigger.form_submission.fields.form_name` without overwriting the actual form name.
</Info>

<Tip>
  If a form field name contains spaces (e.g., "Country Of Origin"), you can't use dot notation. Use bracket syntax instead:

  ```liquid theme={null}
  {{ trigger.form_submission.fields["Country Of Origin"] }}
  ```
</Tip>

### Example

```liquid theme={null}
Hi {{ contact.first_name }},

Thanks for requesting a demo! 

{% if trigger.form_submission.fields.company_size == "Enterprise" %}
I'll have our enterprise team reach out within 24 hours to schedule a call.
{% else %}
I'll follow up shortly with some times to connect.
{% endif %}
```

***

## Page Visits

Triggered when a contact visits a tracked page.

```liquid theme={null}
{% if trigger.type == "page_visit" %}
  They visited {{ trigger.page_visit.page_url }}
{% endif %}
```

### Available Fields

| Field                             | Description                              |
| :-------------------------------- | :--------------------------------------- |
| `trigger.page_visit.page_url`     | URL of the visited page                  |
| `trigger.page_visit.referrer`     | Referring URL (if available)             |
| `trigger.page_visit.type`         | Visit type (direct, organic, paid, etc.) |
| `trigger.page_visit.utm_source`   | UTM source parameter (if available)      |
| `trigger.page_visit.utm_medium`   | UTM medium parameter (if available)      |
| `trigger.page_visit.utm_campaign` | UTM campaign parameter (if available)    |
| `trigger.page_visit.utm_term`     | UTM term parameter (if available)        |
| `trigger.page_visit.visited_at`   | Timestamp of visit (ISO 8601)            |

### Example

```liquid theme={null}
💰 Pricing Page Visit

{{ contact.first_name }} {{ contact.last_name }} from *{{ company.name }}* just viewed the pricing page.

*Contact:* {{ contact.email }}
*Title:* {{ contact.job_title | default: "Unknown" }}
{% if trigger.page_visit.utm_campaign %}
*Campaign:* {{ trigger.page_visit.utm_campaign }}
{% endif %}
```

***

## Email Events

All email event triggers share common email metadata through `trigger.email`. Each event type also has event-specific fields.

### Common Email Fields

These fields are available for all email triggers:

| Field                         | Description                              |
| :---------------------------- | :--------------------------------------- |
| `trigger.email.id`            | Email asset ID                           |
| `trigger.email.sent_email_id` | Unique identifier for this specific send |
| `trigger.email.name`          | Name of the email in Conversion          |
| `trigger.email.sent_at`       | Timestamp when email was sent (ISO 8601) |

### Email Sent

Triggered when an email is sent to a contact.

```liquid theme={null}
{% if trigger.type == "email_sent" %}
  {{ trigger.email.name }} was just sent
{% endif %}
```

### Email Delivered

Triggered when an email is successfully delivered.

| Field                        | Description                      |
| :--------------------------- | :------------------------------- |
| `trigger.email.delivered_at` | Timestamp of delivery (ISO 8601) |

### Email Opened

Triggered when a contact opens an email.

| Field                     | Description                  |
| :------------------------ | :--------------------------- |
| `trigger.email.opened_at` | Timestamp of open (ISO 8601) |

### Email Bounced

Triggered when an email bounces.

| Field                       | Description                    |
| :-------------------------- | :----------------------------- |
| `trigger.email.bounced_at`  | Timestamp of bounce (ISO 8601) |
| `trigger.email.bounce_type` | Type of bounce (hard, soft)    |

### Email Link Clicked

Triggered when a contact clicks a link in an email.

| Field                           | Description                   |
| :------------------------------ | :---------------------------- |
| `trigger.email.link.url`        | URL that was clicked          |
| `trigger.email.link.clicked_at` | Timestamp of click (ISO 8601) |

### Example

```liquid theme={null}
📧 Email Engagement

{{ contact.first_name }} {{ contact.last_name }} clicked a link in *{{ trigger.email.name }}*

*Company:* {{ company.name }}
*Link:* {{ trigger.email.link.url }}
```

***

## Contact Created

Triggered when a new contact is created in Conversion.

```liquid theme={null}
{% if trigger.type == "contact_created" %}
  New contact: {{ contact.email }}
{% endif %}
```

### Available Fields

| Field                        | Description                                                 |
| :--------------------------- | :---------------------------------------------------------- |
| `trigger.contact.created_at` | Timestamp of creation (ISO 8601)                            |
| `trigger.contact.source`     | How the contact was created (e.g., "form", "api", "import") |

### Example

```liquid theme={null}
🆕 New Lead

*Name:* {{ contact.first_name }} {{ contact.last_name }}
*Email:* {{ contact.email }}
*Company:* {{ company.name }}
*Title:* {{ contact.job_title | default: "Not provided" }}
*Source:* {{ trigger.contact.source }}
```

***

## Contact Updated

Triggered when a contact field value changes.

```liquid theme={null}
{% if trigger.type == "contact_updated" %}
  {{ contact.email }} was updated
{% endif %}
```

### Available Fields

| Field                               | Description                               |
| :---------------------------------- | :---------------------------------------- |
| `trigger.contact._changed.<field>`  | Boolean indicating if the field changed   |
| `trigger.contact._previous.<field>` | Previous value of the field before update |

### Example

```liquid theme={null}
{% if trigger.contact._changed.job_title %}
👔 Title Change Detected

*Contact:* {{ contact.first_name }} {{ contact.last_name }} ({{ contact.email }})
*Company:* {{ company.name }}
*Previous Title:* {{ trigger.contact._previous.job_title }}
*New Title:* {{ contact.job_title }}

{% if contact.job_title contains "Director" or contact.job_title contains "VP" or contact.job_title contains "Head" %}
🎉 This looks like a promotion! Consider reaching out to congratulate them.
{% endif %}
{% endif %}
```

***

## Company Updated

Triggered when a company field value changes.

```liquid theme={null}
{% if trigger.type == "company_updated" %}
  {{ company.name }} was updated
{% endif %}
```

### Available Fields

| Field                               | Description                               |
| :---------------------------------- | :---------------------------------------- |
| `trigger.company._changed.<field>`  | Boolean indicating if the field changed   |
| `trigger.company._previous.<field>` | Previous value of the field before update |

### Example

```liquid theme={null}
{% if trigger.company._changed.number_of_employees %}
📈 Company Update

*Company:* {{ company.name }}
*Previous Size:* {{ trigger.company._previous.number_of_employees }} employees
*New Size:* {{ company.number_of_employees }} employees
{% endif %}
```

***

## Audience Changes

Triggered when a contact is added to or removed from an audience.

### Added to Audience

```liquid theme={null}
{% if trigger.type == "added_to_audience" %}
  Added to {{ trigger.audience.name }}
{% endif %}
```

### Removed from Audience

```liquid theme={null}
{% if trigger.type == "removed_from_audience" %}
  Removed from {{ trigger.audience.name }}
{% endif %}
```

### Available Fields

| Field                   | Description                       |
| :---------------------- | :-------------------------------- |
| `trigger.audience.id`   | Unique identifier of the audience |
| `trigger.audience.name` | Name of the audience              |

### Example

```liquid theme={null}
🎯 New MQL

{{ contact.first_name }} {{ contact.last_name }} was added to *{{ trigger.audience.name }}*.

*Email:* {{ contact.email }}
*Company:* {{ company.name }}
*Title:* {{ contact.job_title | default: "Not provided" }}
```

***

## Opportunity Events

Triggered when opportunities are created or updated.

### Opportunity Created

Triggered when a new opportunity is created.

```liquid theme={null}
{% if trigger.type == "opportunity_created" %}
  New opportunity: {{ trigger.opportunity.name }}
{% endif %}
```

### Opportunity Updated

Triggered when an opportunity field value changes.

```liquid theme={null}
{% if trigger.type == "opportunity_updated" %}
  {{ trigger.opportunity.name }} has been updated
{% endif %}
```

### Available Fields

For all opportunity triggers:

| Field                         | Description                  |
| :---------------------------- | :--------------------------- |
| `trigger.opportunity.name`    | Name of the opportunity      |
| `trigger.opportunity.amount`  | Deal amount                  |
| `trigger.opportunity.stage`   | Current stage                |
| `trigger.opportunity.<field>` | Any field on the opportunity |

For `opportunity_updated`, access changed field information:

| Field                                   | Description                         |
| :-------------------------------------- | :---------------------------------- |
| `trigger.opportunity._changed.<field>`  | Boolean indicating if field changed |
| `trigger.opportunity._previous.<field>` | Previous value of the field         |

### Example

```liquid theme={null}
{% if trigger.opportunity._changed.stage %}
🚀 Deal Update

*Opportunity:* {{ trigger.opportunity.name }}
*Company:* {{ company.name }}
*Amount:* {{ trigger.opportunity.amount }}
*Previous Stage:* {{ trigger.opportunity._previous.stage }}
*New Stage:* {{ trigger.opportunity.stage }}

{% if trigger.opportunity.stage == "Closed Won" %}
🎉 Deal closed! Time to kick off onboarding.
{% endif %}
{% endif %}
```

***

## Opportunity Role Events

Triggered when a contact's relationship to an opportunity changes.

### Opportunity Role Added

Triggered when a contact is added to an opportunity (given an Opportunity Contact Role).

```liquid theme={null}
{% if trigger.type == "opportunity_role_added" %}
  {{ contact.first_name }} was added to {{ trigger.opportunity.name }}
{% endif %}
```

### Opportunity Role Changed

Triggered when a contact's role on an opportunity changes.

```liquid theme={null}
{% if trigger.type == "opportunity_role_changed" %}
  {{ contact.first_name }}'s role on {{ trigger.opportunity.name }} changed
{% endif %}
```

### Available Fields

| Field                                 | Description                                 |
| :------------------------------------ | :------------------------------------------ |
| `trigger.opportunity.name`            | Name of the opportunity                     |
| `trigger.opportunity.amount`          | Deal amount                                 |
| `trigger.opportunity.stage`           | Current stage                               |
| `trigger.opportunity_role.role`       | The contact's role (e.g., "Decision Maker") |
| `trigger.opportunity_role.is_primary` | Whether this is the primary contact         |

For `opportunity_role_changed`, access changed field information:

| Field                                        | Description                              |
| :------------------------------------------- | :--------------------------------------- |
| `trigger.opportunity_role._changed.<field>`  | Boolean indicating if role field changed |
| `trigger.opportunity_role._previous.<field>` | Previous value of the role field         |

### Example

```liquid theme={null}
👥 New Stakeholder

A new contact was added to *{{ trigger.opportunity.name }}*:

*Contact:* {{ contact.first_name }} {{ contact.last_name }}
*Title:* {{ contact.job_title | default: "Not provided" }}
*Role:* {{ trigger.opportunity_role.role | default: "Not specified" }}
{% if trigger.opportunity_role.is_primary %}
⭐ Primary contact
{% endif %}
```

***

## Custom Object Events

Triggered when custom objects are created, updated, or when relationships change.

### Object Created

Triggered when a new custom object is created.

```liquid theme={null}
{% if trigger.type == "object_created" %}
  New {{ trigger.object.type }}: {{ trigger.object.name }}
{% endif %}
```

### Object Updated

Triggered when a custom object field value changes.

```liquid theme={null}
{% if trigger.type == "object_updated" %}
  {{ trigger.object.name }} has been updated
{% endif %}
```

### Object Relationship Changed

Triggered when the relationship between a contact and custom object changes.

```liquid theme={null}
{% if trigger.type == "object_relationship_changed" %}
  Relationship to {{ trigger.object.name }} changed
{% endif %}
```

### Available Fields

For all custom object triggers:

| Field                                  | Description                                              |
| :------------------------------------- | :------------------------------------------------------- |
| `trigger.object.id`                    | Unique identifier of the triggering object               |
| `trigger.object.type`                  | The custom object type (e.g., "product", "subscription") |
| `trigger.object.<field>`               | Any field on the triggering custom object                |
| `trigger.object._relationship.<field>` | Relationship fields between contact and object           |

For `object_updated`, access changed field information:

| Field                              | Description                         |
| :--------------------------------- | :---------------------------------- |
| `trigger.object._changed.<field>`  | Boolean indicating if field changed |
| `trigger.object._previous.<field>` | Previous value of the field         |

For `object_relationship_changed`, access relationship change details:

| Field                                            | Description                                      |
| :----------------------------------------------- | :----------------------------------------------- |
| `trigger.object._relationship._changed.<field>`  | Boolean indicating if relationship field changed |
| `trigger.object._relationship._previous.<field>` | Previous value of the relationship field         |

### Example

```liquid theme={null}
{% if trigger.object.type == "subscription" %}
  {% if trigger.object._changed.status %}
🔔 Subscription Update

*Contact:* {{ contact.first_name }} {{ contact.last_name }}
*Company:* {{ company.name }}
*Plan:* {{ trigger.object.plan_name }}
*Previous Status:* {{ trigger.object._previous.status }}
*New Status:* {{ trigger.object.status }}
  {% endif %}
{% endif %}
```

***

## Custom Events

Triggered when a custom event is tracked for a contact.

```liquid theme={null}
{% if trigger.type == "custom_event" %}
  Event: {{ trigger.custom_event.name }}
{% endif %}
```

### Available Fields

| Field                            | Description                        |
| :------------------------------- | :--------------------------------- |
| `trigger.custom_event.name`      | The event name                     |
| `trigger.custom_event.type`      | The event type                     |
| `trigger.custom_event.id`        | Conversion's assigned unique ID    |
| `trigger.custom_event.timestamp` | When the event occurred (ISO 8601) |

### Custom Properties

Access any custom property sent with the event through the `.data` namespace:

```liquid theme={null}
{{ trigger.custom_event.data.feature_name }}
{{ trigger.custom_event.data.plan_name }}
{{ trigger.custom_event.data.usage_count }}
```

<Info>
  Custom properties are nested under `.data` to avoid conflicts between event data and event metadata.
</Info>

### Example

```liquid theme={null}
{% if trigger.custom_event.name == "feature_activated" %}
✨ Feature Adoption

{{ contact.first_name }} {{ contact.last_name }} from *{{ company.name }}* activated *{{ trigger.custom_event.data.feature_name }}*.
{% endif %}
```

***

## API Triggers

Triggered when a workflow is started via the API.

```liquid theme={null}
{% if trigger.type == "api" %}
  Processing {{ trigger.api.name }}
{% endif %}
```

### Available Fields

| Field                   | Description                                     |
| :---------------------- | :---------------------------------------------- |
| `trigger.api.name`      | The name provided in the API request (required) |
| `trigger.api.timestamp` | When the request was received (ISO 8601)        |

### Request Payload

Access any custom field sent in the API request through the `.data` namespace:

```liquid theme={null}
{{ trigger.api.data.campaign_id }}
{{ trigger.api.data.source_system }}
{{ trigger.api.data.assigned_owner }}
```

<Info>
  Request payload fields are nested under `.data` to avoid conflicts with request metadata, following the same pattern as form submissions and custom events.
</Info>

### Example

```liquid theme={null}
Hi {{ contact.first_name }},

You're registered for *{{ trigger.api.data.webinar_title }}*!

*Date:* {{ trigger.api.data.webinar_date }}
*Time:* {{ trigger.api.data.webinar_time }}

We'll send a reminder the day before.
```

***

## Handling Multiple Trigger Types

Use `trigger.type` with `case` statements to handle multiple trigger types in a single workflow:

```liquid theme={null}
{% case trigger.type %}
  {% when "form_submission" %}
New form submission: {{ trigger.form_submission.form_name }}
    
  {% when "email_link_clicked" %}
{{ contact.first_name }} clicked a link in {{ trigger.email.name }}
    
  {% when "opportunity_updated" %}
    {% if trigger.opportunity._changed.stage %}
{{ trigger.opportunity.name }} moved to {{ trigger.opportunity.stage }}
    {% endif %}
    
  {% else %}
Activity from {{ contact.first_name }} {{ contact.last_name }}
{% endcase %}
```

***

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="What happens if I reference a trigger field that doesn't exist for this trigger type?">
    If your Liquid syntax is valid but references a trigger field that doesn't apply to the current trigger type (e.g., using `trigger.form_submission.form_name` when the workflow was triggered by a page visit), the expression evaluates to an empty string. Use `trigger.type` checks to ensure you're accessing the right fields.
  </Accordion>

  <Accordion title="Why are form fields under .fields and event properties under .data?">
    These namespaces prevent conflicts between user-provided data and system metadata. For example, if a form has a field named "form\_name", it won't overwrite `trigger.form_submission.form_name`—it's safely accessible at `trigger.form_submission.fields.form_name`.
  </Accordion>

  <Accordion title="How do I check if a specific field changed in an update trigger?">
    Use the `_changed` namespace. For example, `trigger.contact._changed.job_title` returns `true` if the job title field changed. You can then access the previous value with `trigger.contact._previous.job_title`.
  </Accordion>

  <Accordion title="Are timestamps in a specific timezone?">
    All timestamps are returned in UTC in ISO 8601 format. Use the `date` filter to format them for display.
  </Accordion>
</AccordionGroup>