DocumentationAPI Reference
DocumentationAPI Reference

Migration to v4

[email protected] brings support for Inquiry Templates, which represent the next generation of Persona's inquiry flow. Inquiry Templates allow for greater flexibility in data collection by allowing custom UIs and collection fields.

Inquiry Templates support versioning and fully custom, component-based views. If you are an existing customer and are interested in using Inquiry Templates, please contact us or talk to your CSM.

Am I using Inquiry Templates or Templates?

If your template ID starts with tmpl_, then you are using the old Template.

If your template ID starts with itmpl_, then you are using the new Inquiry Template and must use [email protected] or later.

I am an existing customer using v3. Do I need to migrate?

You must use [email protected] if you are using Inquiry Templates. Inquiries created via Inquiry Templates will not work properly with [email protected].

Existing users who are not using Inquiry Templates will not need to migrate to [email protected], and [email protected] will continue working for the immediate future. However, we encourage using the latest version whenever possible to take advantage of improvements and bug fixes.

If you have a hard reliance on removed features, but want/need to use Inquiry Templates, please contact us or talk to your CSM for a migration path.

What do I need to do to migrate to v4?

The following table lists breaking changes in [email protected].



onLoad and onReady callbacks will no longer be passed error objects

Use the new callback onError.

onStart callback removed

Inquiry Templates no longer track Event.Start.

Templates can continue to listen for this event by watching for Event.Start in the onEvent callback; inquiryId will be a key on the second argument.

onComplete function signature changed to use keyword arguments

Change callback definitions to expect new arguments.

onFail callback removed

onComplete will be called for both passes and fails with a new status argument; check for failure with status === 'failed'.

onExit callback, client.exit() renamed to onCancel, client.cancel() (no behavior change)

onCancel, client.cancel()

accessToken renamed to sessionToken


note removed

Both Inquiry Templates and Templates support custom fields. Contact us to configure a custom fields as a replacement.

(Undocumented feature) themeId removed

Inquiry Templates now control their appearance independently of a separate Theme object.

Templates should specify a default theme in the Templates section of the Persona Dashboard.

Additionally, the following features and events are deprecated but will still continue to function in [email protected]: prefill, Event.CountrySelect, Event.VerificationChange, lockedAttributes (undocumented feature).

What's new in v4?




fields is intended to replace prefill, which has been deprecated. It behaves identically to prefill for Inquiry Templates and will prepopulate form flows in the UI, while also supporting custom fields.

Templates should continue to use prefill, as fields will not prepopulate form flows in the UI. However, it can be used to set values for custom fields that don't appear in the UI.


Allows locking inquiry creation to a specific template version. Only Inquiry Templates have versions.


Allows consistent error handling.

onCancel is passed a sessionToken

This makes it easier to resume an existing inquiry without needing to request a session token from the external API.