What this tutorial covers

• •
  Outcome: You will build a TypeScript integration that creates inquiry sessions, handles manual review escalations, and tracks verification lifecycle events.
• •
  Endpoints used: `POST /api/v1/inquiries/%7Binquiry-id%7D/generate-one-time-link`, `POST /api/v1/inquiries/%7Binquiry-id%7D/mark-for-review`, `POST /api/v1/cases/%7Bcase-id%7D/set-status`, `GET /api/v1/accounts/%7Baccount-id%7D/relations`
• •
  Language: typescript
• •
  Auth: API key (Authorization: Bearer header)
• •
  Estimated implementation time: ~18 minutes

Step 1: Generate a one-time verification link with Persona

Create inquiry verification session

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 an inquiry for manual review in Persona

Escalate inquiry to manual review

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: Track case status updates from Persona

Set case verification outcome

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: Fetch account relations for holistic compliance

Retrieve linked account relations

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: Implement event-driven updates via webhook handlers

Listen for Persona webhook events

Common pitfalls when using Persona

• •
  Ignoring one-time link expiration. Generated links expire in minutes. Always issue fresh links per session and validate expiration timestamps before redirecting users. Reusing stale links will cause verification failures in production.
• •
  Relying on polling instead of webhooks. Polling full inquiry datasets on a schedule consumes quota rapidly and introduces latency. Production integrations should register webhook subscriptions in Persona and handle async events to keep queries incremental.
• •
  Skipping pre-production environment validation. Test your integration against Persona's sandbox environment first. Validate error handling, edge cases, and all four endpoints before promoting to production. Missing even one test scenario can cause deployment failure.
• •
  Not normalizing upstream account data early. If you support multiple customers with custom fields or localized names, normalize data before sending to Persona. This reduces downstream breakage when Persona APIs update or when you support new data sources.

Documentation references

• •
  docs.withpersona.com/api-reference/inquiries/generate-a-one-time-link.md
• •
  docs.withpersona.com/api-reference/inquiries/mark-an-inquiry-for-review.md
• •
  docs.withpersona.com/api-reference/cases/set-status-for-a-case.md
• •
  docs.withpersona.com/api-reference/accounts/list-all-relations.md