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.

Related

• 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/).