DocumentationAPI Reference
DocumentationAPI Reference

Quickstart: Embedded Flow

Verifying individuals with the Embedded Flow can be easily achieved with a short code snippet. You'll only need your template ID which can be found in the Integration Section of your DashboardDashboard - A hub for organizations to review inquiries and manage their integration with Persona..

📘

Looking for v3?

View our migration guide for how to migrate to [email protected].

[email protected] will continue to work for the immediate future, but may not support new features. We recommend everyone upgrade to [email protected] if possible.

Embedding the flow

Persona can be integrated with the following code snippet. Remember to replace templateId with your organization's template ID.

Inquiry SDK latestInquiry SDK latest

<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(),
    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),
  });
</script>
import Persona from 'persona';

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

🚧

Testing the embedded flow locally in an HTML file

The Persona flow will not work if the above snippet is pasted into a local HTML file and the file is directly opened. You will need to serve your HTML file via a local server 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.

You can also use optional callbacks for advanced Event Handling.

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

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

That's it! You're done.

To retrieve information about inquiries, see /api/v1/inquiries/.

❗️

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 client means that the client can reuse the same iframe and listeners, preventing memory leaks between clients and improving performance.