DocumentationAPI Reference
API ChangelogOpenAPIStatus

Getting Started

Inquiry SDK version

The latest version of the SDK is:
Inquiry SDK latest

❗️

Looking for v3?

We will stop making updates to persona@3 on December 31, 2022. You will still be able to create inquiries, but no new features or fixes will be available. Please move to persona@4 for access to the latest product improvements- please see migration to v4 section or contact [email protected].

Embed Code Snippet

Creating inquiries through the Embedded integration can be easily achieved with a short code snippet. You'll only need your inquiry template ID which can be found in the Integration section of your Dashboard.

<!DOCTYPE html>
<html>
  <head>
    <!-- Replace "X.Y.Z" with the Inquiry SDK version you want to use. -->
    <script src="https://cdn.withpersona.com/dist/persona-vX.Y.Z.js"></script>

    <!-- charset and viewport meta tags are required! -->
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
  </head>

  <body>
    <!-- Initialize the Persona client in whichever way is appropriate for your application. -->
    <script>
      const client = new Persona.Client({
        templateId: "<your template ID starting with itmpl_>",
        referenceId: "<your reference ID for this user>",
        environmentId: "<your environment ID starting with env_>",
        onReady: () => client.open(),
        onCancel: ({ inquiryId, sessionToken }) => console.log('onCancel'),
        onError: (error) => console.log(error),
        onEvent: (name, metadata) => {
          if (name === 'start') {
            // Collect and save the inquiry ID for future use
            inquiryId = metadata["inquiryId"]
          }
        },
        onComplete: ({ inquiryId, status, fields }) => {
          // Inquiry completed. Optionally tell your server about it.
          console.log(`Sending finished inquiry ${inquiryId} to backend`);
          // Optionally, cleanup the client to avoid memory leaks.
          // client.destroy();
        },
      });
    </script>
  </body>
</html>
import Persona from 'persona';

const client = new Persona.Client({
  templateId: "<your template ID starting with itmpl_>",
  referenceId: "<your reference ID for this user>",
  environmentId: "<your environment ID starting with env_>",
  onReady: () => client.open(),
  onComplete: ({ inquiryId, status, fields }) => {
    // Inquiry completed. Optionally tell your server about it.
    console.log(`Sending finished inquiry ${inquiryId} to backend`);
  },
  onCancel: ({ inquiryId, sessionToken }) => console.log('onCancel'),
  onError: (error) => console.log(error),
});

❗️

Reinitializing vs. recreating the Persona client

If you plan on allowing the Persona flow to be opened multiple times in a window, we recommend reusing the same Persona client each time. Reusing the same iframe and listeners prevents memory leaks between clients and improves performance.

When using the persona NPM package, you must also ensure its peer dependencies are installed.

# npm
npm install persona react styled-components
# yarn
yarn add persona react styled-components

To permit the Persona iframe to render on your domain, see Security > Embedding the Persona iframe.

Callbacks

You can also use optional callbacks for advanced Event Handling.

const client = new Persona.Client({
  templateId: "<your template ID starting with itmpl_>",
  environmentId: "<your environment ID starting with env_>",
  onReady: () => client.open(),
  onEvent: (name, meta) => {
    switch (name) {
      case 'start':
        console.log(`Received event: start with inquiry ID ${meta.inquiryId}`);
        break;
      default:
        console.log(`Received event: ${name} with meta: ${JSON.stringify(meta)}`);
    }
  }
});

Methods

Use the client's Methods to show, hide, or cleanup the embedded flow widget.

const client = new Persona.Client({
	templateId: "<your template ID starting with itmpl_>",
  environmentId: "<your template ID starting with env_>",
  onComplete: ({ inquiryId, status, fields }) => {
	  // Inquiry completed. Optionally tell your server about it.
	  console.log(`Sending finished inquiry ${inquiryId} to backend`);
	  fetch(`/server-handler?inquiry-id=${inquiryId}`);
  }
});

function openClient() { client.open(); }
function cancelClient() { client.cancel(true); }