Ride-share platforms must onboard millions of drivers annually while managing compliance risk and manual review bottlenecks efficiently. Persona provides intelligent case routing and lifecycle orchestration to automate driver verification workflows at scale. Persona's account and case management APIs enable rule-based routing that applies the right verification intensity—reducing manual review by up to 50% while maintaining compliance. By automating status lifecycle and case routing, platforms reduce time-to-go-live and improve driver completion rates through minimal, focused onboarding flows.
What this tutorial covers
- •Outcome: You will deploy a TypeScript service that routes new driver applications to appropriate verification paths and tracks onboarding status lifecycle using Persona's APIs.
- •Endpoints used: `POST /api/v1/accounts`, `POST /api/v1/cases/search`
- •Language: typescript
- •Auth: API key (X-API-Key header)
- •Estimated implementation time: ~15 minutes
Step 1: Create a driver account in Persona
When a new driver submits their application, create an account in Persona to anchor their verification journey and enable case routing decisions. Persona's account endpoint establishes the identity record that subsequent verification steps and case decisions reference.
Initialize driver account
1async function createDriverAccount(personaToken: string): Promise<void> {
2 const url = 'https://api.withpersona.com/api/v1/accounts';
3 const options = {
4 method: 'POST',
5 headers: { Authorization: `Bearer ${personaToken}`, 'Content-Type': 'application/json' },
6 body: '{}'
7 };
8
9 try {
10 const response = await fetch(url, options);
11 const data = await response.json();
12 console.log('Driver account created:', data);
13 } catch (error) {
14 console.error('Failed to create driver account:', error);
15 }
16}Response:
1const url = 'https://api.withpersona.com/api/v1/accounts';
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: Route cases based on risk using Persona's search API
After creating the account, search for existing cases or query the routing engine to assign drivers to the appropriate verification path—low-risk fast-track or high-risk manual review. Persona enables intelligent routing that can improve onboarding pass rates by 5–20% by reducing friction for low-risk applicants while escalating complex cases to human agents.
Search and route cases by risk
1const token = process.env.PERSONA_API_TOKEN;
2
3const createAccountUrl = 'https://api.withpersona.com/api/v1/accounts';
4const createAccountOptions = {
5 method: 'POST',
6 headers: {Authorization: `Bearer ${token}`, 'Content-Type': 'application/json'},
7 body: '{}'
8};
9
10const accountResponse = await fetch(createAccountUrl, createAccountOptions);
11const accountData = await accountResponse.json();
12console.log('Account created:', accountData);
13
14const searchUrl = 'https://api.withpersona.com/api/v1/cases/search';
15const searchOptions = {
16 method: 'POST',
17 headers: {Authorization: `Bearer ${token}`, 'Content-Type': 'application/json'},
18 body: '{"page":{"size":15}}'
19};
20
21const searchResponse = await fetch(searchUrl, searchOptions);
22const searchData = await searchResponse.json();
23
24if (searchData.data && searchData.data.length > 0) {
25 const riskLevel = searchData.data[0].attributes?.risk_level;
26 if (riskLevel === 'low') {
27 console.log('Routing to fast-track verification');
28 } else {
29 console.log('Routing to manual review queue');
30 }
31} else {
32 console.log('No existing cases found, initiating verification workflow');
33}Response:
1const url = 'https://api.withpersona.com/api/v1/cases/search';
2const options = {
3 method: 'POST',
4 headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
5 body: '{"query":{"and":[{"attribute":"template","operator":"eq","value":"ctmpl_ABC123"},{"or":[{"attribute":"status","operator":"eq","value":"open"},{"attribute":"status","operator":"eq","value":"pending"}]}]},"sort":{"attribute":"created_at","direction":"desc"},"page":{"size":15}}'
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: Implement status lifecycle transitions in Persona
Map driver onboarding states—application submitted, document upload, background check, vehicle verification, approved—to Persona case statuses so human agents see accurate, real-time progress. Automating status transitions reduces manual status-update queries to support and ensures agent productivity focuses on exception handling rather than routine case lookups.
Transition case status through lifecycle
The status lifecycle mapping ensures Persona always reflects the current driver verification stage, enabling agents to prioritize cases and reducing redundant follow-up queries.
Step 4: Configure minimal, focused onboarding flows with Persona
Design your driver onboarding workflow with three to five high-value steps—application, documents, consent, vehicle—keeping Persona's case stages aligned to reduce drop-off. Persona's routing intelligence automatically escalates only high-risk cases to manual review, freeing agent capacity for edge cases and improving overall completion rates.
Build staged verification flow
1// Configure minimal driver onboarding workflow with Persona case routing
2const token = process.env.PERSONA_API_KEY;
3
4// Search for high-risk cases requiring manual review
5const url = 'https://api.withpersona.com/api/v1/cases/search';
6const options = {
7 method: 'POST',
8 headers: {Authorization: `Bearer ${token}`, 'Content-Type': 'application/json'},
9 body: '{"query":{"attribute":"status","operator":"eq","value":"open"},"page":{"size":15}}'
10};
11
12const response = await fetch(url, options);
13const data = await response.json();
14console.log('Onboarding cases ready for routing:', data);A concise, multi-stage flow prevents onboarding drop-off by keeping drivers focused on essential actions, while Persona's automated routing ensures agents handle only the cases requiring human judgment.
Step 5: Monitor onboarding metrics and agent efficiency with Persona
Track completion rates, time-to-approval, and manual review volumes by querying Persona's cases at regular intervals, giving you visibility into driver flow and agent workload. Automating routine status updates and case routing frees human agents to focus on complex cases, measurably improving productivity and reducing customer service friction.
Query and analyze onboarding performance
1import { setInterval } from 'timers';
2
3const apiToken = process.env.PERSONA_API_TOKEN;
4
5async function monitorOnboardingMetrics() {
6 const url = 'https://api.withpersona.com/api/v1/cases/search';
7 const options = {
8 method: 'POST',
9 headers: { Authorization: `Bearer ${apiToken}`, 'Content-Type': 'application/json' },
10 body: '{"query":{"not":{"attribute":"status","operator":"eq","value":"resolved"}},"sort":{"attribute":"created_at","direction":"asc"},"page":{"size":15}}'
11 };
12 try {
13 const response = await fetch(url, options);
14 const data = await response.json();
15 console.log(`Active cases: ${data.data.length}, Completion progress tracked`);
16 } catch (error) {
17 console.error(error);
18 }
19}
20
21setInterval(monitorOnboardingMetrics, 300000);Real-time visibility into completion rates, manual review volume, and automated-path efficiency reveals whether your onboarding flow is reducing friction and improving agent productivity as expected.
Common pitfalls when using Persona
- •Ignoring risk-score segmentation. Applying the same verification intensity to all drivers wastes agent time and frustrates low-risk applicants. Always query Persona's risk score and route high-risk cases to manual review while fast-tracking low-risk drivers.
- •Over-complicating the lifecycle. Long onboarding flows with many steps correlate with higher drop-off. Keep your workflow to three to five focused actions; Persona's intelligent routing and status transitions handle the complexity behind the scenes.
- •Skipping status synchronization. If your platform's internal driver state drifts from Persona's case status, agents will be confused and support queries spike. Always reflect Persona status transitions back into your application and keep metadata in sync.
- •Manual review bottleneck without automation. Routing all cases to agents negates Persona's efficiency gains. Let Persona's automated rules and risk-scoring delegate routine approvals; reserve agent time for edge cases and escalations.
Ready to accelerate your driver onboarding and reduce manual review overhead? Get started with Persona and deploy intelligent case routing at scale.
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 production identity verification with Persona APIs
Identity verification workflows require seamless API integration, secure credential handling, and real-time status management across multiple verification state
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