Claude Code skill pack for Persona (18 skills)

18 Skills

MIT License

Free Pricing

Installation

Open Claude Code and run this command:

/plugin install persona-pack@claude-code-plugins-plus

Use --global to install for all projects, or --project for current project only.

What It Does

> Claude Code skill pack for Persona identity verification — KYC, inquiry flows, government ID verification, and webhook-driven verification pipelines (18 skills)

Skills (18)

persona-ci-integration SKILL.md View full skill →

'CI/CD pipeline for Persona integrations with sandbox API testing.

ReadWriteEditBash(gh:*)

persona-common-errors SKILL.md View full skill →

'Fix top Persona API errors: 401, 422, webhook signature failures, inquiry.

ReadGrepBash(curl:*)

persona common errors | sed 's/\b\(.\)/\u\1/g'

Overview

401 invalid key, 422 invalid template, webhook HMAC mismatch, inquiry already completed, rate limit 429.

Prerequisites

Completed persona-install-auth setup
Valid Persona API key (sandbox or production)

Instructions

Error 1: 401 Unauthorized


{"errors":[{"status":"401","title":"Not Authorized"}]}

Fix: Verify API key starts with personasandbox or personaproduction. Check Authorization: Bearer header format.

Error 2: 422 Invalid Inquiry Template


{"errors":[{"status":"422","title":"Invalid inquiry-template-id"}]}

Fix: Verify template ID format is itmpl_*. Templates are environment-specific (sandbox templates only work with sandbox keys).

Error 3: Webhook Signature Mismatch


HMAC verification failed — expected abc123, got def456

Fix: Ensure you're using the raw request body (not parsed JSON) for HMAC computation. Use express.raw() middleware.

Error 4: 429 Rate Limited


{"errors":[{"status":"429","title":"Rate limit exceeded"}]}

Fix: Implement exponential backoff. Check Retry-After header. See persona-rate-limits.

Error 5: Inquiry Already Completed


{"errors":[{"status":"409","title":"Inquiry is already in a terminal state"}]}

Fix: Check inquiry status before attempting operations. Use the resume endpoint only for created or pending inquiries.

Error 6: 404 Inquiry Not Found


{"errors":[{"status":"404","title":"Not Found"}]}

Fix: Verify inquiry ID format is inq_*. Sandbox inquiries are not accessible with production keys.

Output

Error identified from API response
Targeted fix applied
Verified resolution

Error Handling

persona-core-workflow-a SKILL.md View full skill →

'Build a complete KYC verification flow with Persona inquiries and embedded.

ReadWriteEditBash(npm:*)Grep

Persona Core Workflow A — KYC Inquiry Flow

Overview

Build a complete KYC onboarding flow: create an inquiry from a template, embed the Persona verification UI in your web app, handle completion callbacks, and store verification results.

Prerequisites

Completed persona-install-auth setup
Inquiry Template configured in Persona Dashboard
Web application with a frontend (React, HTML, etc.)

Instructions

Step 1: Backend — Create Inquiry Endpoint


// server.ts — Express endpoint to create inquiries
import express from 'express';
import axios from 'axios';

const app = express();
app.use(express.json());

const persona = axios.create({
  baseURL: 'https://withpersona.com/api/v1',
  headers: {
    'Authorization': `Bearer ${process.env.PERSONA_API_KEY}`,
    'Persona-Version': '2023-01-05',
  },
});

app.post('/api/verify', async (req, res) => {
  const { userId, email } = req.body;

  const { data } = await persona.post('/inquiries', {
    data: {
      attributes: {
        'inquiry-template-id': process.env.PERSONA_TEMPLATE_ID,
        'reference-id': userId,
        'fields': {
          'email-address': { type: 'string', value: email },
        },
      },
    },
  });

  res.json({
    inquiryId: data.data.id,
    sessionToken: data.data.attributes['session-token'],
  });
});

Step 2: Frontend — Embed Persona Flow


<!-- Include Persona's JavaScript SDK -->
<script src="https://cdn.withpersona.com/dist/persona-v5.0.0.js"></script>

<button id="verify-btn">Verify Identity</button>

<script>
document.getElementById('verify-btn').addEventListener('click', async () => {
  // Get inquiry from your backend
  const resp = await fetch('/api/verify', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ userId: 'user-123', email: 'alice@example.com' }),
  });
  const { inquiryId, sessionToken } = await resp.json();

  // Launch Persona embedded flow
  const client = new Persona.Client({
    inquiryId,
    sessionToken,
    onComplete: ({ inquiryId, status }) => {
      console.log(`Verification ${status} for inquiry ${inquiryId}`);
      // Notify your backend
      fetch(`/api/verify/${inquiryId}/complete`, { method: 'POST' });
    },
    onCancel: ({ inquiryId }) => {
      console.log('User cancelled verification');
    },
    onError: (error) => {
      console.error('Persona error:', error);
    },
  });

  client.open();
});
</script>

Step 3: Backend — Handle Completion


app.post('/api/v


                
                  
                  
                  persona-core-workflow-b
                  SKILL.md
                  View full skill →
                
                
                  'Work with Persona verification types: government ID, selfie, database.
                  
                      ReadWriteEditBash(curl:*)Grep
                    
                
                
                  Persona Core Workflow B — Verification Checks
Overview
Work with Persona's verification types: government ID (passport, driver's license), selfie liveness detection, and database checks (SSN, watchlist). Covers retrieving verification details, interpreting check results, and handling edge cases.
Prerequisites

Completed persona-core-workflow-a (inquiry flow)
Inquiry Template with verification checks configured

Instructions
Step 1: List Verifications for an Inquiry

import os, requests

HEADERS = {
    "Authorization": f"Bearer {os.environ['PERSONA_API_KEY']}",
    "Persona-Version": "2023-01-05",
}
BASE = "https://withpersona.com/api/v1"

# Get all verifications for an inquiry
resp = requests.get(f"{BASE}/inquiries/inq_XXXXX", headers=HEADERS)
resp.raise_for_status()
inquiry = resp.json()["data"]
verifications = inquiry["relationships"]["verifications"]["data"]

for v in verifications:
    v_resp = requests.get(f"{BASE}/verifications/{v['id']}", headers=HEADERS)
    v_data = v_resp.json()["data"]["attributes"]
    print(f"  Type: {v['type']}")
    print(f"  Status: {v_data['status']}")  # passed, failed, requires_retry
    print(f"  Checks: {v_data.get('checks', [])}")

Step 2: Government ID Verification Results

# Government ID verification includes extracted data
def get_gov_id_details(verification_id: str) -> dict:
    resp = requests.get(f"{BASE}/verifications/{verification_id}", headers=HEADERS)
    resp.raise_for_status()
    attrs = resp.json()["data"]["attributes"]

    return {
        "status": attrs["status"],
        "first_name": attrs.get("name-first"),
        "last_name": attrs.get("name-last"),
        "dob": attrs.get("birthdate"),
        "id_number": attrs.get("identification-number"),
        "id_class": attrs.get("id-class"),          # dl, pp, id
        "country": attrs.get("country-code"),
        "expiry": attrs.get("expiration-date"),
        "checks": {
            check["name"]: check["status"]
            for check in attrs.get("checks", [])
        },
    }

# Example checks: id_barcode_detection, id_integrity, id_selfie_comparison

Step 3: Selfie Liveness Check

def get_selfie_result(verification_id: str) -> dict:
    resp = requests.get(f"{BASE}/verifications/{verification_id}", headers=HEADERS)
    attrs = resp.json()["data"]["attributes&


                
                  
                  
                  persona-cost-tuning
                  SKILL.md
                  View full skill →
                
                
                  'Optimize Persona verification costs with template selection and caching.
                  
                      ReadGrep
                    
                
                
                  persona cost tuning | sed 's/\b\(.\)/\u\1/g'
Overview
Choose appropriate verification types, cache results, avoid duplicate inquiries.
Prerequisites

Completed persona-install-auth setup
Valid Persona API key (sandbox or production)

Instructions
Step 1: Implementation

import os, requests

HEADERS = {
    "Authorization": f"Bearer {os.environ['PERSONA_API_KEY']}",
    "Persona-Version": "2023-01-05",
}
BASE = "https://withpersona.com/api/v1"

# Optimize Persona verification costs with template selection and caching
resp = requests.get(f"{BASE}/inquiries?page[size]=10", headers=HEADERS)
resp.raise_for_status()
inquiries = resp.json()["data"]
for inq in inquiries:
    print(f"  {inq['id']}: {inq['attributes']['status']}")

Output

Choose appropriate verification types, cache results, avoid duplicate inquiries.

Error Handling

HTTP Code	Meaning	Retryable
400	Bad request	No
401	Invalid API key	No — fix key
404	Resource not found	No
409	Conflict (terminal state)	No
422	Validation error	No — fix request
429	Rate limited	Yes
500+

Error	Cause	Solution
401 Unauthorized	Invalid API key	Check PERSONAAPIKEY
429 Rate Limited	Too many requests	Implement backoff
404 Not Found	Wrong resource ID	Verify ID format


Resources

Persona API Reference
Persona Documentation

Next Steps
See related Persona skills for more workflows.


                
                  
                  
                  persona-debug-bundle
                  SKILL.md
                  View full skill →
                
                
                  'Collect Persona diagnostic info: inquiry IDs, API responses, webhook.
                  
                      ReadBash(grep:*)Bash(curl:*)Bash(tar:*)Grep
                    
                
                
                  persona debug bundle | sed 's/\b\(.\)/\u\1/g'
Overview
Gather inquiry state, verification results, webhook delivery logs, API connectivity test.
Prerequisites

Completed persona-install-auth setup
Valid Persona API key (sandbox or production)

Instructions
Step 1: Implementation

import os, requests

HEADERS = {
    "Authorization": f"Bearer {os.environ['PERSONA_API_KEY']}",
    "Persona-Version": "2023-01-05",
}
BASE = "https://withpersona.com/api/v1"

# Collect Persona diagnostic info: inquiry IDs, API responses, webhook logs
resp = requests.get(f"{BASE}/inquiries?page[size]=10", headers=HEADERS)
resp.raise_for_status()
inquiries = resp.json()["data"]
for inq in inquiries:
    print(f"  {inq['id']}: {inq['attributes']['status']}")

Output

Gather inquiry state, verification results, webhook delivery logs, API connectivity test.

Error Handling

Error
Cause
Solution


401 Unauthorized
Invalid API key
Check PERSONAAPIKEY


429 Rate Limited
Too many requests
Implement backoff


404 Not Found
Wrong resource ID
Verify ID format


Resources

Persona API Reference
Persona Documentation

Next Steps
See related Persona skills for more workflows.


                
                  
                  
                  persona-deploy-integration
                  SKILL.md
                  View full skill →
                
                
                  'Deploy Persona verification service to cloud platforms.
                  
                      ReadWriteEditBash(gcloud:*)
                    
                
                
                  persona deploy integration | sed 's/\b\(.\)/\u\1/g'
Overview
Dockerfile, Cloud Run deployment, secrets management, health checks.
Prerequisites

Completed persona-install-auth setup
Valid Persona API key (sandbox or production)

Instructions
Step 1: Implementation

import os, requests

HEADERS = {
    "Authorization": f"Bearer {os.environ['PERSONA_API_KEY']}",
    "Persona-Version": "2023-01-05",
}
BASE = "https://withpersona.com/api/v1"

# Deploy Persona verification service to cloud platforms
resp = requests.get(f"{BASE}/inquiries?page[size]=10", headers=HEADERS)
resp.raise_for_status()
inquiries = resp.json()["data"]
for inq in inquiries:
    print(f"  {inq['id']}: {inq['attributes']['status']}")

Output

Dockerfile, Cloud Run deployment, secrets management, health checks.

Error Handling

Error
Cause
Solution


401 Unauthorized
Invalid API key
Check PERSONAAPIKEY


429 Rate Limited
Too many requests
Implement backoff


404 Not Found
Wrong resource ID
Verify ID format


Resources

Persona API Reference
Persona Documentation

Next Steps
See related Persona skills for more workflows.


                
                  
                  
                  persona-hello-world
                  SKILL.md
                  View full skill →
                
                
                  'Create your first Persona identity verification inquiry and check its.
                  
                      ReadWriteEditBash(curl:*)
                    
                
                
                  Persona Hello World
Overview
Create a Persona inquiry, generate an embed URL for the verification flow, and poll for the inquiry status. Uses the real Persona REST API with sandbox credentials.
Prerequisites

Completed persona-install-auth setup
An Inquiry Template ID from the Persona Dashboard (format: itmpl_*)

Instructions
Step 1: Create an Inquiry

import os, requests

API_KEY = os.environ["PERSONA_API_KEY"]
BASE = "https://withpersona.com/api/v1"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Persona-Version": "2023-01-05",
    "Content-Type": "application/json",
}

# Create a new inquiry from a template
resp = requests.post(f"{BASE}/inquiries", headers=HEADERS, json={
    "data": {
        "attributes": {
            "inquiry-template-id": "itmpl_YOUR_TEMPLATE_ID",
            "reference-id": "user-12345",  # Your internal user ID
        }
    }
})
resp.raise_for_status()
inquiry = resp.json()["data"]
inquiry_id = inquiry["id"]
status = inquiry["attributes"]["status"]
print(f"Inquiry created: {inquiry_id} (status: {status})")

Step 2: Get the Verification URL

# The inquiry includes a session token for the embedded flow
session_token = inquiry["attributes"].get("session-token")
if session_token:
    # Option A: Hosted flow (redirect user to Persona)
    hosted_url = f"https://withpersona.com/verify?inquiry-id={inquiry_id}&session-token={session_token}"
    print(f"Send user to: {hosted_url}")

    # Option B: Embedded flow (JavaScript SDK in your page)
    print(f"Embed with: Persona.Client({{ templateId: 'itmpl_...', inquiryId: '{inquiry_id}' }})")

Step 3: Poll for Completion

import time

for _ in range(30):  # Poll for up to 5 minutes
    resp = requests.get(f"{BASE}/inquiries/{inquiry_id}", headers=HEADERS)
    resp.raise_for_status()
    status = resp.json()["data"]["attributes"]["status"]
    print(f"  Status: {status}")

    if status in ("completed", "approved", "declined"):
        break
    time.sleep(10)

# Get verification details
if status == "completed":
    verifications = resp.json()["data"]["relationships"]["verifications"]["data"]
    for v in verifications:
        print(f"  Verification: {v['type']} — {v['id']}")

Step 4: Retrieve Verification Results

# Get detailed verification result
verification_id =


                
                  
                  
                  persona-install-auth
                  SKILL.md
                  View full skill →
                
                
                  'Configure Persona API authentication with sandbox and production API.
                  
                      ReadWriteEditBash(npm:*)Bash(pip:*)Grep
                    
                
                
                  Persona Install & Auth
Overview
Set up Persona API authentication. Persona uses Bearer token auth with environment-prefixed API keys (personasandbox for testing, personaproduction for live). No SDK required -- direct REST API calls with any HTTP client.
Prerequisites

Persona account at withpersona.com
At least one Inquiry Template configured in the Persona Dashboard
Node.js 18+ or Python 3.9+

Instructions
Step 1: Get API Keys

1. Log into dashboard.withpersona.com
2. Go to Settings > API Keys
3. Copy your sandbox key (starts with persona_sandbox_)
4. For production: copy production key (starts with persona_production_)

Step 2: Configure Environment

# .env — never commit
PERSONA_API_KEY=persona_sandbox_xxxxxxxxxxxxxxxxxxxxxxxx
PERSONA_API_VERSION=2023-01-05

# .gitignore
echo '.env' >> .gitignore

Step 3: Install HTTP Client

set -euo pipefail
# Node.js
npm install axios dotenv

# Python
pip install requests python-dotenv

Step 4: Verify Connection (Node.js)

import axios from 'axios';

const persona = axios.create({
  baseURL: 'https://withpersona.com/api/v1',
  headers: {
    'Authorization': `Bearer ${process.env.PERSONA_API_KEY}`,
    'Persona-Version': process.env.PERSONA_API_VERSION || '2023-01-05',
    'Content-Type': 'application/json',
  },
});

async function verify() {
  const { data } = await persona.get('/inquiries?page[size]=1');
  console.log(`Connected! Found ${data.data.length} inquiry(ies).`);
}
verify().catch(console.error);

Step 5: Verify Connection (Python)

import os, requests
from dotenv import load_dotenv

load_dotenv()

headers = {
    "Authorization": f"Bearer {os.environ['PERSONA_API_KEY']}",
    "Persona-Version": os.environ.get("PERSONA_API_VERSION", "2023-01-05"),
}

resp = requests.get("https://withpersona.com/api/v1/inquiries?page[size]=1", headers=headers)
resp.raise_for_status()
print(f"Connected! Status: {resp.status_code}")

Output

API key configured and verified
HTTP client set up with correct headers
Successful test call to Persona API

Error Handling

Error
Cause
Solution


401 Unauthorized
Invalid or expired API key
Verify key in Dashboard > Settings > API Keys


403 Forbidden
Key doesn't match environment
Use persona
                
              
                
                  
                  
                  persona-local-dev-loop
                  SKILL.md
                  View full skill →
                
                
                  'Local development with Persona sandbox, ngrok for webhooks, mock verifications.
                  
                      ReadWriteEditBash(npm:*)Grep
                    
                
                
                  persona local dev loop | sed 's/\b\(.\)/\u\1/g'
Overview
Sandbox testing with test inquiry templates, ngrok tunnel for webhook testing, mock API responses for CI.
Prerequisites

Completed persona-install-auth setup
Valid Persona API key (sandbox or production)

Instructions
Step 1: Set Up Sandbox Environment

set -euo pipefail
# Use sandbox API key for all development
echo 'PERSONA_API_KEY=persona_sandbox_xxxxxxxx' > .env
echo 'PERSONA_API_VERSION=2023-01-05' >> .env

Step 2: Expose Local Webhooks with ngrok

# Terminal 1: Start your webhook server
npm run dev  # localhost:3000

# Terminal 2: Tunnel with ngrok
ngrok http 3000
# Copy the HTTPS URL and configure in Persona Dashboard > Webhooks

Step 3: Create Test Inquiries

import os, requests

HEADERS = {
    "Authorization": f"Bearer {os.environ['PERSONA_API_KEY']}",
    "Persona-Version": "2023-01-05",
}

# Create inquiry with sandbox template
resp = requests.post("https://withpersona.com/api/v1/inquiries", headers=HEADERS, json={
    "data": {
        "attributes": {
            "inquiry-template-id": "itmpl_YOUR_SANDBOX_TEMPLATE",
            "reference-id": f"test-{int(time.time())}",
        }
    }
})
print(f"Test inquiry: {resp.json()['data']['id']}")

Step 4: Mock API Responses for CI

import { vi } from 'vitest';

const mockPersonaApi = {
  createInquiry: vi.fn().mockResolvedValue({
    data: { id: 'inq_test_123', attributes: { status: 'created', 'session-token': 'tok_xxx' } },
  }),
  getInquiry: vi.fn().mockResolvedValue({
    data: { id: 'inq_test_123', attributes: { status: 'completed' } },
  }),
};

Output

Sandbox environment configured for development
ngrok tunnel for webhook testing
Test inquiry creation workflow
Mock API responses for unit tests

Error Handling

Error
Cause
Solution


Webhook not received
ngrok URL not configured
Update webhook URL in Dashboard


Sandbox key rejected
Using production key
Verify key starts with personasandbox


Template not found
Wrong environment
Templates are per-environment


Resources

Persona API Quickstart
ngrok Documentation

                
              

                
                  
                  
                  persona-performance-tuning
                  SKILL.md
                  View full skill →
                
                
                  'Optimize Persona API performance with batching and caching.
                  
                      ReadWriteEdit
                    
                
                
                  persona performance tuning | sed 's/\b\(.\)/\u\1/g'
Overview
Batch inquiry creation, cache verification results, parallel polling.
Prerequisites

Completed persona-install-auth setup
Valid Persona API key (sandbox or production)

Instructions
Step 1: Implementation

import os, requests

HEADERS = {
    "Authorization": f"Bearer {os.environ['PERSONA_API_KEY']}",
    "Persona-Version": "2023-01-05",
}
BASE = "https://withpersona.com/api/v1"

# Optimize Persona API performance with batching and caching
resp = requests.get(f"{BASE}/inquiries?page[size]=10", headers=HEADERS)
resp.raise_for_status()
inquiries = resp.json()["data"]
for inq in inquiries:
    print(f"  {inq['id']}: {inq['attributes']['status']}")

Output

Batch inquiry creation, cache verification results, parallel polling.

Error Handling

Error
Cause
Solution


401 Unauthorized
Invalid API key
Check PERSONAAPIKEY


429 Rate Limited
Too many requests
Implement backoff


404 Not Found
Wrong resource ID
Verify ID format


Resources

Persona API Reference
Persona Documentation

Next Steps
See related Persona skills for more workflows.
                
              

                
                  
                  
                  persona-prod-checklist
                  SKILL.md
                  View full skill →
                
                
                  'Production deployment checklist for Persona identity verification.
                  
                      ReadBash(curl:*)Grep
                    
                
                
                  persona prod checklist | sed 's/\b\(.\)/\u\1/g'
Overview
Production API keys, HTTPS webhooks, compliance review, monitoring, rollback.
Prerequisites

Completed persona-install-auth setup
Valid Persona API key (sandbox or production)

Instructions
Step 1: Implementation

import os, requests

HEADERS = {
    "Authorization": f"Bearer {os.environ['PERSONA_API_KEY']}",
    "Persona-Version": "2023-01-05",
}
BASE = "https://withpersona.com/api/v1"

# Production deployment checklist for Persona identity verification
resp = requests.get(f"{BASE}/inquiries?page[size]=10", headers=HEADERS)
resp.raise_for_status()
inquiries = resp.json()["data"]
for inq in inquiries:
    print(f"  {inq['id']}: {inq['attributes']['status']}")

Output

Production API keys, HTTPS webhooks, compliance review, monitoring, rollback.

Error Handling

Error
Cause
Solution


401 Unauthorized
Invalid API key
Check PERSONAAPIKEY


429 Rate Limited
Too many requests
Implement backoff


404 Not Found
Wrong resource ID
Verify ID format


Resources

Persona API Reference
Persona Documentation

Next Steps
See related Persona skills for more workflows.
                
              

                
                  
                  
                  persona-rate-limits
                  SKILL.md
                  View full skill →
                
                
                  'Handle Persona API rate limits with exponential backoff and request.
                  
                      ReadWriteEdit
                    
                
                
                  persona rate limits | sed 's/\b\(.\)/\u\1/g'
Overview
Persona rate limits (varies by plan), backoff on 429, batch inquiry creation, queue-based processing.
Prerequisites

Completed persona-install-auth setup
Valid Persona API key (sandbox or production)

Instructions
Step 1: Implementation

import os, requests

HEADERS = {
    "Authorization": f"Bearer {os.environ['PERSONA_API_KEY']}",
    "Persona-Version": "2023-01-05",
}
BASE = "https://withpersona.com/api/v1"

# Handle Persona API rate limits with exponential backoff and request queuing
resp = requests.get(f"{BASE}/inquiries?page[size]=10", headers=HEADERS)
resp.raise_for_status()
inquiries = resp.json()["data"]
for inq in inquiries:
    print(f"  {inq['id']}: {inq['attributes']['status']}")

Output

Persona rate limits (varies by plan), backoff on 429, batch inquiry creation, queue-based processing.

Error Handling

Error
Cause
Solution


401 Unauthorized
Invalid API key
Check PERSONAAPIKEY


429 Rate Limited
Too many requests
Implement backoff


404 Not Found
Wrong resource ID
Verify ID format


Resources

Persona API Reference
Persona Documentation

Next Steps
See related Persona skills for more workflows.
                
              

                
                  
                  
                  persona-reference-architecture
                  SKILL.md
                  View full skill →
                
                
                  'KYC service architecture with Persona as verification provider.
                  
                      ReadGrep
                    
                
                
                  persona reference architecture | sed 's/\b\(.\)/\u\1/g'
Overview
Service architecture, inquiry lifecycle, webhook-driven processing, compliance patterns.
Prerequisites

Completed persona-install-auth setup
Valid Persona API key (sandbox or production)

Instructions
Step 1: Implementation

import os, requests

HEADERS = {
    "Authorization": f"Bearer {os.environ['PERSONA_API_KEY']}",
    "Persona-Version": "2023-01-05",
}
BASE = "https://withpersona.com/api/v1"

# KYC service architecture with Persona as verification provider
resp = requests.get(f"{BASE}/inquiries?page[size]=10", headers=HEADERS)
resp.raise_for_status()
inquiries = resp.json()["data"]
for inq in inquiries:
    print(f"  {inq['id']}: {inq['attributes']['status']}")

Output

Service architecture, inquiry lifecycle, webhook-driven processing, compliance patterns.

Error Handling

Error
Cause
Solution


401 Unauthorized
Invalid API key
Check PERSONAAPIKEY


429 Rate Limited
Too many requests
Implement backoff


404 Not Found
Wrong resource ID
Verify ID format


Resources

Persona API Reference
Persona Documentation

Next Steps
See related Persona skills for more workflows.
                
              

                
                  
                  
                  persona-sdk-patterns
                  SKILL.md
                  View full skill →
                
                
                  'Production Persona API client wrapper with retry, pagination, typed.
                  
                      ReadWriteEdit
                    
                
                
                  persona sdk patterns | sed 's/\b\(.\)/\u\1/g'
Overview
Singleton API client, typed verification results, pagination through inquiries, error classification.
Prerequisites

Completed persona-install-auth setup
Valid Persona API key (sandbox or production)

Instructions
Step 1: Typed API Client Wrapper

import axios, { AxiosInstance, AxiosError } from 'axios';

interface PersonaConfig {
  apiKey: string;
  version?: string;
  baseURL?: string;
}

class PersonaClient {
  private http: AxiosInstance;

  constructor(config: PersonaConfig) {
    this.http = axios.create({
      baseURL: config.baseURL || 'https://withpersona.com/api/v1',
      headers: {
        'Authorization': `Bearer ${config.apiKey}`,
        'Persona-Version': config.version || '2023-01-05',
        'Content-Type': 'application/json',
      },
    });
  }

  async createInquiry(templateId: string, referenceId: string, fields?: Record<string, any>) {
    const { data } = await this.http.post('/inquiries', {
      data: { attributes: { 'inquiry-template-id': templateId, 'reference-id': referenceId, fields } },
    });
    return data.data;
  }

  async getInquiry(inquiryId: string) {
    const { data } = await this.http.get(`/inquiries/${inquiryId}`);
    return data.data;
  }

  async listInquiries(params: { referenceId?: string; status?: string; pageSize?: number } = {}) {
    const { data } = await this.http.get('/inquiries', {
      params: {
        'filter[reference-id]': params.referenceId,
        'filter[status]': params.status,
        'page[size]': params.pageSize || 25,
      },
    });
    return data.data;
  }

  async getVerification(verificationId: string) {
    const { data } = await this.http.get(`/verifications/${verificationId}`);
    return data.data;
  }
}

// Singleton
let _client: PersonaClient | null = null;
export function getPersonaClient(): PersonaClient {
  if (!_client) {
    _client = new PersonaClient({ apiKey: process.env.PERSONA_API_KEY! });
  }
  return _client;
}

Step 2: Error Classification

function classifyPersonaError(error: AxiosError): { retryable: boolean; message: string } {
  const status = error.response?.status;
  if (status === 429) return { retryable: true, message: 'Rate limited' };
  if (status && status >= 500) return { retryable: true, message: 'Server error' };
  if (status === 401) return { retryable: false, message: 'Invalid API key' };
  if (status === 422) return { retryable: false, message: 'Invalid request' };
  return { retryable: false, message: error.message };
}

Output

Typed Persona API client with inquiry and verification methods
Singleton p
                
              

                
                  
                  
                  persona-security-basics
                  SKILL.md
                  View full skill →
                
                
                  'Secure Persona API keys, webhook secrets, PII handling in verification.
                  
                      ReadWriteGrep
                    
                
                
                  persona security basics | sed 's/\b\(.\)/\u\1/g'
Overview
API key rotation, webhook HMAC verification, PII encryption at rest, audit logging.
Prerequisites

Completed persona-install-auth setup
Valid Persona API key (sandbox or production)

Instructions
Step 1: Implementation

import os, requests

HEADERS = {
    "Authorization": f"Bearer {os.environ['PERSONA_API_KEY']}",
    "Persona-Version": "2023-01-05",
}
BASE = "https://withpersona.com/api/v1"

# Secure Persona API keys, webhook secrets, PII handling in verification data
resp = requests.get(f"{BASE}/inquiries?page[size]=10", headers=HEADERS)
resp.raise_for_status()
inquiries = resp.json()["data"]
for inq in inquiries:
    print(f"  {inq['id']}: {inq['attributes']['status']}")

Output

API key rotation, webhook HMAC verification, PII encryption at rest, audit logging.

Error Handling

Error
Cause
Solution


401 Unauthorized
Invalid API key
Check PERSONAAPIKEY


429 Rate Limited
Too many requests
Implement backoff


404 Not Found
Wrong resource ID
Verify ID format


Resources

Persona API Reference
Persona Documentation

Next Steps
See related Persona skills for more workflows.
                
              

                
                  
                  
                  persona-upgrade-migration
                  SKILL.md
                  View full skill →
                
                
                  'Upgrade Persona API versions and handle breaking changes.
                  
                      ReadWriteEditBash(npm:*)Bash(git:*)
                    
                
                
                  persona upgrade migration | sed 's/\b\(.\)/\u\1/g'
Overview
API versioning via Persona-Version header, deprecated field migration, test against sandbox.
Prerequisites

Completed persona-install-auth setup
Valid Persona API key (sandbox or production)

Instructions
Step 1: Implementation

import os, requests

HEADERS = {
    "Authorization": f"Bearer {os.environ['PERSONA_API_KEY']}",
    "Persona-Version": "2023-01-05",
}
BASE = "https://withpersona.com/api/v1"

# Upgrade Persona API versions and handle breaking changes
resp = requests.get(f"{BASE}/inquiries?page[size]=10", headers=HEADERS)
resp.raise_for_status()
inquiries = resp.json()["data"]
for inq in inquiries:
    print(f"  {inq['id']}: {inq['attributes']['status']}")

Output

API versioning via Persona-Version header, deprecated field migration, test against sandbox.

Error Handling

Error
Cause
Solution


401 Unauthorized
Invalid API key
Check PERSONAAPIKEY


429 Rate Limited
Too many requests
Implement backoff


404 Not Found
Wrong resource ID
Verify ID format


Resources

Persona API Reference
Persona Documentation

Next Steps
See related Persona skills for more workflows.
                
              

                
                  
                  
                  persona-webhooks-events
                  SKILL.md
                  View full skill →
                
                
                  'Handle Persona webhook events for inquiry and verification status changes.
                  
                      ReadWriteEditBash(curl:*)
                    
                
                
                  persona webhooks events | sed 's/\b\(.\)/\u\1/g'
Overview
HMAC signature verification, inquiry.completed/approved/declined events, idempotent processing.
Prerequisites

Completed persona-install-auth setup
Valid Persona API key (sandbox or production)

Instructions
Step 1: Configure Webhook in Dashboard

1. Dashboard > Settings > Webhooks > Add Webhook
2. URL: https://your-app.com/webhooks/persona
3. Events: inquiry.completed, inquiry.approved, inquiry.declined,
           verification.passed, verification.failed
4. Copy the webhook secret for signature verification

Step 2: Webhook Endpoint with HMAC Verification

import express from 'express';
import crypto from 'crypto';

const app = express();

app.post('/webhooks/persona',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const signature = req.headers['persona-signature'] as string;
    const secret = process.env.PERSONA_WEBHOOK_SECRET!;

    // Verify HMAC-SHA256 signature
    const expectedSig = crypto
      .createHmac('sha256', secret)
      .update(req.body)
      .digest('hex');

    if (!crypto.timingSafeEqual(Buffer.from(signature || ''), Buffer.from(expectedSig))) {
      return res.status(401).json({ error: 'Invalid signature' });
    }

    const event = JSON.parse(req.body.toString());
    await handlePersonaEvent(event);
    res.status(200).json({ received: true });
  }
);

Step 3: Event Handlers

async function handlePersonaEvent(event: any) {
  const { type, data } = event;

  switch (type) {
    case 'inquiry.completed':
      const inquiryId = data.attributes.payload.data.id;
      const referenceId = data.attributes.payload.data.attributes['reference-id'];
      console.log(`Inquiry completed: ${inquiryId} for user ${referenceId}`);
      // Update user KYC status in your database
      await updateUserKycStatus(referenceId, 'completed');
      break;

    case 'inquiry.approved':
      await updateUserKycStatus(data.attributes.payload.data.attributes['reference-id'], 'approved');
      break;

    case 'inquiry.declined':
      await updateUserKycStatus(data.attributes.payload.data.attributes['reference-id'], 'declined');
      break;

    case 'verification.passed':
      console.log(`Verification passed: ${data.attributes.payload.data.id}`);
      break;

    case 'verification.failed':
      console.log(`Verification failed: ${data.attributes.payload.data.id}`);
      break;

    default:
      console.log(`Unhandled event: ${type}`);
  }
}

Step 4: Idempotent Processing

const processedEvents = 

                

              

          

        

      
      
          How It Works
          
"Set up Persona verification" -- triggers persona-install-auth
"Create KYC inquiry" -- triggers persona-core-workflow-a
"Handle Persona webhook" -- triggers persona-webhooks-events

        

      
      

      
      

      
      
  Ready to use persona-pack?
  
    
    
  




      
      
          Related Plugins
          
            
                supabase-pack
                Complete Supabase integration skill pack with 30 skills covering authentication, database, storage, realtime, edge functions, and production operations. Flagship+ tier vendor pack.
              
                vercel-pack
                Complete Vercel integration skill pack with 30 skills covering deployments, edge functions, preview environments, performance optimization, and production operations. Flagship+ tier vendor pack.
              
                clay-pack
                Complete Clay integration skill pack with 30 skills covering data enrichment, waterfall workflows, AI agents, and GTM automation. Flagship+ tier vendor pack.
              
                cursor-pack
                Complete Cursor integration skill pack with 30 skills covering AI code editing, composer workflows, codebase indexing, and productivity features. Flagship+ tier vendor pack.
              
                exa-pack
                Complete Exa integration skill pack with 30 skills covering neural search, semantic retrieval, web search API, and AI-powered discovery. Flagship+ tier vendor pack.
              
                firecrawl-pack
                Complete Firecrawl integration skill pack with 30 skills covering web scraping, crawling, markdown conversion, and LLM-ready data extraction. Flagship+ tier vendor pack.
              
          
        

      
      
          Tags
          
            personasaassdkintegration
          
        
    
  

  

    

    
    
        
            
                Stay in the Loop
                
                    
                    
                    
                
                No spam. Unsubscribe anytime.
            

            
                
                    Product
                    
                        Explore
                        Skills
                        Cowork
                        Compare
                        Tools
                    
                
                
                    Resources
                    
                        Docs
                        Changelog
                        Collections
                        Playbooks
                        Research
                        Learning
                    
                
                
                    Company
                    
                        Community
                        Hall of Fame
                        GitHub
                    
                
                
                    Legal
                    
                        Privacy
                        Terms
                        Acceptable Use
                    
                
            

            
                Tons of Skills by Intent Solutions. Marine. Citadel Grad. 20 years ops → self-taught dev → AI architect.
                © 2026 Tons of Skills | Intent Solutions

persona-pack

Installation

What It Does

Skills (18)

persona ci integration | sed 's/\b\(.\)/\u\1/g'

Overview

Prerequisites

Instructions

Step 1: Implementation

Output

Error Handling

Resources

Next Steps

persona common errors | sed 's/\b\(.\)/\u\1/g'

Overview

Prerequisites

Instructions

Error 1: 401 Unauthorized

Error 2: 422 Invalid Inquiry Template

Error 3: Webhook Signature Mismatch

Error 4: 429 Rate Limited

Error 5: Inquiry Already Completed

Error 6: 404 Inquiry Not Found

Output

Error Handling

Persona Core Workflow A — KYC Inquiry Flow

Overview

Prerequisites

Instructions

Step 1: Backend — Create Inquiry Endpoint

Step 2: Frontend — Embed Persona Flow

Step 3: Backend — Handle Completion

Persona Core Workflow B — Verification Checks

Overview

Prerequisites

Instructions

Step 1: List Verifications for an Inquiry

Step 2: Government ID Verification Results

Step 3: Selfie Liveness Check

persona cost tuning | sed 's/\b\(.\)/\u\1/g'

Overview

Prerequisites

Instructions

Step 1: Implementation

Output

Error Handling

Resources

Next Steps

persona debug bundle | sed 's/\b\(.\)/\u\1/g'

Overview

Prerequisites

Instructions

Step 1: Implementation

Output

Error Handling

Resources

Next Steps

persona deploy integration | sed 's/\b\(.\)/\u\1/g'

Overview

Prerequisites

Instructions

Step 1: Implementation

Output

Error Handling

Resources

Next Steps

Persona Hello World

Overview

Prerequisites

Instructions

Step 1: Create an Inquiry

Step 2: Get the Verification URL

Step 3: Poll for Completion

Step 4: Retrieve Verification Results

Persona Install & Auth

Overview

Prerequisites

Instructions

Step 1: Get API Keys

Step 2: Configure Environment