Feature: Expert Application

Last updated: 2026-06-04 (Pass-3 docs audit follow-up — Tavus expert application cluster shipped 2026-06-03)

The Expert Application flow is how Humanity Protocol acquires new Experts: public applicants submit a form on the marketing site, complete an asynchronous Tavus video interview, and — if their interview reviews well — are promoted by a SuperAdmin into the platform as an active Expert. It is operationally distinct from the client onboarding flow.

Three audiences interact with this feature:

Applicants — fill the marketing form, take the Tavus interview, then wait for an outcome email.
AMs / SuperAdmins — review applications in the unified Ops surface (/ops/marketing/experts/*), retry interview invites, hard-delete spam entries, approve or decline applicants.
The Tavus integration — drives the video interview, posts conversation
- transcript webhooks back to humanwork-api, and atomically transitions the applicant to interview_completed so the review queue can pick them up.

What shipped

PR	Change	Date
#1369	Original expert application form, AI screening, and ops pipeline (closes #1082 — funnel: public apply form → async AI scoring → qualified / waitlisted → ops pipeline)	2026-05-30
#1478	Tavus video interviews wired into the expert application track (closes #1083) — `qualified` applicants are sent a Tavus interview link instead of the legacy "approved" email	2026-06-03
#1540	Fixed Tavus expert application integration issues — replica binding, applicant identity injected into `conversational_context`, conversation properties (recording + transcript callback URLs) tightened. Closes the regression that fell back to the `qualified` email when env was incomplete	2026-06-03
#1524	Ops review interface for `interview_completed` applicants — `/ops/marketing/experts` gets an Interviews tab and a "Retry interview invite" action	2026-06-03
#1519	SuperAdmin hard-delete endpoint for expert applications + trash-icon UI on the list view — lets ops scrub spam / duplicate submissions	2026-06-03
#1565	Flow polish — `send-to-interview` action for waitlisted applicants, Approve transition wired to the post-interview status, LinkedIn-URL dedup on submit so resubmissions don't create new rows	2026-06-03
#1560	5 Expert-onboarding email templates added to `EmailService` (closes #1554) — `application_received`, `interview_scheduled`, `application_approved`, `application_declined`, `welcome`. See onboarding.md §Expert onboarding email templates	2026-06-03

Flow

[Marketing site]
       │
       │ POST /marketing/experts/application
       ▼
expert_applications row (status = pending)
       │
       │ async AI scoring (#1369)
       ▼
status = qualified | waitlisted | rejected
       │
       ▼
┌──────────────────────────────────────────────┐
│ qualified  → Tavus interview invite          │
│             (#1478, #1540)                   │
│  email: expert.interview_scheduled           │
│  status → invited                            │
│                                              │
│ waitlisted → SuperAdmin clicks               │
│              "Send to interview" (#1565)     │
│              → same path as qualified        │
└──────────────────────────────────────────────┘
       │
       │ Applicant joins Tavus call
       │ Tavus posts webhook → /tavus/webhooks/conversation-ended
       │ Atomic status transition (#1083 / #1540): invited → interview_completed
       ▼
status = interview_completed
   + tavus_conversation_id, transcript_summary,
     interview_completed_at populated
       │
       │ SuperAdmin reviews in /ops/marketing/experts (Interviews tab, #1524)
       ▼
┌────────────────────────────────────┬────────────────────────────────────┐
│ Promote (POST .../promote)         │ Decline (POST .../decline)         │
│  status → approved                 │  status → rejected                 │
│  email: expert.application_approved│  email: expert.application_declined│
│  + create platform user (Expert)   │                                    │
└────────────────────────────────────┴────────────────────────────────────┘
       │
       │ Approved applicant logs into /workspace
       ▼
email: expert.welcome  → active Expert

Status machine

The full set of expert_applications.status values:

Status	Set by	Next transitions
`pending`	Public submit	→ `qualified` / `waitlisted` / `rejected` (AI scoring)
`reviewing`	AI scoring in-flight	→ `qualified` / `waitlisted` / `rejected`
`qualified`	AI scoring	→ `invited` (auto, Tavus invite sent) · → `rejected` (SA decline)
`waitlisted`	AI scoring	→ `invited` (SA send-to-interview, #1565) · → `rejected` (SA decline) · → `approved` (SA promote — legacy direct path)
`invited`	System (Tavus invite sent)	→ `interview_completed` (Tavus webhook) · → `rejected`
`interview_completed`	Tavus webhook (#1540)	→ `approved` (canonical post-interview path) · → `rejected`
`approved`	SA promote	terminal — platform Expert created
`rejected`	SA decline	terminal

Allowed transitions are enforced in MarketingService.promote() / decline() / sendWaitlistedToInterview() / retryInterviewInvite() — see api/src/marketing/marketing.service.ts. The post-interview promotion path (interview_completed → approved) is described in the service's docstring as the canonical path; promoting directly from waitlisted remains for back-compat with applications taken before #1478 shipped.

Module locations

Backend (NestJS)

api/src/marketing/ — applicant-facing surface (form submit, status poll, waitlist rejoin) and the core MarketingService that owns the expert_applications row + status transitions.
- marketing.controller.ts — public POST /marketing/experts/application, GET /marketing/experts/application/status, GET /marketing/experts/application/:id, POST /marketing/experts/rejoin-waitlist.
- marketing.service.ts — submitExpertApplication, sendWaitlistedToInterview (#1565), retryInterviewInvite (#1524), promote (#1565, accepts interview_completed as entry status), decline.
- entities/expert-application.entity.ts — the expert_applications row (incl. Tavus fields added in the 1783/1784 migration series — see Schema below).

api/src/admin/admin-marketing-leads.controller.ts — SuperAdmin / AM-facing Ops surface. Mounts at /admin/marketing/leads/experts/*. Live routes:

Route	Purpose
`GET /admin/marketing/leads/experts`	List applicants (filterable by status — Interviews tab uses `status=interview_completed`)
`GET /admin/marketing/leads/experts/:id`	Detail view
`PATCH /admin/marketing/leads/experts/:id/status`	Direct status patch (back-compat)
`POST /admin/marketing/leads/experts/:id/promote`	Promote (`interview_completed` → `approved`, also accepts `waitlisted`/`invited`)
`POST /admin/marketing/leads/experts/:id/decline`	Decline → `rejected`
`POST /admin/marketing/leads/experts/:id/retry-invite`	Resend Tavus invite (#1524)
`POST /admin/marketing/leads/experts/:id/send-to-interview`	Force `waitlisted` → `invited` + send Tavus invite (#1565)
`PATCH /admin/marketing/leads/experts/:id/threshold`	Adjust per-application AI score threshold
`DELETE /admin/marketing/leads/experts/:id`	SuperAdmin hard-delete (#1519)

api/src/tavus/tavus.controller.ts — Tavus webhook intake. POST /tavus/webhooks/conversation-ended is the entry point that atomically transitions invited → interview_completed (see #1540 fix). Related webhooks: POST /tavus/webhooks/function-call, POST /tavus/webhooks/transcript-ready. Replica enumeration: GET /tavus/replicas (gated by PlatformRolesGuard).

Schema

expert_applications table (TypeORM entity: api/src/marketing/entities/expert-application.entity.ts). Tavus-track columns were added by the following migrations (verify under api/migrations/):

Migration	Adds
`1783000000001-AddTavusFieldsToExpertApplication.ts`	`tavus_conversation_id`, `tavus_replica_id`, plus the `invited`/`interview_completed` status enum values
`1783000000002-AddInterviewReminderSentField.ts`	`interview_reminder_sent_at` — for the reminder-nudge job on stale `invited` applicants
`1783000000003-AddInviteSentAtToExpertApplication.ts`	`invite_sent_at` — anchors the reminder schedule and the `retry-invite` cooldown
`1784000000001-AddInterviewCompletedAtToExpertApplication.ts`	`interview_completed_at` — set by the `/tavus/webhooks/conversation-ended` handler
`1784000000002-AddTranscriptSummaryToExpertApplication.ts`	`transcript_summary` (JSONB) — populated when the Tavus transcript webhook fires; surfaced in the Ops Interviews tab

The older marketing-side migration 1746000000009-ExpertApplicationR2Urls.ts (resume / portfolio object storage) and 1752200000010-ExpertApplicationWaitlistFields.ts (AI scoring + waitlist) predate the Tavus track but remain in effect.

Frontend

Public form: frontend/src/app/(marketing)/apply/experts/* (and the /apply/experts/status poll page).
Ops surface: frontend/src/app/ops/marketing/experts/* — list view, Interviews tab (#1524), per-application detail with Approve / Decline / Retry / Send-to-Interview / Delete actions.

The Expert workspace surface itself (/workspace/*) is not part of this doc — it's covered by expert-workspace.md. Approved applicants only see /workspace/* after the expert.application_approved email lands them on the welcome flow.

Email side effects

Triggered by EmailService from MarketingService (#1560):

Transition	Template key
Submit (any `pending` create)	`expert.application_received`
`qualified` / `waitlisted` + `send-to-interview` / `retry-invite`	`expert.interview_scheduled` (includes the Tavus join URL)
`promote` → `approved`	`expert.application_approved`
`decline` → `rejected`	`expert.application_declined`
First successful login to `/workspace`	`expert.welcome`

Templates live under api/src/email/templates/expert/. Copy changes go through PR review; see onboarding.md §Expert onboarding email templates.

docs/specs/tavus-integration.md — the design surface for the wider Tavus integration (replica management, conversational context, webhook signatures, cost model). The expert application is one of two surfaces consuming Tavus today (the other is the client × Specialist onboarding call, tracked under #1379).
docs/decisions/tavus/ADR-0001-integration-approach.md — chosen integration shape (CVI conversations + replicas, not standalone Persona Manager).
docs/decisions/tavus/ADR-0002-integration-test-deferral.md — why integration tests against the live Tavus API are deferred and how that's compensated.
docs/features/onboarding.md — client-side onboarding (distinct flow); the Expert email-templates table referenced from §Expert onboarding email templates is the same one consumed here.
Open follow-ups: #1202 (wire Tavus invite into promoteExpertApplication for legacy waitlisted-direct-promote — now largely subsumed by #1565), #1363 (P2 design — abstract the Tavus "management" layer that today lives partly in tavus/ and partly in marketing/).

What shipped​

Flow​

Status machine​

Module locations​

Backend (NestJS)​

Schema​

Frontend​

Email side effects​

Related​