Persona Getting Started: Quickstart Guide (2026)

Getting started overview

Integrating Persona for identity verification involves several core steps, from account creation to making your first operational request. This guide outlines the process to help developers establish a functional integration quickly. The primary goal is to conduct an initial identity verification inquiry, which can range from basic document checks to more complex biometric analyses, depending on the configured workflow.

Persona's architecture separates the client-side interaction (where users submit their identity information) from the server-side processing and decisioning. Developers typically utilize Persona's SDKs or client-side integrations to collect user data, and then interact with Persona's API from their backend to manage inquiries and retrieve results. This approach helps maintain data security and compliance by keeping sensitive operations server-side.

Before initiating API calls, it is necessary to configure an 'Inquiry Template' within the Persona Dashboard. This template defines the specific steps and checks a user will undergo during verification, such as document uploads, selfie capture, or database lookups. The template also dictates the data points collected and processed, aligning with specific regulatory or business requirements.

Here is a summary of the initial setup process:

Create an account and get keys

To begin using Persona, the first step is to create a new account. Persona offers a free tier that supports up to 100 verifications per month, allowing developers to test and integrate without immediate cost. Account creation typically involves providing an email address and setting up an organization profile.

Once an account is established, access to the Persona Dashboard is granted. Within the Dashboard, API keys are generated. These keys are essential for authenticating requests to Persona's API. There are typically two types of keys required:

• API Key (Public Key): Used for client-side integrations, such as initializing SDKs for web or mobile applications. This key is typically considered safe to embed in client-side code because it only allows for the initiation of an inquiry, not its modification or review.
• Private Key (Secret Key): Used for server-side authentication when making direct API calls for managing inquiries, retrieving results, or configuring settings. Private keys should be stored securely and never exposed in client-side code, adhering to general API security best practices such as those outlined by Google Cloud's API key security guidelines.

To generate your keys:

1. Log in to your Persona Dashboard.
2. Navigate to the 'Developer' or 'API Keys' section.
3. Generate a new API Key pair.
4. Securely store your Private Key. It will only be shown once.

For detailed instructions on obtaining and managing API keys, refer to the Persona API Keys documentation.

Your first request

After setting up your account and obtaining API keys, the next step is to make a first request to verify the integration. This typically involves initializing an Inquiry using one of Persona's SDKs or a direct API call.

Using the Web SDK

The Web SDK allows for client-side initiation of an inquiry flow. This method is common for web applications where users interact directly with the verification process in their browser.

Example (JavaScript):

import Persona from 'persona';

const client = new Persona({ 
  templateId: 'YOUR_INQUIRY_TEMPLATE_ID', // Replaces 'inquiry-tmplt_xxxxxxx'
  environment: 'sandbox', // Or 'production'
  onComplete: ({ inquiryId, status, fields }) => {
    console.log(`Inquiry ${inquiryId} completed with status: ${status}`);
    // Send inquiryId to your backend for further processing and results retrieval
  },
  onError: (error) => {
    console.error('Persona error:', error);
  },
});

const openInquiry = () => {
  client.open();
};

Important considerations for the Web SDK:

• templateId: This is the ID of an Inquiry Template configured in your Persona Dashboard. It dictates the verification steps. Find your template ID in the Inquiry Templates section of the Dashboard.
• environment: Use 'sandbox' for testing and development. Switch to 'production' when deploying live.
• onComplete: This callback function is executed when the user completes the verification flow. The inquiryId returned here is crucial for fetching detailed results from your backend using your Private Key.

For more detailed information on integrating the Web SDK, refer to the Persona Web SDK reference.

Making a Server-Side API Call (Python Example)

For scenarios where direct server-to-server interaction is preferred, or to retrieve inquiry results, you use your Private Key to authenticate API calls. This example demonstrates creating a new inquiry programmatically.

Example (Python):

import persona

# Replace with your actual Private Key and Template ID
persona.api_key = 'YOUR_PRIVATE_KEY'

try:
    inquiry = persona.Inquiry.create(
        template_id='YOUR_INQUIRY_TEMPLATE_ID',
        reference_id='user_12345_session_abc',
        # Add optional fields like 'fields' or 'metadata'
    )
    print(f"Successfully created inquiry with ID: {inquiry.id}")
    print(f"Inquiry status: {inquiry.status}")
except persona.PersonaError as e:
    print(f"Error creating inquiry: {e}")

Key points for server-side API calls:

• Authentication: Ensure your persona.api_key is set to your Private Key.
• template_id: As with the SDK, this links the inquiry to a defined verification workflow.
• reference_id: An optional, unique identifier from your system to help track the inquiry.
• Error Handling: Implement proper error handling to manage API responses.

Further details on the Persona API and available endpoints can be found in the Persona API Reference.

Common next steps

Once a basic inquiry can be initiated, several common next steps enhance the integration:

1. Webhook Configuration: Persona communicates inquiry status changes and results via webhooks. Setting up a webhook endpoint in your application is critical for real-time updates and processing verification outcomes without polling the API. This typically involves creating an HTTP endpoint in your application that can receive POST requests from Persona. Ensure your webhook endpoint is secured—for instance, by validating webhook signatures using a secret, as recommended by services like Twilio.
2. Retrieving Inquiry Results: After an inquiry is completed, you will need to fetch the detailed results from Persona's API. This involves using the inquiryId (obtained from the SDK callback or API creation response) to query the Inquiry endpoint. The results include the verification status, extracted data, and any decisions made by Persona's system.
3. Customizing Inquiry Templates: Refine your Inquiry Templates in the Dashboard to match specific user flows and compliance requirements. This might involve adding more verification steps, customizing branding, or setting up different flows for various user segments.
4. Integrating with other SDKs: If developing for mobile, integrate the iOS SDK, Android SDK, or React Native SDK, which provide native user experiences.
5. Error Handling and Retries: Implement robust error handling for API calls and webhook processing. Strategize retry mechanisms for transient network issues or rate limits.

Troubleshooting the first call

When making your first Persona API call or initiating an SDK-based inquiry, common issues can arise. Here are typical troubleshooting steps:

• Invalid API Key or Private Key:
  • Symptom: Authentication errors (e.g., 401 Unauthorized or 403 Forbidden).
  • Solution: Double-check that you are using the correct API key (for client-side SDKs) and the correct Private Key (for server-side API calls). Ensure there are no leading/trailing spaces or typos. Confirm you are not using a client-side API key for server-side operations and vice-versa.
• Incorrect templateId:
  • Symptom: Inquiries fail to start or return an error indicating an unknown template.
  • Solution: Verify that the templateId passed to the SDK or API call matches an active Inquiry Template in your Persona Dashboard. Template IDs are case-sensitive.
• Environment Mismatch:
  • Symptom: Inquiries appear to succeed but data isn't visible, or unexpected behavior occurs.
  • Solution: Ensure your SDK's environment parameter (e.g., 'sandbox' or 'production') matches the environment of your API keys and the Dashboard you are viewing. Sandbox keys only work in the sandbox environment.
• Network or Firewall Issues:
  • Symptom: Requests time out or fail to connect to Persona's servers.
  • Solution: Check local network connectivity. If operating within a corporate network, ensure that firewall rules allow outbound connections to Persona's API endpoints. Consult your network administrator if necessary.
• Webhook Signature Verification Failure:
  • Symptom: Your webhook endpoint receives events but rejects them as invalid.
  • Solution: Accurately implement the webhook signature verification process using the secret provided in your Persona Dashboard. Ensure the payload, timestamp, and signature are processed correctly according to Persona's webhook security documentation.
• Missing Required Parameters:
  • Symptom: API calls return 400 Bad Request errors with messages indicating missing fields.
  • Solution: Review the Persona API reference for the specific endpoint you are calling and ensure all mandatory parameters are included in your request.

Persona's documentation on API status codes can provide further insights into specific error messages returned by the API.