DocumentationAPI Reference
API ChangelogOpenAPI SpecStatus
API ChangelogOpenAPI SpecStatus

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 either reusing the same Persona client each time with client.open(), or ensuring that clients are cleaned up with client.destroy().

Repeated calls to new Persona.Client({ ... }) without cleaning up old clients can lead to elevated memory usage and degraded 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 environment 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); }

Updated 4 days ago

Next steps