# Deploying Inquiry Template versions with the Deployment Manager

> Use the Deployment Manager to choose which published Inquiry Template version serves new Inquiries in each environment, review deploy history, and roll back.

Source: https://help.withpersona.com/articles/3UXQOXp87ySib6VB1DFWCO/
Section: Inquiries > Introduction > Key Concepts

## Overview

The **Deployment Manager** controls which version of an Inquiry Template is used to create new Inquiries in each of your environments, such as Sandbox and Production. It separates two steps that used to happen together:

- **Publishing** saves a finished version of the template and locks it from further editing. Publishing does not change which version new Inquiries use.
- **Deploying** chooses which published version new Inquiries use in each environment. One deploy can cover several environments at once.

Because the two steps are separate, you can publish a version, deploy only to Sandbox to test, and then deploy it to Production later when you are ready. You can also see at a glance which version is live in each environment, who deployed it, and when.

The Deployment Manager also lets you remove a deployed version from an environment, so outdated versions stop being used for new Inquiries.

## Key terms

| Term               | What it means                                                                                                                                                                                        |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Published version  | A locked version of an Inquiry Template. Only published versions can be deployed.                                                                                                                    |
| Deploy             | Making a published version live in one or more environments.                                                                                                                                         |
| Deployed version   | The version an environment uses to create new Inquiries.                                                                                                                                             |
| Publish note       | A locked note, up to 255 characters, that describes what changed in a version. It appears throughout the Deployment Manager and in the **Deployed version** column of the list of Inquiry Templates. |
| Description        | A version's editable description. When you publish, it is set to the same text as the publish note. You can change it after publishing, and it appears in Version History.                           |
| Deployment history | The record of earlier deploys to an environment, including the version, who deployed it, and when.                                                                                                   |

## Where to find the Deployment Manager

You can open the Deployment Manager from three places in the Dashboard:

- **The list of Inquiry Templates.** Go to **Inquiries > Templates**, open the actions menu on a template's row, and select **Deployment Manager**. This works for any active template, whichever version you want to deploy. The **Deployed version** column in this list shows the version number each template is using in the environment you are currently viewing, followed by its publish note if it has one. Hover over it to see the full note, or click it to open that version.
- **The editor's overflow menu.** On the Flow or Screens view of the Inquiry Template editor, click **···** and select **Deployment Manager**.
- **The Deploy button.** In the editor's top bar, **Deploy** sits to the right of **Publish**. It is the quickest route right after you publish a version.

  ![TemplateDeploymentManager003](https://assets.withpersona.com/c_fill,q_auto,f_auto/help-center/TemplateDeploymentManager003.png)

The **Deploy** button is enabled only when you're viewing the latest published version of an Inquiry Template, no unpublished draft exists, and your role can edit and publish Inquiry Templates in the environment you're currently viewing.

When the button is visible but disabled, hover over it to see why. On a draft, its tooltip reads "Deployment is only available for published versions. Publish this version first to deploy it." If your role can edit but not publish Inquiry Templates in the environment you are viewing, its tooltip reads "You do not have permission to deploy. Contact your Admin to enable this feature."

If the **Deploy** button isn't available, you can still open the Deployment Manager from the actions menu on the template's row in **Inquiries > Templates**, or from **···** > **Deployment Manager** in the editor.

## Publish notes and descriptions

A version can carry two pieces of text, and they appear in different places.

**The publish note.** When you publish a version, the **Publish version?** dialog includes a **Description (optional)** field. Use it to describe what changed in this version, in up to 255 characters. The field starts empty each time you publish. This note is locked once you publish. The Deployment Manager shows it next to the version's publish date in the version selector, in each environment's **Deployed version**, and in **Deployment History**. The list of Inquiry Templates shows it after the version number in the **Deployed version** column. A clear publish note makes it much easier to choose the right version later.

**The description.** When you publish, the version's description is set to the same text as your publish note. If you leave the publish note empty, the description is left empty too. To add or change a version's description after publishing, open **Version History**, open the menu on the version, and select **Edit description**. Enter the new text in the **Edit Description** dialog and click **Confirm**. You need permission to edit Inquiry Templates. Permission to publish Inquiry Templates is not required. The description appears in Version History. Editing it does not change the publish note, which is what the Deployment Manager and the list of Inquiry Templates show.

## Deploy a version

1.  Open the Deployment Manager, either from the actions menu on the template's row in **Inquiries > Templates**, from **···** > **Deployment Manager** in the editor, or with the **Deploy** button right after you publish.
2.  Under **Create a new deploy**, use the version selector to choose the version to deploy. Versions are listed newest first, each with its publish date and time, its publish note if it has one, and its version number. If you opened the Deployment Manager from a published version in the editor, that version is already selected.

    ![TemplateDeploymentManager005](https://assets.withpersona.com/c_fill,q_auto,f_auto/help-center/TemplateDeploymentManager005.png)

3.  Under **Deploys**, check the box next to each environment you want to deploy the version to, or use the **Select all environments** checkbox in the header. The table shows each environment's current **Deployed version**, **Deployed by**, and **Deployed at** values, so you can see what will change before you deploy. Each deployed version is shown by its publish date and publish note. Hover over a value to see the full text.

    ![TemplateDeploymentManager006](https://assets.withpersona.com/c_fill,q_auto,f_auto/help-center/TemplateDeploymentManager006.png)

4.  Click **Deploy**. A "Deployment successful" message confirms that the environments you selected now use the new version.

An environment's checkbox is disabled when that environment is already using the version you selected. The **Deploy** button is enabled once there is at least one change to make, either a version with one or more environments selected or an environment marked for removal, and once you have confirmed any warning shown above the **Deploys** table.

💡

A common pattern is to deploy a new version to Sandbox first, run test Inquiries against it, and then open the Deployment Manager again to deploy the same version to Production. See [Testing your Inquiry Template](https://help.withpersona.com/articles/1az3sGqpcW5Zrne9I7lm49/) for ways to test a version before it reaches your users.

## See which version is deployed

There are three places to check which version an environment is using:

- **In the editor's top bar.** When the version you are viewing is deployed in your current environment, a **Deployed** label appears next to its status.
- **In Version History.** The version deployed in your current environment carries a **Deployed** label. Other published versions carry no label.
- **In the Deployment Manager.** The **Deploys** table lists every environment with its deployed version. If an environment has earlier deploys, expand its row to see its **Deployment History**: each earlier deploy, the version it deployed (shown by its publish date and publish note), who deployed it, and when. Some older entries show **Unknown** in place of who deployed them.

## How new Inquiries pick a version

When an Inquiry is created from an Inquiry Template or via a Create Inquiry step in a workflow, it uses the version that is deployed in its environment at that moment, and it stays on that version for its whole life. Deploying a different version later only affects Inquiries created after the deploy. Inquiries that already exist, including ones that end users have started but not finished, keep the version they were created with.

If your integration creates Inquiries from a specific Inquiry Template version ID (one that begins with `itmplv_`) rather than from the template ID, the Inquiry uses exactly that version, and deployments do not affect it.

Pinning to a version ID is the same guarantee described in [Inquiry Template Versions and Change Management](https://help.withpersona.com/articles/2Luxrdu3Cdg6pcecKBJxvs/). Changing which template version is deployed never updates which template is used for an Inquiry that already exists.

ℹ️

When you retrieve an Inquiry Template version through the API with a production API key that can read Inquiry Templates, the response includes two extra fields. `version-tag` is an object with the version's number (`name`), its publish note (`description`), and when the number was assigned (`created-at`). It is empty (`null`) if the version hasn't been given a number yet, for example a draft, or an older version that was published before version numbers were introduced and hasn't been deployed since. The version's editable description is returned separately, in the version's own `description` field. `deployments` lists the environments where that version is currently deployed, with one entry per environment. For more information, see [List all Inquiry Template Versions](https://docs.withpersona.com/api-reference/inquiry-templates/list-all-inquiry-template-versions) in the API reference.

## Roll back to an earlier version

![TemplateDeploymentManager010](https://assets.withpersona.com/c_fill,q_auto,f_auto/help-center/TemplateDeploymentManager010.png)

To roll back, deploy the earlier version again:

1.  Open the Deployment Manager for the Inquiry Template from the actions menu on its row in **Inquiries > Templates**.
2.  Under **Create a new deploy**, select the earlier version you want to return to. The publish notes and the **Deployment History** in each environment's row help you find the last version that worked as expected.
3.  Select the environments to roll back, and click **Deploy**.

New Inquiries use the earlier version from that point on. Rolling back does not delete or change the newer version, so you can deploy it again after you fix the issue. It also does not move any existing Inquiries to a different version.

## Remove a deployed version from an environment

To stop an environment from using a template entirely:

1.  Open the Deployment Manager for the Inquiry Template.
2.  Under **Create a new deploy**, select **No Deployment** at the top of the version selector.
3.  Under **Deploys**, check each environment you want to remove the deployed version from. Environments that have no deployed version can't be selected.
4.  Click **Deploy**.

Until you click **Deploy**, each selected row shows its current version followed by **No deployed version**; afterwards it shows **No deployed version**. If you change your mind before you click **Deploy**, uncheck the environment or select a version instead of **No Deployment**.

Removing the deployed version leaves the environment with no deployed version of the template at all. It does not fall back to the version that was deployed before. Your versions are not deleted: they stay published, you can deploy any of them again, and other environments are not affected.

Once no version is deployed in an environment, requests to create an Inquiry from the template ID in that environment fail with the error "Inquiry template is not deployed to this environment". In some cases the error reads "Inquiry template has no published version" instead. Both mean that no version is deployed in that environment. Inquiries created from a specific version ID are not affected.

☝️

Only remove a deployed version from an environment that should no longer create Inquiries from this template. If your integration still creates Inquiries from the template in that environment, deploy a version to it again.

## Permissions

![TemplateDeploymentManager001](https://assets.withpersona.com/c_fill,q_auto,f_auto/help-center/TemplateDeploymentManager001.png)

To deploy, your role needs permission to both edit and publish Inquiry Templates.

- If your role cannot edit Inquiry Templates, the **Deploy** button does not appear in the editor.
- If your role can edit but not publish Inquiry Templates, the **Deploy** button is disabled with the tooltip "You do not have permission to deploy. Contact your Admin to enable this feature."

Team members who can view Inquiry Templates can still open the Deployment Manager from the list of Inquiry Templates to review deployed versions and deployment history, but cannot deploy.

## Troubleshooting

**I can't find the Deploy button**

The **Deploy** button is hidden on older published versions, on the latest published version while a draft exists, on the Review Changes and Compare Changes pages, on archived templates, and for roles that cannot edit Inquiry Templates. Open the Deployment Manager from the actions menu on the template's row in **Inquiries > Templates** instead.

**The Deploy button is disabled**

Hover over the button to see why. The two most common reasons are that you are viewing a draft rather than a published version, and that your role can edit but not publish Inquiry Templates.

**No versions appear in the version selector**

The version selector only lists published versions. If the template has never been published, publish a version first, then open the Deployment Manager again. If a published version still doesn't appear in the list, [contact your Persona account team](https://app.withpersona.com/dashboard/contact-us?category=sales).

**The deploy failed because deployments changed**

If you see "Deployments changed since this dialog was opened. Please review and try again.", someone in your organization made another deploy while you had the Deployment Manager open. This happens after any deploy in your organization, including one to a different Inquiry Template. Close the Deployment Manager, open it again to load the latest deployments, and review the **Deploys** table before you deploy.

**I published a version but new Inquiries still use the old one**

Publishing and deploying are separate steps. After you publish, open the Deployment Manager and deploy the new version to each environment where you want new Inquiries to use it.

## Required updates to API and Webhooks

The Deployment Manager adds new API fields, endpoints, and a webhook event, and it changes what some existing ones mean. If you have existing API or webhook integrations related to Inquiry Templates, you will need to make some small updates before the Inquiry Template Deployment Manager goes live in early November 2026.

### What's new

- **New fields on Inquiry Template versions.** When retrieved with a production API key that can read Inquiry Templates, Inquiry Template version responses include a `version-tag` object (the version's number, publish note, and when the number was assigned) and a `deployments` field listing the environments where that version is currently deployed. For more information, see [List all Inquiry Template Versions](https://docs.withpersona.com/api-reference/inquiry-templates/list-all-inquiry-template-versions) in the API reference.
- **New deployments endpoints.** `GET /api/v1/deployments` lists your organization's deploys, newest first, and `GET /api/v1/deployments/{id}` retrieves a single deploy. Both require an API key with the `deployment.read` permission.
- **New `deployment.completed` webhook event.** This event is sent once per deploy, even when you deploy to multiple environments. The same event is delivered to every environment in your organization, not only the environments you deployed to, so if you have webhooks in more than one environment, each one receives it. The event lists each environment and Inquiry Template the deploy changed, and the version now deployed there.

### What's changing

- **Publishing no longer makes a version live.** A published version is only used for new Inquiries after it is deployed to an environment.
- **The `inquiry-template-version.published` webhook event no longer means a version is live.** It is still sent when a version is published, but the version is not used until it is deployed. Use `deployment.completed` to know when a version is live.
- **`latest-published-version` may not be the version in use.** The latest published version of an Inquiry Template can differ from the version deployed in each environment.
- **`live` means deployed somewhere.** A version's `live` field is `true` when that version is deployed in at least one environment.
- **Creating Inquiries from a template ID uses the deployed version.** If no version is deployed in that environment, the request fails with the error "Inquiry template is not deployed to this environment". The request does not fall back to the latest published version.
- **Creating Inquiries from a version ID is not affected.** Inquiries created from a specific version ID (one that begins with `itmplv_`) always use that version, whatever is deployed.
- **New environments start with nothing deployed.** Deploy a version to a new environment before you create Inquiries from a template ID in it.

### Update your integration

1.  Review any code, scripts, or automated processes on your own systems that call the Persona API or receive Persona webhooks, and find any that treat publishing an Inquiry Template version as making that version live. After you publish a new version of an Inquiry Template, deploy that version to each environment (for example, Sandbox or Production) where new Inquiries should use it, using the Deployment Manager in the Persona Dashboard. Deploying an Inquiry Template version can only be done in the Dashboard; the Persona API can't deploy versions.
2.  If you listen for the `inquiry-template-version.published` webhook event to learn when a version goes live, subscribe to the `deployment.completed` event instead.
3.  If your integration needs to read deploys through the API, grant the `deployment.read` permission to the API key it uses.
4.  Update any logic that reads `latest-published-version` or `live` to find the version in use. To check which version is deployed in each environment, read the `deployments` field on the version, or call `GET /api/v1/deployments`.
5.  Make sure each environment where you create Inquiries from a template ID has a version deployed in the Deployment Manager, including any new environments. Otherwise, those requests fail with one of the errors described above.

For more details on relevant API details and webhooks visit the following Developer Docs: [List All Deployments](https://docs.withpersona.com/api-reference/deployments/list-all-deployments), [Retrieve a Deployment](https://docs.withpersona.com/api-reference/deployments/retrieve-a-deployment), and [Webhook Deployment Completed](https://docs.withpersona.com/api-reference/webhooks/deployment-events/webhook-deployment-completed).

To learn more or request access, [let us know](https://app.withpersona.com/dashboard/contact-us?category=sales). We're happy to help.

_Last updated on October 9, 2026._