{"id":11543,"library":"persona","title":"Persona Inquiry JavaScript SDK","description":"The `persona` package offers the official JavaScript SDK for integrating Persona's identity verification Inquiry Flow into web applications. As of version 5.8.0, it provides a robust client library designed to embed and manage the entire inquiry process directly within the user's browser environment. Key functionalities include configuring inquiry templates, selecting runtime environments (e.g., sandbox, production), and handling critical lifecycle events through callbacks for completion, cancellation, and errors. The SDK abstracts away the complexities of direct API interaction, offering a streamlined integration experience for front-end developers. It ships with built-in TypeScript types, enhancing developer experience and type safety. Persona maintains an active development pace, regularly releasing updates and fixes, and explicitly recommends staying up-to-date. Its primary differentiation lies in being the official, fully supported client for Persona services, ensuring compatibility with the latest features and security standards.","status":"active","version":"5.8.0","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","typescript"],"install":[{"cmd":"npm install persona","lang":"bash","label":"npm"},{"cmd":"yarn add persona","lang":"bash","label":"yarn"},{"cmd":"pnpm add persona","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The Client class is a named export. CommonJS users should use destructuring from require().","wrong":"const Client = require('persona');","symbol":"Client","correct":"import { Client } from 'persona';"},{"note":"TypeScript type for the configuration object passed to the Client constructor.","symbol":"PersonaInquiryOptions","correct":"import type { PersonaInquiryOptions } from 'persona';"},{"note":"TypeScript type for the various event callback functions (onComplete, onCancel, onError, onEvent).","symbol":"ClientCallbacks","correct":"import type { ClientCallbacks } from 'persona';"}],"quickstart":{"code":"import { Client } from 'persona';\n\n// Initialize the Persona client for an embedded inquiry flow.\nconst client = new Client({\n  // Replace with your actual template ID, or use the provided demo template for testing.\n  templateId: 'itmpl_Ygs16MKTkA6obnF8C3Rb17dm',\n  // Use 'sandbox' for development and testing, 'production' for live applications.\n  environment: 'sandbox',\n  // Callback executed when the Persona flow is ready to be opened.\n  onReady: () => {\n    console.log('Persona client is ready, opening flow...');\n    client.open();\n  },\n  // Callback for when the inquiry process is successfully completed.\n  onComplete: ({ inquiryId, status, fields }) => {\n    console.log('Inquiry completed:', { inquiryId, status, fields });\n    // Handle post-completion logic, e.g., notify your backend, update UI.\n  },\n  // Callback for when the user cancels the inquiry flow.\n  onCancel: ({ inquiryId, sessionToken }) => {\n    console.log('Inquiry cancelled:', { inquiryId, sessionToken });\n    // Handle cancellation, e.g., log, return user to previous state.\n  },\n  // Callback for any errors encountered during the inquiry process.\n  onError: (error) => {\n    console.error('Persona inquiry error:', error);\n    // Implement robust error handling and user feedback.\n  },\n  // Optional: Set allowed events for the onEvent callback (e.g., ['step-transitioned', 'click']).\n  // eventsAllowlist: ['all']\n});\n\nconsole.log('Persona client initialized.');","lang":"typescript","description":"Demonstrates how to initialize the Persona `Client` for an embedded inquiry flow, configure its environment, and set up essential event callbacks for `onReady`, `onComplete`, `onCancel`, and `onError` to manage the user journey."},"warnings":[{"fix":"If using React, install `persona-react` and change `import { Inquiry } from 'persona'` to `import Inquiry from 'persona-react'`.","message":"Starting with `persona@5.0.0`, the `Inquiry` export (previously used for React integration) has been moved to a separate package, `persona-react`. Direct imports of `Inquiry` from `persona` will fail.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Update your `onComplete` callback function signature to accept destructuring `({ inquiryId, status, fields }) => { ... }` and migrate any logic from `onFail` into `onComplete` by checking the `status` parameter.","message":"The `onComplete` callback signature was significantly changed in `persona@5.0.0`. It now uses keyword arguments `{ inquiryId, status, fields }` instead of positional arguments. The `onFail` callback was removed entirely.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Replace `onStart` with the `onEvent` callback (listening for `Event.Start`), rename `onExit` to `onCancel` and `client.exit()` to `client.cancel()`, and update references of `accessToken` to `sessionToken` in callback arguments.","message":"The `onStart` callback was removed in `persona@5.0.0`. `onExit` and `client.exit()` were renamed to `onCancel` and `client.cancel()` respectively. The `accessToken` parameter was renamed to `sessionToken`.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Migrate to using the `fields` parameter for prefilling and attribute locking, and rely on template-level configuration for themes. Remove any usage of `InquiryAttributes` type.","message":"Features such as `prefill`, `lockedAttributes`, `themeId`, and the `InquiryAttributes` type export, which were deprecated in `persona@4.0.0`, have been completely removed in `persona@5.0.0`.","severity":"deprecated","affected_versions":">=5.0.0"},{"fix":"Uninstall `@types/persona` if it is present in your project. The types are included directly with the `persona` package.","message":"The package `persona` provides its own TypeScript type definitions. Installing `@types/persona` is unnecessary and the `@types` package is deprecated, which can lead to type conflicts or confusion.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"If using React, install `persona-react` (`npm install persona-react`) and update your import to `import Inquiry from 'persona-react'`.","cause":"Attempting to import `Inquiry` from 'persona' when it has been moved to 'persona-react' (since v5.0.0).","error":"ReferenceError: Inquiry is not defined"},{"fix":"Update your `onComplete` callback to use destructuring keyword arguments: `onComplete: ({ inquiryId, status, fields }) => { ... }`.","cause":"Using the old positional argument signature for the `onComplete` callback after upgrading to `persona@5.0.0` or later.","error":"TypeError: Cannot read properties of undefined (reading 'inquiryId')"},{"fix":"For CommonJS, use `const { Client } = require('persona');`. Ensure your build setup correctly handles ES Modules if you intend to use `import` statements.","cause":"Incorrectly importing `Client` in a CommonJS environment or mixing CommonJS `require()` syntax with ES Modules `import` syntax.","error":"TypeError: Client is not a constructor"},{"fix":"Ensure the `templateId` property is correctly provided in the `Client` constructor options, for example: `templateId: 'your_template_id'`.","cause":"The `templateId` option is a required parameter for initializing the Persona `Client`.","error":"Persona: Invalid configuration. Missing 'templateId'."}],"ecosystem":"npm"}