Identity verification workflows require seamless API integration, secure credential handling, and real-time status management across multiple verification states. Persona provides purpose-built APIs and SDKs for production identity verification, enabling rapid integration of compliance-grade verification flows. Persona's inquiry and case management endpoints let you generate verification links, track status changes, and escalate cases for manual review without custom polling logic. This tutorial covers the core integration pattern: creating inquiries, generating one-time links, managing case lifecycles, and monitoring relation data at scale.
What this tutorial covers
- •Outcome: You can build a complete identity verification integration using Persona APIs to manage inquiries, generate secure verification links, update case statuses, and handle manual review escalation.
- •Endpoints used: `POST /api/v1/inquiries/%7Binquiry-id%7D/generate-one-time-link`, `POST /api/v1/cases/%7Bcase-id%7D/set-status`, `POST /api/v1/inquiries/%7Binquiry-id%7D/mark-for-review`, `GET /api/v1/accounts/%7Baccount-id%7D/relations`, `POST /api/v1/inquiries/%7Binquiry-id%7D/perform-simulate-actions`
- •Language: typescript
- •Auth: API key (Authorization: Bearer {api_key})
- •Estimated implementation time: ~18 minutes
Step 1: Generate verification links with Persona inquiries
Persona inquiries represent individual verification requests. Generate a one-time link to securely redirect users to the verification flow without exposing internal identifiers. One-time links expire after first use, enforcing a single verified session per inquiry and reducing fraud surface area.
Create and link an inquiry
Response:
1const url = 'https://api.withpersona.com/api/v1/inquiries/inquiry-id/generate-one-time-link';
2const options = {
3 method: 'POST',
4 headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
5 body: '{}'
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 2: Mark inquiries for manual review in Persona workflows
When automated verification flags ambiguous cases, escalate them to your compliance team using Persona's manual review workflow. Manual review creates an audit trail and prevents false rejections, improving user experience while maintaining verification integrity.
Escalate inquiry for review
Response:
1const url = 'https://api.withpersona.com/api/v1/inquiries/inquiry-id/mark-for-review';
2const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
3
4try {
5 const response = await fetch(url, options);
6 const data = await response.json();
7 console.log(data);
8} catch (error) {
9 console.error(error);
10}Step 3: Update case status and track verification outcomes with Persona
After users complete verification through Persona, update the associated case status to reflect the final outcome: approved, rejected, or escalated. Synchronizing case status with Persona ensures downstream systems receive accurate verification results and reduces manual status reconciliation.
Set case approval status
1import fetch from 'node-fetch';
2
3const personaApiToken = process.env.PERSONA_API_TOKEN;
4const inquiryId = 'inquiry-id';
5const caseId = 'case-id';
6const verificationOutcome = 'approved';
7
8const url = 'https://api.withpersona.com/api/v1/cases/case-id/set-status';
9const options = {
10 method: 'POST',
11 headers: {Authorization: `Bearer ${personaApiToken}`, 'Content-Type': 'application/json'},
12 body: JSON.stringify({meta: {status: 'Approved'}})
13};
14
15const response = await fetch(url, options);
16const data = await response.json();
17console.log('Case status updated:', data);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 4: Retrieve account relations to monitor verification coverage
Query all relations (verified individuals, entities) linked to your account using Persona's relations endpoint to audit verification coverage and track verification history. Periodic relation queries let you detect gaps in verification pipelines and identify users who need re-verification.
Fetch account relations list
1const accountId = process.env.PERSONA_ACCOUNT_ID;
2const token = process.env.PERSONA_API_KEY;
3const url = 'https://api.withpersona.com/api/v1/accounts/account-id/relations?filter=%7B%22key%22%3A%22string%22%7D';
4const options = {method: 'GET', headers: {Authorization: `Bearer ${token}`}};
5
6try {
7 const response = await fetch(url, options);
8 const data = await response.json();
9 console.log('Account Relations Retrieved:', data);
10 if (data && data.data) {
11 console.log(`Found ${data.data.length} relations for verification audit`);
12 }
13} catch (error) {
14 console.error('Error retrieving account relations:', error);
15}Response:
1const url = 'https://api.withpersona.com/api/v1/accounts/account-id/relations?filter=%7B%22key%22%3A%22string%22%7D';
2const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
3
4try {
5 const response = await fetch(url, options);
6 const data = await response.json();
7 console.log(data);
8} catch (error) {
9 console.error(error);
10}Step 5: Test verification flows with Persona simulate actions
Before pushing to production, use the simulate actions endpoint to test end-to-end verification workflows in a sandbox environment. Simulation lets you validate approval logic, escalation paths, and status transitions without provisioning real identity documents or user data.
Simulate verification completion
Common pitfalls when using Persona
- •Polling instead of event-driven workflows. Repeatedly querying inquiry or case status via polling incurs unnecessary API load and rate-limit risk. Instead, configure webhook subscriptions to receive real-time status change events, reducing latency and integration overhead.
- •Missing audit trails for manual review escalations. When marking inquiries for review, omit the review-reason field, leaving compliance teams unable to understand why escalation occurred. Always populate reason attributes to maintain auditability and reduce investigation time.
- •Skipping sandbox simulation before production deployment. Launching verification flows directly in production without simulate-actions testing risks silent failures in approval logic or status transitions. Use sandbox endpoints first to validate entire workflows end-to-end.
- •Unmonitored relation-query performance at scale. Fetching all account relations without pagination or filtering can timeout or exhaust memory with thousands of verified individuals. Implement cursor-based pagination and apply status filters to keep queries performant and observable.
Ready to ship identity verification? Get started with Persona and integrate these endpoints into your production stack today.
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
Automate driver onboarding routing with Persona
Ride-share platforms must onboard millions of drivers annually while managing compliance risk and manual review bottlenecks efficiently. Persona provides intell
Build a production integration with Persona API
Integrating identity verification into production systems requires careful orchestration of authentication, data normalization, and status tracking across multi