Integrating identity verification into production systems requires handling state changes, retries, and real-time updates safely and reliably. Persona provides a REST API designed for production integrations with idempotent requests, webhook support, and detailed event payloads for monitoring. Persona's API surface supports setting case status, marking inquiries for review, generating secure links, and simulating verification actions programmatically. Production workflows benefit from webhooks to avoid polling and idempotency headers to safely retry failed operations without duplication.
What this tutorial covers
- •Outcome: You will build a TypeScript service that integrates Persona's verification API, handles state transitions, and processes webhooks for real-time updates.
- •Endpoints used: `POST /api/v1/cases/%7Bcase-id%7D/set-status`, `POST /api/v1/inquiries/%7Binquiry-id%7D/mark-for-review`, `POST /api/v1/inquiries/%7Binquiry-id%7D/perform-simulate-actions`, `POST /api/v1/inquiries/%7Binquiry-id%7D/generate-one-time-link`, `GET /api/v1/accounts/%7Baccount-id%7D/relations`
- •Language: typescript
- •Auth: API key (Authorization header with Bearer token)
- •Estimated implementation time: ~18 minutes
Step 1: Initialize the Persona API client in TypeScript
Set up authenticated HTTP requests to Persona using your API key. Store credentials in environment variables to keep them safe in production. All subsequent operations will use this client to communicate with Persona's REST endpoints.
Configure API authentication
1import fetch from 'node-fetch';
2
3const apiKey = process.env.PERSONA_API_KEY;
4if (!apiKey) {
5 throw new Error('PERSONA_API_KEY environment variable is required');
6}
7
8const headers = {
9 Authorization: `Bearer ${apiKey}`,
10 'Content-Type': 'application/json'
11};
12
13console.log('Persona API client initialized with authenticated headers');
14
15export { headers, fetch };The client is ready to make authenticated requests to Persona with optional idempotency support for retry safety.
Step 2: Set case status and transition verification workflows in Persona
When an inquiry completes, update its case status to reflect the verification outcome. Persona uses case status to track progress through your workflow. Use the set-status endpoint to move cases from pending to approved, rejected, or manual-review states.
Update case verification status
1const caseId = 'case-123';
2const verificationStatus = 'Approved';
3const url = 'https://api.withpersona.com/api/v1/cases/case-id/set-status';
4const options = {
5 method: 'POST',
6 headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
7 body: JSON.stringify({meta: {status: verificationStatus}})
8};
9
10try {
11 const response = await fetch(url, options);
12 const data = await response.json();
13 console.log('Case status updated:', data);
14} catch (error) {
15 console.error(error);
16}Response:
1const url = 'https://api.withpersona.com/api/v1/cases/case-id/set-status';
2const options = {
3 method: 'POST',
4 headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
5 body: '{"meta":{"status":"Approved"}}'
6};
7
8try {
9 const response = await fetch(url, options);
10 const data = await response.json();
11 console.log(data);
12} catch (error) {
13 console.error(error);
14}Step 3: Mark inquiries for manual review and secure verification links in Persona
Flag inquiries requiring human review when automated verification is inconclusive. Simultaneously, generate secure one-time links for users to complete or re-submit verification steps. Both operations ensure your team can intervene when needed while users receive secure, time-limited access to continue their verification.
Flag and issue secure verification link
Step 4: Simulate verification outcomes and fetch account relations in Persona
In development and staging, simulate different verification outcomes (pass, fail, error) to test your integration's handling of edge cases. Fetch related accounts and inquiries to understand an applicant's relationship map and detect patterns across submissions.
Test verification flows and retrieve relations
Step 5: Implement webhook handling for real-time Persona verification events
Production integrations should consume webhooks instead of polling Persona's API. Webhooks deliver immediate notifications when inquiries, verifications, or cases change state. Build an Express.js endpoint to validate webhook signatures and log detailed event payloads for debugging and monitoring.
Validate and process webhook events
The webhook endpoint validates signatures, processes events in real-time, and logs detailed outcomes for production monitoring and audit trails.
Step 6: Deploy best practices for production Persona integrations
Separate sandbox and production projects with distinct API keys. Rotate credentials regularly and restrict environment access to reduce the blast radius of any compromise. Use idempotency keys on all state-changing requests so retries remain safe. Monitor detailed event payloads and response data to tune your decisioning logic over time.
Production security and monitoring checklist
1// Production Persona integration with best practices
2const productionApiKey = process.env.PERSONA_PROD_API_KEY;
3const sandboxApiKey = process.env.PERSONA_SANDBOX_API_KEY;
4const idempotencyKey = `req-${Date.now()}-${Math.random()}`;
5
6const url = 'https://api.withpersona.com/api/v1/inquiries/inquiry-id/mark-for-review';
7const options = {method: 'POST', headers: {Authorization: `Bearer ${productionApiKey}`, 'Idempotency-Key': idempotencyKey}};
8
9try {
10 const response = await fetch(url, options);
11 const data = await response.json();
12 console.log('Event payload:', data);
13} catch (error) {
14 console.error('Request failed, safe to retry with same idempotency key:', error);
15}Your integration follows production security best practices: environment separation, idempotent retries, detailed logging, credential rotation, and configurable decisioning.
Common pitfalls when using Persona
- •Polling instead of webhooks. Repeatedly calling Persona's API to check inquiry status wastes bandwidth and increases latency. Webhooks deliver state changes instantly and reduce load on your infrastructure.
- •Missing idempotency keys on retries. Without the Idempotency-Key header, network failures or timeouts can cause duplicate case status updates, duplicate one-time links, or duplicate review flags in production.
- •Ignoring risk signals and event details. Persona's event payloads include detailed failure reasons and risk indicators. Logging and monitoring these helps you identify patterns, tune decisioning, and catch edge cases early.
- •Sharing API keys across environments. Using the same API key for sandbox and production increases blast radius. Separate credentials by environment and rotate production keys monthly to comply with security best practices.
Ready to ship this? Get started with Persona's REST API and deploy your production integration with confidence.
Documentation references
The code examples in this tutorial are grounded in the following docs pages:
- •
- •
- •
- •
- •
Want to streamline identity verification?
See how top tech teams use Withpersona to automate KYC, reduce fraud, and accelerate onboarding securely.
Read More Blog Posts
Build a production integration with Persona KYC
Integrating KYC verification into production requires coordinating inquiry workflows, managing case statuses, and handling real-time verification results reliab
Socure Alternatives That Actually Solve Your Pain Point
Socure is a capable platform, but teams typically leave when a specific operational need outgrows what one vertically integrated vendor can deliver: richer devi