DocumentationAPI Reference
Help CenterAPI ChangelogOpenAPI SpecStatus
Documentation
Help CenterAPI 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: "itmpl_Ygs16MKTkA6obnF8C3Rb17dm",
        referenceId: "<your reference ID for this user>",
        environment: "sandbox",
        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`);
        },
      });
    </script>
  </body>
</html>

import Persona from 'persona';

const client = new Persona.Client({
  templateId: "itmpl_Ygs16MKTkA6obnF8C3Rb17dm",
  referenceId: "<your reference ID for this user>",
  environment: "sandbox",
  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),
});

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.

Testing Locally

Your local HTML must be served rather than simply opening it.

For example:

python -m http.server
open http://localhost:8000/your_html_file.html

This is due to the origin for local files (file://) not being a valid origin for window.postMessage(), which the Persona flow uses to communicate with your code.

Callbacks

You can also use optional callbacks for advanced Event Handling.

<!-- 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>

<script>
  const client = new Persona.Client({
    templateId: "itmpl_Ygs16MKTkA6obnF8C3Rb17dm",
    environment: "sandbox",
    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)}`);
      }
    }
  });
</script>

❗️

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.

Updated almost 2 years ago

Next steps