{"openapi":"3.1.0","info":{"title":"Coverfy BFF API","description":"Coverfy Backend-for-Frontend API contract. Single source of truth for web / advisor-web / mobile.\nMounted at `/api/v1/*` on the BFF service (default port 3105).\n","version":"0.4.0","contact":{"name":"Coverfy Platform","email":"platform@coverfy.example"}},"servers":[{"url":"http://localhost:3105","description":"Local development"},{"url":"https://bff.coverfy.example","description":"Production (via Cloudflare Tunnel)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"hex","description":"BFF-issued token from /api/v1/prospect/login or /register or /auth/otp/verify"},"apiKey":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"Internal broker/admin API key (process.env.BFF_API_KEY)"},"brokerContext":{"type":"apiKey","in":"header","name":"X-Broker-Id","description":"Broker identity for tenant-scoped operations"},"tenantContext":{"type":"apiKey","in":"header","name":"X-Tenant-Id","description":"Tenant identity for multi-tenant scope"},"voiceWorkerKey":{"type":"apiKey","in":"header","name":"X-Voice-Worker-Key","description":"Voice outbound worker authentication (process.env.VOICE_OUTBOUND_API_KEY)"},"userIdHeader":{"type":"apiKey","in":"header","name":"X-User-Id","description":"Used by /client/assistant/* routes instead of bearer token"},"prospectTokenHeader":{"type":"apiKey","in":"header","name":"X-Prospect-Token","description":"Alternate to Authorization Bearer for /me etc."}},"schemas":{"Notification":{"type":"object","required":["notificationId","type","title","severity","createdAt"],"properties":{"notificationId":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["claim_update","policy_review","advisor_message","document_request","renewal_due","assistant_followup","feedback_response","security_alert","account_update","general"]},"title":{"type":"string"},"body":{"type":"string","nullable":true},"actionUrl":{"type":"string","nullable":true},"severity":{"type":"string","enum":["info","warning","success","critical"],"default":"info"},"readAt":{"type":"string","format":"date-time","nullable":true},"dismissedAt":{"type":"string","format":"date-time","nullable":true},"relatedEntityType":{"type":"string","nullable":true},"relatedEntityId":{"type":"string","nullable":true},"metadata":{"type":"object","additionalProperties":true},"createdAt":{"type":"string","format":"date-time"}}},"EmptyOk":{"type":"object","required":["ok"],"properties":{"ok":{"type":"boolean","const":true}}},"BrokerPublic":{"type":"object","required":["brokerId","email","fullName","isActive"],"properties":{"brokerId":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"fullName":{"type":"string"},"headline":{"type":"string","nullable":true},"bio":{"type":"string","nullable":true},"licenseState":{"type":"string","nullable":true},"licenseNumberMasked":{"type":"string","nullable":true},"yearsExperience":{"type":"integer","nullable":true},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time","nullable":true}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"code":{"type":"string","nullable":true},"message":{"type":"string","nullable":true},"details":{},"status":{"type":"integer","nullable":true}}},"HealthCheck":{"type":"object","required":["service","version","stack","checks"],"properties":{"status":{"type":"string","enum":["ok","degraded"]},"service":{"type":"string"},"version":{"type":"string"},"stack":{"type":"string"},"checks":{"type":"object","additionalProperties":true}}},"ServiceStatus":{"type":"object","properties":{"crm":{"type":"string"},"crmAdminUrl":{"type":"string","format":"uri"},"fileStore":{"type":"string"},"documentIntake":{"$ref":"#/components/schemas/ServiceStatusDocumentIntake"},"returnCycle":{"$ref":"#/components/schemas/ServiceStatusReturnCycle"},"termConversion":{"$ref":"#/components/schemas/ServiceStatusReportEndpoint"},"dividendTrack":{"$ref":"#/components/schemas/ServiceStatusReportEndpoint"},"prospectIntake":{"$ref":"#/components/schemas/ServiceStatusReportEndpoint"},"portals":{"type":"object","additionalProperties":true}}},"EspoPing":{"type":"object","required":["reachable"],"properties":{"reachable":{"type":"boolean"},"url":{"type":"string","nullable":true},"latencyMs":{"type":"number","nullable":true},"error":{"type":"string","nullable":true}}},"UserPublic":{"type":"object","properties":{"userId":{"type":"string"},"email":{"type":"string","format":"email"},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"preferredLanguage":{"type":"string","nullable":true},"caslConsent":{"type":"boolean"},"latestReportId":{"type":"string","nullable":true},"prospectHouseholdId":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time","nullable":true}}},"RegisterRequest":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"},"firstName":{"type":"string"},"lastName":{"type":"string"},"caslConsent":{"type":"boolean","default":false},"sessionId":{"type":"string"},"password":{"type":"string"},"inviteToken":{"type":"string"}}},"LoginRequest":{"type":"object","required":["email"],"properties":{"email":{"type":"string","description":"Email or phone (legacy compat)"},"password":{"type":"string"}}},"LoginResponse":{"type":"object","required":["user","token"],"properties":{"user":{"$ref":"#/components/schemas/UserPublic"},"token":{"type":"string"},"reportId":{"type":"string","nullable":true},"prospectHouseholdId":{"type":"string","nullable":true}}},"MeResponse":{"type":"object","properties":{"user":{"$ref":"#/components/schemas/UserPublic"},"reportId":{"type":"string","nullable":true}}},"InviteResponse":{"type":"object","properties":{"invite":{"type":"object","properties":{"clientId":{"type":"string"},"email":{"type":"string","format":"email"},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"ownerBrokerId":{"type":"string"},"expiresAt":{"type":"string","format":"date-time","nullable":true}}}}},"IntakeSessionCreateResponse":{"type":"object","required":["sessionId"],"properties":{"sessionId":{"type":"string"}}},"IntakeSessionPatchRequest":{"type":"object","additionalProperties":true,"description":"Partial intake fields (name, age, dependents, income, scenario, preferred_language,\nexisting_coverage, risk_tolerance, contact, etc.). All keys free-form.\n"},"IntakeSessionResponse":{"type":"object","properties":{"sessionId":{"type":"string"},"intake":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/IntakeField"}}}},"IntakeChatRequest":{"type":"object","required":["sessionId"],"properties":{"sessionId":{"type":"string"},"message":{"type":"string"},"chipAnswer":{"type":"string"},"inputMode":{"type":"string","enum":["text","voice"]}}},"IntakeChatResponse":{"type":"object","properties":{"sessionId":{"type":"string"},"reply":{"type":"string"},"chipOptions":{"type":"array","items":{"type":"string"}},"nextStep":{"type":"string","nullable":true},"intake":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/IntakeField"},"description":"Polymorphic intake map keyed by field name; each value is discriminated by `kind`."},"followUpFields":{"type":"array","items":{"type":"string"}},"error":{"type":"string","nullable":true},"status":{"type":"integer","nullable":true}}},"IntakePreview":{"type":"object","properties":{"reportId":{"type":"string"},"prospectHouseholdId":{"type":"string","nullable":true},"protectionScore":{"type":"integer"},"leadGrade":{"type":"string","enum":["A","B","C","D"]},"scenario":{"type":"string"},"scenarioLabel":{"type":"string"},"preferredLanguage":{"type":"string"},"gaps":{"type":"array","items":{"$ref":"#/components/schemas/IntakeGap"}},"riskEstimate":{"$ref":"#/components/schemas/RiskEstimate"},"preview":{"type":"boolean","enum":[true]},"disclaimer":{"type":"string"}}},"OtpSendRequest":{"type":"object","required":["phone"],"properties":{"phone":{"type":"string"},"sessionId":{"type":"string"}}},"OtpSendResponse":{"type":"object","properties":{"challengeId":{"type":"string"},"ttlSeconds":{"type":"integer"},"smsSent":{"type":"boolean"}}},"OtpVerifyRequest":{"type":"object","required":["challengeId","code"],"properties":{"challengeId":{"type":"string"},"code":{"type":"string","minLength":4,"maxLength":8},"sessionId":{"type":"string"},"caslConsent":{"type":"boolean"},"firstName":{"type":"string"},"lastName":{"type":"string"}}},"OtpVerifyResponse":{"type":"object","properties":{"token":{"type":"string"},"user":{"$ref":"#/components/schemas/UserPublic"},"reportId":{"type":"string","nullable":true},"leadId":{"type":"string","nullable":true}}},"Lead":{"type":"object","properties":{"leadId":{"type":"string"},"userId":{"type":"string"},"reportId":{"type":"string","nullable":true},"leadGrade":{"type":"string","enum":["A","B","C","D"]},"leadSource":{"type":"string","enum":["IntakeChat","BookAdvisor","BrokerClient","Registration","WebSandbox","Other"]},"ownershipLocked":{"type":"boolean"},"ownerBrokerId":{"type":"string","nullable":true},"tenantId":{"type":"string","nullable":true},"poolVisible":{"type":"boolean"},"preferredSlot":{"type":"string","nullable":true},"preferredLanguage":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"displayPhone":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"espoLeadId":{"type":"string","nullable":true},"espoSynced":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time","nullable":true},"status":{"type":"string","enum":["New","Contacted","Qualified","Won","Lost","OptOut"]},"sla":{"$ref":"#/components/schemas/LeadSla"}}},"BookAdvisorRequest":{"type":"object","required":["reportId"],"deprecated":true,"description":"Deprecated. Prefer BookAdvisorRequestV2. The snake_case siblings are kept\nfor backward compat and routed server-side to the camelCase fields.\n","properties":{"reportId":{"type":"string"},"slot":{"type":"string","description":"ISO date or relative slot ref"},"preferred_slot":{"type":"string"},"language":{"type":"string"},"preferred_language":{"type":"string"},"phone":{"type":"string"},"notes":{"type":"string"}}},"BookAdvisorResponse":{"type":"object","properties":{"lead":{"$ref":"#/components/schemas/Lead"},"espo":{"$ref":"#/components/schemas/LeadEspoSync"},"prospectHouseholdId":{"type":"string","nullable":true},"message":{"type":"string"}}},"LeadsListResponse":{"type":"object","properties":{"date":{"type":"string","description":"YYYY-MM-DD or \"today\" or \"all\""},"scope":{"type":"string","enum":["pool","mine","all"]},"brokerId":{"type":"string"},"filters":{"type":"object","properties":{"country":{"type":"string","nullable":true},"region":{"type":"string","nullable":true},"grade":{"type":"string","nullable":true},"city":{"type":"string","nullable":true}}},"masked":{"type":"boolean"},"leads":{"type":"array","items":{"$ref":"#/components/schemas/Lead"}},"count":{"type":"integer"}}},"ProspectPoolResponse":{"type":"object","properties":{"brokerId":{"type":"string"},"filters":{"type":"object","additionalProperties":{"nullable":true}},"sort":{"type":"string","nullable":true},"cityAnchor":{"type":"string","nullable":true},"masked":{"type":"boolean","enum":[true]},"prospects":{"type":"array","items":{"$ref":"#/components/schemas/Lead"}},"count":{"type":"integer"}}},"LeadsTodayResponse":{"type":"object","properties":{"leads":{"type":"array","items":{"$ref":"#/components/schemas/Lead"}}}},"Report":{"type":"object","properties":{"reportId":{"type":"string"},"sessionId":{"type":"string"},"protectionScore":{"type":"integer"},"leadGrade":{"type":"string"},"scenario":{"type":"string"},"scenarioLabel":{"type":"string"},"householdSummary":{"type":"object","additionalProperties":true},"riskEstimate":{"$ref":"#/components/schemas/RiskEstimate"},"gaps":{"type":"array","items":{"$ref":"#/components/schemas/IntakeGap"}},"disclaimer":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"DocumentUpload":{"type":"object","properties":{"uploadId":{"type":"string"},"userId":{"type":"string"},"prospectHouseholdId":{"type":"string"},"documentType":{"type":"string","enum":["Contract","AnnualStatement","InforceIllustration","Rider"]},"fileName":{"type":"string"},"mimeType":{"type":"string"},"fileSize":{"type":"integer"},"fileSha":{"type":"string"},"minioKey":{"type":"string"},"parseStatus":{"type":"string","enum":["Queued","InProgress","Succeeded","Failed"]},"extractionStatus":{"type":"string","nullable":true},"extractionEngine":{"type":"string","nullable":true},"confidence":{"type":"number","nullable":true},"fieldsPreview":{"type":"array","items":{"$ref":"#/components/schemas/DocumentFieldPreview"}},"fieldCoordinates":{"type":"object","additionalProperties":true},"reviewStatus":{"type":"string","nullable":true},"status":{"type":"string","enum":["Queued","InProgress","Extracted","Failed","Adopted","Rejected","NeedsMoreInfo","Certified"]},"advisorReviewRequired":{"type":"boolean","nullable":true},"leadId":{"type":"string","nullable":true},"error":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time","nullable":true}}},"UploadsListResponse":{"type":"object","properties":{"uploads":{"type":"array","items":{"$ref":"#/components/schemas/DocumentUpload"}}}},"UploadJourneyResponse":{"type":"object","properties":{"journey":{"type":"array","items":{"$ref":"#/components/schemas/DocumentJourneyStep"}},"upload":{"$ref":"#/components/schemas/DocumentUpload"}}},"PolicyDocument":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"policyId":{"type":"string"},"documentType":{"type":"string"},"parseStatus":{"type":"string","enum":["Queued","InProgress","Succeeded","Failed"]},"version":{"type":"integer"},"fileSha":{"type":"string"},"mimeType":{"type":"string"},"fileSize":{"type":"integer"},"minioKey":{"type":"string","nullable":true},"downloadUrl":{"type":"string","nullable":true,"format":"uri"},"createdAt":{"type":"string","format":"date-time"},"modifiedAt":{"type":"string","format":"date-time","nullable":true}}},"PolicyDocumentUploadRequest":{"type":"object","required":["policyId"],"properties":{"policyId":{"type":"string"},"documentType":{"type":"string","enum":["Contract","AnnualStatement","InforceIllustration","Rider"],"default":"Contract"},"version":{"type":"integer","default":1},"autoProcess":{"type":"boolean","default":false},"extractionTemplatePack":{"type":"string"}}},"PolicyDocumentUploadResponse":{"type":"object","properties":{"id":{"type":"string"},"policyId":{"type":"string"},"documentType":{"type":"string"},"parseStatus":{"type":"string"},"version":{"type":"integer"},"fileSha":{"type":"string"},"minioKey":{"type":"string"},"autoProcessed":{"type":"boolean"},"fieldsPreview":{"type":"array","items":{"$ref":"#/components/schemas/DocumentFieldPreview"}},"confidence":{"type":"number","nullable":true},"extractionStatus":{"type":"string","nullable":true},"extractionEngine":{"type":"string","nullable":true},"policyDocumentId":{"type":"string"},"policyExtractionId":{"type":"string","nullable":true}}},"PolicyFieldCoordinates":{"type":"object","properties":{"policyDocumentId":{"type":"string"},"policyExtractionId":{"type":"string","nullable":true},"extractionStatus":{"type":"string"},"fieldCoordinates":{"type":"object","additionalProperties":true},"confidence":{"type":"number","nullable":true}}},"PolicyCertifyRequest":{"type":"object","properties":{"fieldCoordinates":{"type":"object","additionalProperties":true}}},"PolicyCertifyResponse":{"type":"object","properties":{"policyDocumentId":{"type":"string"},"policyExtractionId":{"type":"string"},"policyId":{"type":"string"},"dataGrade":{"type":"string"},"policy":{"type":"object","additionalProperties":true},"prospectUploadId":{"type":"string","nullable":true},"certifiedAt":{"type":"string","format":"date-time","nullable":true}}},"Policy":{"type":"object","properties":{"id":{"type":"string"},"policyNumber":{"type":"string"},"carrierName":{"type":"string"},"productName":{"type":"string"},"policyType":{"type":"string"},"dataGrade":{"type":"string"}}},"PolicyDocumentsResponse":{"type":"object","properties":{"policyId":{"type":"string"},"policyNumber":{"type":"string","nullable":true},"documents":{"type":"array","items":{"$ref":"#/components/schemas/PolicyDocument"}}}},"HouseholdPoliciesResponse":{"type":"object","properties":{"householdId":{"type":"string"},"policies":{"type":"array","items":{"$ref":"#/components/schemas/Policy"}}}},"ReturnCycleNode":{"type":"object","properties":{"year":{"type":"integer"},"event":{"type":"string"},"cashValue":{"type":"number"},"netOutlay":{"type":"number"},"surrender":{"type":"number"},"guaranteed":{"type":"boolean"},"source":{"type":"string","enum":["Actual","Projected","OPIE"]}}},"ReturnCycleResponse":{"type":"object","properties":{"policyId":{"type":"string"},"nodes":{"type":"array","items":{"$ref":"#/components/schemas/ReturnCycleNode"}},"summary":{"type":"object","properties":{"breakEvenYear":{"type":"integer","nullable":true},"irr":{"type":"number","nullable":true},"cashValueAtMaturity":{"type":"number","nullable":true}}},"projectionAssumption":{"type":"string","enum":["Current","Guaranteed"]},"includeActual":{"type":"boolean"},"includeProjected":{"type":"boolean"},"disclaimer":{"type":"string"}}},"ReturnCycleNodesResponse":{"type":"object","properties":{"policy_id":{"type":"string"},"nodes":{"type":"array","items":{"$ref":"#/components/schemas/ReturnCycleNode"}},"warnings":{"type":"array","items":{"type":"string"}},"disclaimer":{"type":"string"}}},"ReturnCycleScenariosRequest":{"type":"object","required":["scenario_type"],"properties":{"scenario_type":{"type":"string","enum":["premium_increase","premium_decrease","death_benefit_change","fund_switch","withdrawal","loan"]},"params":{"type":"object","additionalProperties":true}}},"ReturnCycleScenarioResponse":{"type":"object","properties":{"scenario_type":{"type":"string"},"params":{"type":"object"},"nodes":{"type":"array","items":{"$ref":"#/components/schemas/ReturnCycleNode"}},"summary":{"type":"object","additionalProperties":true},"disclaimer":{"type":"string"}}},"TermConversionResponse":{"type":"object","properties":{"policyId":{"type":"string"},"convertibleWindow":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}}},"currentTerm":{"type":"object"},"conversionOptions":{"type":"array","items":{"type":"object","properties":{"productName":{"type":"string"},"estimatedPremium":{"type":"number"},"notes":{"type":"string"}}}},"disclaimer":{"type":"string"}}},"DividendTrackResponse":{"type":"object","properties":{"policyId":{"type":"string"},"dividendHistory":{"type":"array","items":{"type":"object","properties":{"year":{"type":"integer"},"dividendAmount":{"type":"number"},"source":{"type":"string"}}}},"projectedDividends":{"type":"array","items":{"type":"object","properties":{"year":{"type":"integer"},"projectedAmount":{"type":"number"},"assumption":{"type":"string"}}}},"disclaimer":{"type":"string"}}},"BrokerClient":{"type":"object","properties":{"clientId":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string","format":"email"},"ownerBrokerId":{"type":"string"},"ownershipLocked":{"type":"boolean"},"poolVisible":{"type":"boolean"},"leadSource":{"type":"string"},"status":{"type":"string"},"leadId":{"type":"string","nullable":true},"preferredLanguage":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"userId":{"type":"string","nullable":true},"inviteExpiresAt":{"type":"string","format":"date-time","nullable":true},"lastPortalEmailAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"BrokerClientsListResponse":{"type":"object","properties":{"brokerId":{"type":"string"},"clients":{"type":"array","items":{"$ref":"#/components/schemas/BrokerClient"}},"count":{"type":"integer"}}},"BrokerClientCreateRequest":{"type":"object","required":["firstName","lastName","email"],"properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"preferredLanguage":{"type":"string"}}},"BrokerClientCreateResponse":{"type":"object","properties":{"client":{"type":"object","properties":{"clientId":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"ownerBrokerId":{"type":"string"},"ownershipLocked":{"type":"boolean"},"poolVisible":{"type":"boolean"},"leadSource":{"type":"string"},"status":{"type":"string"},"leadId":{"type":"string"}}},"lead":{"type":"object","properties":{"leadId":{"type":"string"},"leadSource":{"type":"string"},"ownershipLocked":{"type":"boolean"},"poolVisible":{"type":"boolean"},"ownerBrokerId":{"type":"string"}}}}},"BrokerClientDetail":{"type":"object","properties":{"client":{"$ref":"#/components/schemas/BrokerClient"},"household":{"type":"object","nullable":true},"policies":{"type":"array","items":{"$ref":"#/components/schemas/Policy"}},"documents":{"type":"array","items":{"$ref":"#/components/schemas/PolicyDocument"}},"recentActivity":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"at":{"type":"string","format":"date-time"},"description":{"type":"string"}}}},"followUpFields":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"status":{"type":"string"}}}}}},"BrokerClientPortalLinkRequest":{"type":"object","properties":{"coverfyWebUrl":{"type":"string","format":"uri"}}},"BrokerClientPortalLinkResponse":{"type":"object","properties":{"loginUrl":{"type":"string","format":"uri"},"tempPassword":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}}},"BrokerIntakeStep":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","enum":["text","choice","multi","number","date"]},"options":{"type":"array","items":{"type":"string"}},"required":{"type":"boolean"},"followUpField":{"type":"boolean"}}},"BrokerIntakeStepsResponse":{"type":"object","properties":{"steps":{"type":"array","items":{"$ref":"#/components/schemas/BrokerIntakeStep"}}}},"BrokerIntakeSubmitRequest":{"type":"object","required":["intake"],"properties":{"intake":{"type":"object","additionalProperties":true},"sendPortalLink":{"type":"boolean","default":false},"coverfyWebUrl":{"type":"string","format":"uri"}}},"BrokerIntakeSubmitResponse":{"type":"object","properties":{"client":{"$ref":"#/components/schemas/BrokerClient"},"lead":{"$ref":"#/components/schemas/Lead"},"portalLink":{"type":"object","nullable":true,"properties":{"loginUrl":{"type":"string","format":"uri"},"tempPassword":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}}}}},"BrokerFollowUpsResponse":{"type":"object","properties":{"brokerId":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{"followUpKey":{"type":"string"},"clientId":{"type":"string"},"clientName":{"type":"string"},"lastTouchAt":{"type":"string","format":"date-time"},"priority":{"type":"string","enum":["high","medium","low"]},"summary":{"type":"string"}}}},"count":{"type":"integer"}}},"BrokerProspectUploadsResponse":{"type":"object","properties":{"status":{"type":"string"},"uploads":{"type":"array","items":{"$ref":"#/components/schemas/BrokerProspectUpload"}},"count":{"type":"integer"}}},"BrokerProspectUpload":{"allOf":[{"$ref":"#/components/schemas/DocumentUpload"},{"type":"object","properties":{"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"leadGrade":{"type":"string","nullable":true},"fieldsPreviewSummary":{"type":"string"}}}]},"ProspectUploadActionResponse":{"type":"object","properties":{"uploadId":{"type":"string"},"reviewStatus":{"type":"string"},"message":{"type":"string"}}},"ProspectUploadAdoptResponse":{"type":"object","properties":{"success":{"type":"boolean"},"upload":{"$ref":"#/components/schemas/DocumentUpload"},"ownerBrokerId":{"type":"string"},"leadId":{"type":"string","nullable":true}}},"SendPortalEmailResponse":{"type":"object","properties":{"clientId":{"type":"string"},"email":{"type":"string","format":"email"},"result":{"type":"object","properties":{"id":{"type":"string"},"provider":{"type":"string"},"accepted":{"type":"boolean"}}}}},"Opportunity":{"type":"object","properties":{"opportunityId":{"type":"string"},"leadId":{"type":"string","nullable":true},"insuranceType":{"type":"string"},"language":{"type":"string"},"intentLevel":{"type":"string","enum":["high","medium","low"]},"state":{"type":"string","enum":["available","claimed","expired","locked"]},"agreedPrice":{"type":"number","nullable":true},"sla":{"type":"object","properties":{"deadlineAt":{"type":"string","format":"date-time"},"remainingSeconds":{"type":"integer"}}},"createdAt":{"type":"string","format":"date-time"}}},"OpportunityListResponse":{"type":"object","properties":{"opportunities":{"type":"array","items":{"$ref":"#/components/schemas/Opportunity"}},"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"}}},"OpportunityClaimRequest":{"type":"object","required":["agreed_price"],"properties":{"agreed_price":{"type":"number"}}},"OpportunityClaimResponse":{"type":"object","properties":{"success":{"type":"boolean"},"opportunity":{"$ref":"#/components/schemas/Opportunity"},"error":{"type":"string","nullable":true},"message":{"type":"string","nullable":true}}},"ClaimedOpportunitiesResponse":{"type":"object","properties":{"brokerId":{"type":"string"},"opportunities":{"type":"array","items":{"$ref":"#/components/schemas/Opportunity"}},"count":{"type":"integer"}}},"AdvisorApplication":{"type":"object","properties":{"application_id":{"type":"string","format":"uuid"},"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string","nullable":true},"license_state":{"type":"string","minLength":2,"maxLength":2},"license_number":{"type":"string"},"license_expiration":{"type":"string","format":"date","nullable":true},"firm_name":{"type":"string","nullable":true},"years_experience":{"type":"integer","nullable":true,"minimum":0,"maximum":80},"client_focus":{"type":"string","nullable":true,"enum":["family","business","estate","mixed"]},"monthly_volume":{"type":"string","nullable":true,"enum":["<5","5-15","15-50","50+"]},"plan_tier":{"type":"string","enum":["starter","professional","enterprise"]},"notes":{"type":"string","nullable":true},"source":{"type":"string"},"status":{"type":"string","enum":["new","reviewing","approved","rejected","on_hold"]},"reviewer_notes":{"type":"string","nullable":true},"reviewed_by":{"type":"string","nullable":true},"reviewed_at":{"type":"string","format":"date-time","nullable":true},"locale":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"AdvisorApplicationCreateRequest":{"type":"object","required":["first_name","last_name","email","license_state","license_number"],"properties":{"first_name":{"type":"string","maxLength":80},"last_name":{"type":"string","maxLength":80},"email":{"type":"string","format":"email","maxLength":160},"phone":{"type":"string","maxLength":40},"license_state":{"type":"string","minLength":2,"maxLength":2},"license_number":{"type":"string","maxLength":80},"license_expiration":{"type":"string","format":"date"},"firm_name":{"type":"string","maxLength":160},"years_experience":{"type":"integer","minimum":0,"maximum":80},"client_focus":{"type":"string","enum":["family","business","estate","mixed"]},"monthly_volume":{"type":"string","enum":["<5","5-15","15-50","50+"]},"plan_tier":{"type":"string","enum":["starter","professional","enterprise"],"default":"starter"},"notes":{"type":"string","maxLength":4000},"locale":{"type":"string","default":"en","maxLength":8},"referrer":{"type":"string","maxLength":255},"user_agent":{"type":"string","maxLength":255},"ip_address":{"type":"string","maxLength":64}}},"AdvisorApplicationUpdateRequest":{"type":"object","properties":{"first_name":{"type":"string","maxLength":80},"last_name":{"type":"string","maxLength":80},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"license_state":{"type":"string"},"license_number":{"type":"string"},"license_expiration":{"type":"string","format":"date"},"firm_name":{"type":"string"},"years_experience":{"type":"integer"},"client_focus":{"type":"string","enum":["family","business","estate","mixed"]},"monthly_volume":{"type":"string","enum":["<5","5-15","15-50","50+"]},"plan_tier":{"type":"string","enum":["starter","professional","enterprise"]},"notes":{"type":"string"},"status":{"type":"string","enum":["new","reviewing","approved","rejected","on_hold"]},"reviewer_notes":{"type":"string"},"reviewed_by":{"type":"string"},"locale":{"type":"string"}}},"AdvisorApplicationCreateResponse":{"type":"object","properties":{"success":{"type":"boolean"},"application":{"$ref":"#/components/schemas/AdvisorApplication"}}},"AdvisorApplicationDetailResponse":{"type":"object","properties":{"application":{"$ref":"#/components/schemas/AdvisorApplication"}}},"AdvisorApplicationListResponse":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"},"count":{"type":"integer"},"applications":{"type":"array","items":{"$ref":"#/components/schemas/AdvisorApplication"}}}},"AssistantConversation":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"lastMessageAt":{"type":"string","format":"date-time","nullable":true},"messageCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"}}},"AssistantConversationsListResponse":{"type":"object","properties":{"conversations":{"type":"array","items":{"$ref":"#/components/schemas/AssistantConversation"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}},"AssistantConversationCreateRequest":{"type":"object","properties":{"title":{"type":"string"},"firstMessage":{"type":"string"}}},"AssistantConversationCreateResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"messageCount":{"type":"integer"}}},"AssistantMessageLegacy":{"description":"DEPRECATED. Use AssistantMessage (discriminated by `type`) instead.\nKept for legacy OpenAPI consumers; will be removed in 1.0.0.\n","type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["user","ai","system"]},"content":{"type":"string"},"aiResponse":{"type":"object","nullable":true,"properties":{"directAnswer":{"type":"string"},"whyThisMatters":{"type":"string"},"whatINoticed":{"type":"string"},"whatToCheckNext":{"type":"array","items":{"type":"string"}},"needProfessionalHelp":{"type":"boolean"},"confidence":{"type":"number"}}},"attachments":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"ref":{"type":"string"}}}},"createdAt":{"type":"string","format":"date-time"}}},"AssistantMessagesListResponse":{"type":"object","properties":{"conversationId":{"type":"string"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/AssistantMessage"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}},"AssistantMessageSendRequest":{"type":"object","required":["content"],"properties":{"content":{"type":"string","minLength":1},"attachments":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"ref":{"type":"string"}}}}}},"AssistantMessageSendResponse":{"type":"object","properties":{"userMessage":{"$ref":"#/components/schemas/AssistantMessage"},"aiMessage":{"$ref":"#/components/schemas/AssistantMessage"}}},"IntakeFollowUpJob":{"type":"object","properties":{"jobId":{"type":"string"},"sessionId":{"type":"string"},"phone":{"type":"string"},"followUpFields":{"type":"array","items":{"type":"string"}},"prospectHouseholdId":{"type":"string","nullable":true},"leadId":{"type":"string","nullable":true},"enqueuedAt":{"type":"string","format":"date-time"}}},"RbacRole":{"type":"object","properties":{"roleId":{"type":"string"},"roleKey":{"type":"string"},"roleName":{"type":"string"},"roleDescription":{"type":"string","nullable":true},"level":{"type":"integer","description":"1=platform, 2=tenant, 3=custom"},"isPlatformLevel":{"type":"boolean"},"isSystem":{"type":"boolean"},"parentRoleId":{"type":"string","nullable":true},"parentRoleName":{"type":"string","nullable":true},"tenantId":{"type":"string","nullable":true},"permissionSet":{"type":"array","items":{"type":"string"}},"userCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"}}},"RbacRoleCreateRequest":{"type":"object","required":["roleKey","roleName"],"properties":{"roleKey":{"type":"string","maxLength":64},"roleName":{"type":"string","maxLength":80},"roleDescription":{"type":"string","maxLength":400},"level":{"type":"integer","default":3},"isPlatformLevel":{"type":"boolean","default":false},"parentRoleId":{"type":"string","nullable":true},"permissionSet":{"type":"array","items":{"type":"string"}}}},"RbacRoleUpdateRequest":{"type":"object","properties":{"roleName":{"type":"string"},"roleDescription":{"type":"string"},"parentRoleId":{"type":"string","nullable":true},"permissionSet":{"type":"array","items":{"type":"string"}}},"allOf":[{"$ref":"#/components/schemas/RbacPermission"},{"type":"object","properties":{"fieldMask":{"type":"array","nullable":true,"items":{"type":"string"}},"grantedAt":{"type":"string","format":"date-time"},"grantedBy":{"type":"string","nullable":true}}}]},"RbacRolePermission":{"allOf":[{"$ref":"#/components/schemas/RbacPermission"},{"type":"object","properties":{"fieldMask":{"type":"array","nullable":true,"items":{"type":"string"}},"grantedAt":{"type":"string","format":"date-time"},"grantedBy":{"type":"string","nullable":true}}}]},"RbacRolePermissionsUpdateRequest":{"type":"object","properties":{"permissions":{"type":"array","items":{"type":"object","required":["permissionId","granted"],"properties":{"permissionId":{"type":"string"},"permissionKey":{"type":"string"},"granted":{"type":"boolean"},"fieldMask":{"type":"array","items":{"type":"string"}}}}},"fieldMasks":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}},"RbacUserRole":{"type":"object","properties":{"id":{"type":"string"},"userId":{"type":"string"},"userType":{"type":"string","enum":["broker","admin","prospect"]},"roleId":{"type":"string"},"roleKey":{"type":"string"},"roleName":{"type":"string"},"level":{"type":"integer"},"isPlatformLevel":{"type":"boolean"},"tenantId":{"type":"string","nullable":true},"tenantName":{"type":"string","nullable":true},"grantedBy":{"type":"string","nullable":true},"expiresAt":{"type":"string","format":"date-time","nullable":true},"isActive":{"type":"boolean"},"grantedAt":{"type":"string","format":"date-time"}}},"RbacAssignRoleRequest":{"type":"object","required":["roleId"],"properties":{"userType":{"type":"string","enum":["broker","admin","prospect"],"default":"broker"},"roleId":{"type":"string"},"tenantId":{"type":"string","nullable":true},"expiresAt":{"type":"string","format":"date-time","nullable":true}}},"RbacTeam":{"type":"object","properties":{"teamId":{"type":"string"},"tenantId":{"type":"string"},"teamName":{"type":"string"},"teamCode":{"type":"string","nullable":true},"parentTeamId":{"type":"string","nullable":true},"teamLeadId":{"type":"string","nullable":true},"teamLeadName":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"memberCount":{"type":"integer"},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}}},"RbacTeamCreateRequest":{"type":"object","required":["teamName"],"properties":{"teamName":{"type":"string","maxLength":120},"teamCode":{"type":"string","maxLength":40},"parentTeamId":{"type":"string"},"teamLeadId":{"type":"string"},"description":{"type":"string","maxLength":400}}},"RbacTeamMember":{"type":"object","properties":{"teamId":{"type":"string"},"brokerId":{"type":"string"},"fullName":{"type":"string"},"email":{"type":"string","format":"email"},"roleInTeam":{"type":"string","enum":["lead","member","observer"]},"yearsExperience":{"type":"integer","nullable":true},"customerRating":{"type":"number","nullable":true},"verified":{"type":"boolean"},"joinedAt":{"type":"string","format":"date-time"}}},"RbacAddTeamMemberRequest":{"type":"object","required":["brokerId"],"properties":{"brokerId":{"type":"string"},"roleInTeam":{"type":"string","enum":["lead","member","observer"],"default":"member"}}},"RbacAuditLog":{"type":"object","properties":{"id":{"type":"string"},"actorType":{"type":"string"},"actorId":{"type":"string","nullable":true},"tenantId":{"type":"string","nullable":true},"entityType":{"type":"string"},"entityId":{"type":"string"},"entityName":{"type":"string","nullable":true},"action":{"type":"string"},"changes":{"type":"object","additionalProperties":true},"ipAddress":{"type":"string","nullable":true},"userAgent":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"RbacTenant":{"type":"object","properties":{"tenantId":{"type":"string"},"name":{"type":"string"},"brandName":{"type":"string","nullable":true},"customDomain":{"type":"string","nullable":true},"subscriptionStatus":{"type":"string","enum":["active","paused","canceled","trial"],"nullable":true},"planKey":{"type":"string","nullable":true},"brokerCount":{"type":"integer"},"leads30d":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"}}},"FieldRef":{"description":"Reference to a certified extracted field. Returned in nodes / gaps / risk\nevidence so the UI can deep-link back to the document page or coordinates.\n","type":"object","required":["documentType","field"],"properties":{"documentType":{"type":"string","enum":["Contract","AnnualStatement","InforceIllustration","Rider","TermConversionNotice"]},"field":{"type":"string"},"value":{},"confidence":{"type":"number","nullable":true}}},"RiskEstimate":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"number"},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"ISO-4217 (USD, CAD, CNY)"},"formatted":{"type":"string","description":"Pre-formatted for display, e.g. \"$250,000\""}}},"BlockResponse":{"description":"409 shape for blocked reports (returnCycle / dividendTrack / termConversion).\n`suggestedReportId` points to the report that IS applicable for this product family.\n","type":"object","required":["error"],"properties":{"error":{"type":"string"},"product_family":{"type":"string","enum":["WholeLife","Term","UniversalLife","Annuity","Other"],"nullable":true},"suggestedReportId":{"type":"string","nullable":true},"data_grade":{"type":"string","enum":["A","B","C","D"],"nullable":true},"disclaimer":{"type":"string","nullable":true}}},"LeadSla":{"type":"object","required":["deadlineAt","remainingSeconds","breached"],"properties":{"deadlineAt":{"type":"string","format":"date-time"},"remainingSeconds":{"type":"integer"},"breached":{"type":"boolean"},"responseCount":{"type":"integer"},"firstResponseAt":{"type":"string","format":"date-time","nullable":true}}},"LeadEspoSync":{"type":"object","properties":{"synced":{"type":"boolean"},"espoLeadId":{"type":"string","nullable":true},"error":{"type":"string","nullable":true}}},"ServiceStatusDocumentIntake":{"type":"object","properties":{"upload":{"type":"string"},"process":{"type":"string"},"extractEngine":{"type":"string"},"certify":{"type":"string"},"architecture":{"type":"string"},"roadmap":{"type":"string"}}},"ServiceStatusReturnCycle":{"type":"object","properties":{"status":{"type":"string"},"projectionEngine":{"type":"string"},"opieUrl":{"type":"string","format":"uri"},"endpoints":{"type":"array","items":{"type":"string"}},"roadmap":{"type":"string"}}},"ServiceStatusReportEndpoint":{"type":"object","properties":{"status":{"type":"string"},"endpoints":{"type":"array","items":{"type":"string"}}}},"PaginatedMeta":{"type":"object","required":["total","limit","offset"],"properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"page":{"type":"integer","nullable":true},"pageSize":{"type":"integer","nullable":true}}},"Pagination":{"type":"object","required":["meta"],"properties":{"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}},"AssistantMessageBase":{"type":"object","required":["id","type","content","createdAt"],"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["user","ai","system"]},"content":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"attachments":{"type":"array","items":{"type":"string"}}}},"AssistantMessageUser":{"allOf":[{"$ref":"#/components/schemas/AssistantMessageBase"},{"type":"object","properties":{"type":{"type":"string","enum":["user"]}}}]},"AssistantMessageAi":{"allOf":[{"$ref":"#/components/schemas/AssistantMessageBase"},{"type":"object","required":["aiResponse"],"properties":{"type":{"type":"string","enum":["ai"]},"aiResponse":{"type":"object","required":["directAnswer","needProfessionalHelp","confidence"],"properties":{"directAnswer":{"type":"string"},"whyThisMatters":{"type":"string","nullable":true},"whatINoticed":{"type":"string","nullable":true},"whatToCheckNext":{"type":"array","items":{"type":"string"}},"needProfessionalHelp":{"type":"boolean"},"confidence":{"type":"number","minimum":0,"maximum":1}}}}}]},"AssistantMessage":{"oneOf":[{"$ref":"#/components/schemas/AssistantMessageUser"},{"$ref":"#/components/schemas/AssistantMessageAi"}],"discriminator":{"propertyName":"type","mapping":{"user":"#/components/schemas/AssistantMessageUser","ai":"#/components/schemas/AssistantMessageAi"}}},"AssistantConversationSummary":{"type":"object","required":["id","createdAt"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"lastMessageAt":{"type":"string","format":"date-time","nullable":true},"messageCount":{"type":"integer"}}},"AssistantConversationMessagesResponse":{"type":"object","required":["conversationId","messages","total","limit","offset"],"properties":{"conversationId":{"type":"string"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/AssistantMessage"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}},"AssistantSendMessageResponse":{"type":"object","required":["userMessage","aiMessage"],"properties":{"userMessage":{"$ref":"#/components/schemas/AssistantMessageUser"},"aiMessage":{"$ref":"#/components/schemas/AssistantMessageAi"}}},"IntakeFieldText":{"type":"object","required":["key","kind"],"properties":{"key":{"type":"string"},"kind":{"type":"string","enum":["text"]},"value":{"type":"string","nullable":true},"placeholder":{"type":"string","nullable":true}}},"IntakeFieldNumber":{"type":"object","required":["key","kind"],"properties":{"key":{"type":"string"},"kind":{"type":"string","enum":["number"]},"value":{"type":"number","nullable":true},"min":{"type":"number","nullable":true},"max":{"type":"number","nullable":true},"unit":{"type":"string","nullable":true}}},"IntakeFieldChoice":{"type":"object","required":["key","kind","options"],"properties":{"key":{"type":"string"},"kind":{"type":"string","enum":["choice"]},"options":{"type":"array","items":{"type":"string"},"minItems":1},"value":{"type":"string","nullable":true}}},"IntakeFieldBool":{"type":"object","required":["key","kind"],"properties":{"key":{"type":"string"},"kind":{"type":"string","enum":["bool"]},"value":{"type":"boolean","nullable":true}}},"IntakeField":{"description":"Discriminated by `kind` (text | number | choice | bool).","oneOf":[{"$ref":"#/components/schemas/IntakeFieldText"},{"$ref":"#/components/schemas/IntakeFieldNumber"},{"$ref":"#/components/schemas/IntakeFieldChoice"},{"$ref":"#/components/schemas/IntakeFieldBool"}],"discriminator":{"propertyName":"kind","mapping":{"text":"#/components/schemas/IntakeFieldText","number":"#/components/schemas/IntakeFieldNumber","choice":"#/components/schemas/IntakeFieldChoice","bool":"#/components/schemas/IntakeFieldBool"}}},"IntakeGap":{"type":"object","required":["type","priority"],"properties":{"type":{"type":"string"},"priority":{"type":"string","enum":["High","Medium","Low"]},"hint":{"type":"string"},"note":{"type":"string","nullable":true}}},"ReturnCycleRowActual":{"allOf":[{"$ref":"#/components/schemas/ReturnCycleRowBase"},{"type":"object","required":["row_type","row_source"],"properties":{"row_type":{"type":"string","enum":["Actual"]},"row_source":{"type":"string","enum":["actual"]},"note":{"type":"string","nullable":true}}}]},"ReturnCycleRowProjected":{"allOf":[{"$ref":"#/components/schemas/ReturnCycleRowBase"},{"type":"object","required":["row_type","row_source","assumption_type"],"properties":{"row_type":{"type":"string","enum":["Projected"]},"row_source":{"type":"string","enum":["illustration","opie","illustration+opie"]},"assumption_type":{"type":"string","enum":["Current","Guaranteed"]},"attained_age":{"type":"integer","nullable":true}}}]},"ReturnCycleRowBase":{"type":"object","required":["policy_year","row_type"],"properties":{"policy_year":{"type":"integer"},"calendar_year":{"type":"integer","nullable":true},"premium":{"type":"number","nullable":true},"cash_value":{"type":"number","nullable":true},"csv":{"type":"number","nullable":true},"death_benefit":{"type":"number","nullable":true}}},"ReturnCycleRow":{"description":"Discriminated by `row_type` (Actual | Projected).","oneOf":[{"$ref":"#/components/schemas/ReturnCycleRowActual"},{"$ref":"#/components/schemas/ReturnCycleRowProjected"}],"discriminator":{"propertyName":"row_type","mapping":{"Actual":"#/components/schemas/ReturnCycleRowActual","Projected":"#/components/schemas/ReturnCycleRowProjected"}}},"ReturnCycleSummary":{"type":"object","properties":{"cash_value_current":{"type":"number","nullable":true},"csv_current":{"type":"number","nullable":true},"death_benefit_current":{"type":"number","nullable":true},"latest_statement_year":{"type":"integer","nullable":true},"projected_lapse_year":{"type":"integer","nullable":true},"premium_offset_year":{"type":"integer","nullable":true}}},"ReturnCycleResponseFull":{"description":"Shape returned by /policies/{id}/reports/return-cycle. Mirrors\nbuildReturnCycle() in bff/packages/vpass-return-cycle.\n","type":"object","required":["policy_id","data_grade","rows","projection_source","disclaimer"],"properties":{"policy_id":{"type":"string"},"data_grade":{"type":"string","enum":["A","B","C","D"]},"summary":{"$ref":"#/components/schemas/ReturnCycleSummary"},"rows":{"type":"array","items":{"$ref":"#/components/schemas/ReturnCycleRow"}},"projection_source":{"type":"string","enum":["opie","unavailable"]},"disclaimer":{"type":"string"}}},"ReturnCycleKeyNodeBase":{"type":"object","required":["node_type","node_year","severity","source"],"properties":{"node_type":{"type":"string","enum":["ProjectedLapseYear","PremiumOffsetYear","SurrenderChargeEndsYear"]},"node_year":{"type":"integer"},"severity":{"type":"string","enum":["low","medium","high"]},"source":{"type":"string","enum":["Illustration","Contract"]},"evidence":{"$ref":"#/components/schemas/FieldRef","nullable":true}}},"ReturnCycleKeyNode":{"description":"Specific lifecycle node. `node_type` carries semantic meaning, severity drives UI emphasis.\n","$ref":"#/components/schemas/ReturnCycleKeyNodeBase"},"ReturnCycleKeyNodesResponse":{"type":"object","required":["policy_id","nodes"],"properties":{"policy_id":{"type":"string"},"nodes":{"type":"array","items":{"$ref":"#/components/schemas/ReturnCycleKeyNode"}},"warnings":{"type":"array","items":{"type":"string"}},"disclaimer":{"type":"string"}}},"ReturnCycleScenarioConservative":{"type":"object","required":["scenario_type","assumption_type"],"properties":{"scenario_type":{"type":"string","enum":["ConservativeAssumption"]},"assumption_type":{"type":"string","enum":["Current","Guaranteed"]},"scale_factor":{"type":"number","nullable":true,"description":"Subtract from crediting_rate_annual when assumption=Current"}}},"ReturnCycleScenario":{"$ref":"#/components/schemas/ReturnCycleScenarioConservative"},"ReturnCycleScenarioResponseFull":{"type":"object","required":["scenario_id","base_policy_id","scenario_type","assumption_type","projection_source"],"properties":{"scenario_id":{"type":"string"},"base_policy_id":{"type":"string"},"scenario_type":{"type":"string"},"scenario_label":{"type":"string"},"assumption_type":{"type":"string","enum":["Current","Guaranteed"]},"rows":{"type":"array","items":{"$ref":"#/components/schemas/ReturnCycleRow"}},"projection_source":{"type":"string","enum":["opie","unavailable"]}}},"DividendTrackRow":{"type":"object","required":["basis"],"properties":{"policy_year":{"type":"integer","nullable":true},"calendar_year":{"type":"integer","nullable":true},"cash_value":{"type":"number","nullable":true},"cash_surrender_value":{"type":"number","nullable":true},"dividend_amount":{"type":"number","nullable":true},"basis":{"type":"string","enum":["actual","illustrated","projected"]},"source":{"type":"string","enum":["AnnualStatement","Illustration","OPIE"]}}},"DividendTrackOpieSummary":{"type":"object","properties":{"product_code":{"type":"string","enum":["wl_nonpar","wl_par","term_20","term_30","iul"]},"ledger_year_end_cash":{"type":"number","nullable":true},"note":{"type":"string"}}},"DividendTrackSummary":{"type":"object","properties":{"policy_number":{"type":"string","nullable":true},"face_amount":{"type":"number","nullable":true},"latest_statement_year":{"type":"integer","nullable":true},"cash_value_current":{"type":"number","nullable":true},"cash_surrender_value":{"type":"number","nullable":true},"dividend_latest":{"type":"number","nullable":true}}},"DividendTrackResponseFull":{"type":"object","required":["policy_id","report_id","product_family","data_grade"],"properties":{"policy_id":{"type":"string"},"report_id":{"type":"string","enum":["RPT_DIVIDEND_TRACK"]},"product_family":{"type":"string","enum":["WholeLife","Term","UniversalLife","Annuity","Other"]},"data_grade":{"type":"string","enum":["A","B","C","D"]},"summary":{"$ref":"#/components/schemas/DividendTrackSummary"},"rows":{"type":"array","items":{"$ref":"#/components/schemas/DividendTrackRow"}},"opie_summary":{"$ref":"#/components/schemas/DividendTrackOpieSummary","nullable":true},"servicing_recommendations":{"type":"array","items":{"type":"string"}},"warnings":{"type":"array","items":{"type":"string"}},"disclaimer":{"type":"string"}}},"TermConversionDataSources":{"type":"object","properties":{"contract":{"type":"boolean"},"term_conversion_notice":{"type":"boolean"}}},"TermConversionEligibility":{"type":"object","properties":{"window_start":{"type":"string","format":"date","nullable":true},"expiry_date":{"type":"string","format":"date","nullable":true},"eligible_products":{"type":"array","items":{"type":"string"}},"data_sources":{"$ref":"#/components/schemas/TermConversionDataSources"}}},"TermConversionSummary":{"type":"object","properties":{"policy_number":{"type":"string","nullable":true},"face_amount":{"type":"number","nullable":true},"issue_date":{"type":"string","format":"date","nullable":true},"term_length_years":{"type":"integer"},"issue_age":{"type":"integer","nullable":true},"product_name":{"type":"string","nullable":true},"conversion_window_start":{"type":"string","format":"date","nullable":true},"conversion_expiry_date":{"type":"string","format":"date","nullable":true}}},"TermConversionResponseFull":{"type":"object","required":["policy_id","report_id","product_family","data_grade"],"properties":{"policy_id":{"type":"string"},"report_id":{"type":"string","enum":["RPT_TERM_CONVERSION"]},"product_family":{"type":"string","enum":["Term"]},"data_grade":{"type":"string","enum":["A","B","C","D"]},"summary":{"$ref":"#/components/schemas/TermConversionSummary"},"conversion":{"$ref":"#/components/schemas/TermConversionEligibility"},"servicing_recommendations":{"type":"array","items":{"type":"string"}},"warnings":{"type":"array","items":{"type":"string"}},"disclaimer":{"type":"string"}}},"HouseholdPolicySummary":{"type":"object","required":["id","policyType","dataGrade"],"properties":{"id":{"type":"string"},"policyNumber":{"type":"string"},"carrierName":{"type":"string"},"productName":{"type":"string"},"policyType":{"type":"string","enum":["WholeLife","Term","UniversalLife","Annuity","Other"]},"dataGrade":{"type":"string","enum":["A","B","C","D"]}}},"HouseholdPoliciesResponseV2":{"type":"object","required":["householdId","policies"],"properties":{"householdId":{"type":"string"},"policies":{"type":"array","items":{"$ref":"#/components/schemas/HouseholdPolicySummary"}}}},"BBox":{"description":"[x, y, x2, y2] in PDF point space (origin top-left).","type":"array","items":{"type":"number"},"minItems":4,"maxItems":4,"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}]},"DocumentFieldPreview":{"type":"object","required":["label","value","confidence"],"properties":{"label":{"type":"string"},"value":{"type":"string"},"confidence":{"type":"number","minimum":0,"maximum":1},"page":{"type":"integer","nullable":true},"bbox":{"$ref":"#/components/schemas/BBox","nullable":true}}},"DocumentJourneyStep":{"type":"object","required":["step","label","status"],"properties":{"step":{"type":"string","enum":["queued","uploaded","parsed","extracted","certified","failed"]},"label":{"type":"string"},"status":{"type":"string","enum":["done","current","pending","error"]},"at":{"type":"string","format":"date-time","nullable":true},"detail":{"type":"string","nullable":true}}},"AdvisorApplyFormField":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"value":{"type":"string"},"file":{"type":"string","format":"binary","nullable":true}}},"AdvisorApplyApplication":{"type":"object","properties":{"id":{"type":"string"},"applicantName":{"type":"string","nullable":true},"email":{"type":"string","format":"email","nullable":true},"phone":{"type":"string","nullable":true},"status":{"type":"string","enum":["submitted","reviewing","approved","rejected"]},"createdAt":{"type":"string","format":"date-time"}}},"BookAdvisorRequestV2":{"description":"Deprecated. Use BookAdvisorRequestV2. The `slot` / `preferred_slot` /\n`language` / `preferred_language` / `phone` / `notes` snake_case fields\nare kept for backward compat — prefer the camelCase siblings.\n","type":"object","required":["reportId"],"properties":{"reportId":{"type":"string"},"slot":{"type":"string","deprecated":true,"description":"ISO date or relative slot ref"},"preferredSlot":{"type":"string","description":"ISO date or relative slot ref"},"language":{"type":"string","deprecated":true},"preferredLanguage":{"type":"string"},"phone":{"type":"string"},"notes":{"type":"string","nullable":true}}},"RbacPermission":{"type":"object","required":["permissionId","permissionKey"],"properties":{"permissionId":{"type":"string"},"resourceType":{"type":"string"},"action":{"type":"string"},"permissionKey":{"type":"string"},"description":{"type":"string","nullable":true},"category":{"type":"string","nullable":true}}},"RbacRoleAssignment":{"type":"object","required":["userId","roleKey"],"properties":{"userId":{"type":"string"},"roleKey":{"type":"string"},"tenantId":{"type":"string","nullable":true},"grantedAt":{"type":"string","format":"date-time"},"grantedBy":{"type":"string","nullable":true}}},"RbacAuditEntry":{"type":"object","required":["id","action","actor","createdAt"],"properties":{"id":{"type":"string"},"action":{"type":"string","enum":["role_granted","role_revoked","permission_added","permission_removed","broker_added","broker_removed","tenant_created","tenant_updated"]},"actor":{"type":"string"},"target":{"type":"string","nullable":true},"meta":{"type":"object","additionalProperties":true,"nullable":true},"ipAddress":{"type":"string","nullable":true},"userAgent":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"AdvisorPublicSummary":{"type":"object","description":"Public summary of an advisor (PII masked)","required":["advisorId","displayName","specialties","acceptingClients"],"properties":{"advisorId":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid","nullable":true},"displayName":{"type":"string"},"headline":{"type":"string","nullable":true},"bio":{"type":"string","nullable":true},"avatarUrl":{"type":"string","format":"uri","nullable":true},"licenseState":{"type":"array","items":{"type":"string"}},"licenseNumber":{"type":"string","description":"Masked (e.g. xxxx-1234) in list responses"},"specialties":{"type":"array","items":{"type":"string"}},"yearsExperience":{"type":"integer","nullable":true},"rating":{"type":"number","format":"float","minimum":0,"maximum":5},"responseTimeHours":{"type":"integer","nullable":true},"totalClients":{"type":"integer"},"acceptingClients":{"type":"boolean"}}},"AdvisorPublicDetail":{"allOf":[{"$ref":"#/components/schemas/AdvisorPublicSummary"},{"type":"object","properties":{"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}]},"AdvisorReviewSummary":{"type":"object","required":["reviewId","rating","createdAt"],"properties":{"reviewId":{"type":"string","format":"uuid"},"rating":{"type":"integer","minimum":1,"maximum":5},"comment":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"AdvisorSlot":{"type":"object","required":["slotId","start","end"],"properties":{"slotId":{"type":"string","format":"uuid"},"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}}},"AdvisorInquiryCreated":{"type":"object","required":["inquiryId","status","createdAt"],"properties":{"inquiryId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["new","contacted","closed"]},"createdAt":{"type":"string","format":"date-time"}}},"AdvisorMatchSummary":{"type":"object","description":"Minimal advisor info shown in claim match result","required":["advisorId","displayName"],"properties":{"advisorId":{"type":"string","format":"uuid"},"displayName":{"type":"string"},"headline":{"type":"string","nullable":true},"avatarUrl":{"type":"string","format":"uri","nullable":true},"rating":{"type":"number","format":"float"},"responseTimeHours":{"type":"integer","nullable":true},"specialties":{"type":"array","items":{"type":"string"}}}},"ClaimTypeMeta":{"type":"object","required":["key","label","icon"],"properties":{"key":{"type":"string","enum":["auto_collision","auto_theft","home_fire","home_water","health_medical","life_death","disability","travel","liability"]},"label":{"type":"string"},"icon":{"type":"string"}}},"ClaimChecklistItem":{"type":"object","required":["key","label","required"],"properties":{"key":{"type":"string"},"label":{"type":"string"},"required":{"type":"boolean"},"onlyFor":{"type":"array","description":"When set, only applies to these claim types","items":{"type":"string"}}}},"Claim":{"type":"object","required":["claimId","userId","claimType","status"],"properties":{"claimId":{"type":"string","format":"uuid"},"userId":{"type":"string","format":"uuid"},"policyId":{"type":"string","format":"uuid","nullable":true},"claimType":{"type":"string"},"status":{"type":"string","enum":["draft","submitted","matching","in_progress","closed","denied"]},"incidentDate":{"type":"string","format":"date","nullable":true},"description":{"type":"string","nullable":true},"amountClaimed":{"type":"number","format":"float","nullable":true},"matchedAdvisorId":{"type":"string","format":"uuid","nullable":true},"matchedAt":{"type":"string","format":"date-time","nullable":true},"submittedAt":{"type":"string","format":"date-time","nullable":true},"closedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"ClaimCreate":{"type":"object","required":["claimType"],"properties":{"claimType":{"type":"string"},"incidentDate":{"type":"string","format":"date"},"description":{"type":"string"},"amountClaimed":{"type":"number","format":"float"},"policyId":{"type":"string","format":"uuid"}}},"ClaimPatch":{"type":"object","properties":{"description":{"type":"string"},"amountClaimed":{"type":"number","format":"float"},"incidentDate":{"type":"string","format":"date"},"policyId":{"type":"string","format":"uuid"},"matchedAdvisorId":{"type":"string","format":"uuid"}}},"ClaimDocument":{"type":"object","required":["claimDocId","claimId","documentId","uploadedAt"],"properties":{"claimDocId":{"type":"string","format":"uuid"},"claimId":{"type":"string","format":"uuid"},"documentId":{"type":"string","format":"uuid"},"docType":{"type":"string","nullable":true},"uploadedAt":{"type":"string","format":"date-time"}}},"ClaimTimelineEntry":{"type":"object","required":["eventType","at"],"properties":{"eventId":{"type":"string","format":"uuid"},"eventType":{"type":"string"},"data":{"type":"object","additionalProperties":true},"at":{"type":"string","format":"date-time"}}},"ConsumerProfile":{"type":"object","properties":{"consumer_id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email","nullable":true},"full_name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"locale":{"type":"string","nullable":true},"marketing_opt_in":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ConsumerProfilePatch":{"type":"object","properties":{"fullName":{"type":"string"},"phone":{"type":"string"},"locale":{"type":"string"},"marketingOptIn":{"type":"boolean"}}},"LifeEventCatalogItem":{"type":"object","required":["key","label","icon"],"properties":{"key":{"type":"string","enum":["married","baby","home_purchase","divorce","job_change","retirement","spouse_death","child_education","relocation","business_start","inheritance"]},"label":{"type":"string"},"icon":{"type":"string"}}},"UserLifeEvent":{"type":"object","required":["track_id","user_id","event_key","status"],"properties":{"track_id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"event_key":{"type":"string"},"custom_label":{"type":"string","nullable":true},"event_date":{"type":"string","format":"date","nullable":true},"status":{"type":"string","enum":["tracking","completed","archived"]},"progress":{"type":"object","additionalProperties":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"UserLifeEventCreate":{"type":"object","required":["eventKey"],"properties":{"eventKey":{"type":"string"},"customLabel":{"type":"string"},"eventDate":{"type":"string","format":"date"}}},"UserLifeEventPatch":{"type":"object","properties":{"status":{"type":"string","enum":["tracking","completed","archived"]},"progress":{"type":"object","additionalProperties":true},"eventDate":{"type":"string","format":"date"},"customLabel":{"type":"string"}}},"DashboardAttentionItem":{"type":"object","required":["type","title","severity"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"link":{"type":"string"},"severity":{"type":"string","enum":["low","medium","high"]},"createdAt":{"type":"string","format":"date-time"}}},"DashboardActivityItem":{"type":"object","required":["activity_type","ref_id","label","created_at"],"properties":{"activity_type":{"type":"string","enum":["document_upload","conversation","claim"]},"ref_id":{"type":"string"},"label":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"HouseholdMember":{"type":"object","required":["member_id","household_id","user_id","full_name"],"properties":{"member_id":{"type":"string","format":"uuid"},"household_id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"full_name":{"type":"string"},"relationship":{"type":"string","nullable":true},"date_of_birth":{"type":"string","format":"date","nullable":true},"ssn_last4":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"HouseholdMemberCreate":{"type":"object","required":["fullName"],"properties":{"fullName":{"type":"string"},"relationship":{"type":"string"},"dateOfBirth":{"type":"string","format":"date"},"ssnLast4":{"type":"string","maxLength":4}}},"MessageThread":{"type":"object","required":["thread_id","user_id","thread_type","status"],"properties":{"thread_id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"subject":{"type":"string","nullable":true},"thread_type":{"type":"string","enum":["support","advisor","claim","system"]},"status":{"type":"string","enum":["open","closed","archived"]},"last_message_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"Message":{"type":"object","required":["message_id","thread_id","sender_id","sender_type","content"],"properties":{"message_id":{"type":"string","format":"uuid"},"thread_id":{"type":"string","format":"uuid"},"sender_id":{"type":"string","format":"uuid"},"sender_type":{"type":"string","enum":["user","advisor","ai","system"]},"content":{"type":"string"},"attachments":{"type":"array","items":{"type":"object"}},"read_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"OAuthLoginRequest":{"type":"object","required":["idToken"],"properties":{"idToken":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"sub":{"type":"string"}}},"OAuthLoginResponse":{"type":"object","required":["token","user"],"properties":{"token":{"type":"string"},"user":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"fullName":{"type":"string"},"photoURL":{"type":"string","nullable":true},"provider":{"type":"string","enum":["google","apple"]},"oauthDemo":{"type":"boolean"}}},"isNew":{"type":"boolean"}}},"ProviderListResponse":{"type":"object","properties":{"providers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"supported":{"type":"boolean"}}}}}},"FieldReviewRequest":{"type":"object","properties":{"value":{"type":"string"},"confirmed":{"type":"boolean"}}},"FieldReviewResponse":{"type":"object","properties":{"policyId":{"type":"string"},"fieldKey":{"type":"string"},"value":{"type":"string"},"confirmed":{"type":"boolean"},"source":{"type":"string"}}},"ConfirmAllResponse":{"type":"object","properties":{"policyId":{"type":"string"},"total":{"type":"integer"},"reviewed":{"type":"integer"},"source":{"type":"string"}}},"AdoptRequest":{"type":"object","properties":{}},"AdoptResponse":{"type":"object","properties":{"policyId":{"type":"string"},"reviewStatus":{"type":"string","enum":["Adopted"]},"adoptedAt":{"type":"string","format":"date-time"}}},"CertifyRequest":{"type":"object","properties":{"notes":{"type":"string","maxLength":4000}}},"CertifyResponse":{"type":"object","properties":{"policyId":{"type":"string"},"reviewStatus":{"type":"string","enum":["Certified"]},"certifiedAt":{"type":"string","format":"date-time"}}},"PolicyMetadataPatch":{"type":"object","properties":{"planType":{"type":"string"},"notes":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}}}},"PolicyMetadataResponse":{"type":"object","properties":{"policyId":{"type":"string"},"planType":{"type":"string"},"notes":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}}}},"PolicyFieldsResponse":{"type":"object","properties":{"policyId":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"},"confidence":{"type":"number"},"source":{"type":"string"},"reviewed":{"type":"boolean"}}}},"legacyFieldsPreview":{"type":"array","items":{"type":"object"}},"certificationPending":{"type":"boolean"}}},"RenameConversationRequest":{"type":"object","required":["title"],"properties":{"title":{"type":"string","maxLength":200}}},"RenameConversationResponse":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"updated_at":{"type":"string","format":"date-time"}}},"SaveMessageRequest":{"type":"object","properties":{"conversationId":{"type":"string","format":"uuid"}}},"SaveMessageResponse":{"type":"object","properties":{"savedId":{"type":"string","nullable":true},"saved":{"type":"boolean"},"alreadySaved":{"type":"boolean"}}},"SavedMessageItem":{"type":"object","properties":{"savedId":{"type":"string"},"conversationId":{"type":"string"},"conversationTitle":{"type":"string"},"messageId":{"type":"string"},"content":{"type":"string"},"messageType":{"type":"string","enum":["user","ai","system"]},"aiResponse":{"type":"object","nullable":true},"savedAt":{"type":"string","format":"date-time"}}},"SavedMessagesResponse":{"type":"object","properties":{"saved":{"type":"array","items":{"$ref":"#/components/schemas/SavedMessageItem"}},"total":{"type":"integer"}}},"ReminderCreateRequest":{"type":"object","required":["remindAt"],"properties":{"conversationId":{"type":"string","format":"uuid"},"messageId":{"type":"string"},"remindAt":{"type":"string","format":"date-time"},"remindType":{"type":"string","enum":["one_time","daily","weekly"]}}},"ReminderItem":{"type":"object","properties":{"reminder_id":{"type":"string"},"user_id":{"type":"string"},"conversation_id":{"type":"string","nullable":true},"message_id":{"type":"string","nullable":true},"remind_at":{"type":"string","format":"date-time"},"remind_type":{"type":"string"},"status":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}},"ReminderCreateResponse":{"type":"object","properties":{"reminderId":{"type":"string"},"status":{"type":"string"},"remindAt":{"type":"string","format":"date-time"},"remindType":{"type":"string"}}},"ReminderListResponse":{"type":"object","properties":{"reminders":{"type":"array","items":{"$ref":"#/components/schemas/ReminderItem"}},"total":{"type":"integer"}}},"ActionPlanStep":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"done":{"type":"boolean"},"done_at":{"type":"string","format":"date-time","nullable":true}}},"ActionPlanCreateRequest":{"type":"object","required":["title"],"properties":{"conversationId":{"type":"string","format":"uuid"},"title":{"type":"string","maxLength":200},"description":{"type":"string"},"steps":{"type":"array","items":{"$ref":"#/components/schemas/ActionPlanStep"}},"dueAt":{"type":"string","format":"date-time"}}},"ActionPlanItem":{"type":"object","properties":{"plan_id":{"type":"string"},"user_id":{"type":"string"},"conversation_id":{"type":"string","nullable":true},"title":{"type":"string"},"description":{"type":"string","nullable":true},"steps":{"type":"array","items":{"$ref":"#/components/schemas/ActionPlanStep"}},"due_at":{"type":"string","format":"date-time","nullable":true},"completed_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ActionPlanCreateResponse":{"type":"object","properties":{"planId":{"type":"string"},"title":{"type":"string"},"status":{"type":"string","enum":["tracking"]},"createdAt":{"type":"string","format":"date-time"}}},"ActionPlanListResponse":{"type":"object","properties":{"plans":{"type":"array","items":{"$ref":"#/components/schemas/ActionPlanItem"}},"total":{"type":"integer"}}},"ActionPlanPatchRequest":{"type":"object","properties":{"steps":{"type":"array","items":{"$ref":"#/components/schemas/ActionPlanStep"}},"completed":{"type":"boolean"}}},"FollowUpCreateRequest":{"type":"object","required":["followUpAt"],"properties":{"conversationId":{"type":"string","format":"uuid"},"messageId":{"type":"string"},"followUpAt":{"type":"string","format":"date-time"},"followUpType":{"type":"string","enum":["check_in","progress","decision","renewal"]}}},"FollowUpCreateResponse":{"type":"object","properties":{"followUpId":{"type":"string"},"status":{"type":"string"},"followUpAt":{"type":"string","format":"date-time"},"followUpType":{"type":"string"}}},"FollowUpListResponse":{"type":"object","properties":{"followUps":{"type":"array","items":{"type":"object"}},"total":{"type":"integer"}}},"FollowUpPatchRequest":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["done","skipped","expired"]},"resultNote":{"type":"string"}}},"ClaimCloseRequest":{"type":"object","properties":{"finalNotes":{"type":"string","maxLength":4000}}},"ClaimDisputeRequest":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","minLength":10,"maxLength":4000}}},"ClaimReviewRequest":{"type":"object","required":["rating"],"properties":{"rating":{"type":"integer","minimum":1,"maximum":5},"comment":{"type":"string"}}},"HouseholdMemberPatch":{"type":"object","properties":{"fullName":{"type":"string"},"relationship":{"type":"string"},"dateOfBirth":{"type":"string","format":"date"},"ssnLast4":{"type":"string","minLength":4,"maxLength":4},"hasLife":{"type":"boolean"},"hasHealth":{"type":"boolean"},"notes":{"type":"string"}}},"PrivacySettingsResponse":{"type":"object","properties":{"privacy":{"type":"object","properties":{"share_aggregated_anonymous":{"type":"boolean"},"marketing_email":{"type":"boolean"},"marketing_sms":{"type":"boolean"},"search_visibility":{"type":"boolean"}}}}},"PrivacySettingsUpdateRequest":{"type":"object","properties":{"share_aggregated_anonymous":{"type":"boolean"},"marketing_email":{"type":"boolean"},"marketing_sms":{"type":"boolean"},"search_visibility":{"type":"boolean"}}},"SecuritySettingsResponse":{"type":"object","properties":{"twoFaEnabled":{"type":"boolean"},"passwordLastChangedAt":{"type":"string","format":"date-time","nullable":true},"activeSessions":{"type":"integer"}}},"ChangePasswordRequest":{"type":"object","required":["currentPassword","newPassword"],"properties":{"currentPassword":{"type":"string"},"newPassword":{"type":"string","minLength":8,"maxLength":200}}},"AvatarUploadRequest":{"type":"object","required":["dataUrl"],"properties":{"dataUrl":{"type":"string","description":"data URL e.g. data:image/png;base64,..."},"mimeType":{"type":"string","enum":["image/png","image/jpeg","image/webp"]}}},"AvatarUploadResponse":{"type":"object","properties":{"updated":{"type":"boolean"},"avatarUrl":{"type":"string"},"note":{"type":"string"}}},"DataExportResponse":{"type":"object","properties":{"userId":{"type":"string"},"exportedAt":{"type":"string","format":"date-time"},"profile":{"type":"object","nullable":true},"householdMembers":{"type":"array","items":{"type":"object"}},"claims":{"type":"array","items":{"type":"object"}}}},"AccountDeleteResponse":{"type":"object","properties":{"requestId":{"type":"string"},"scheduledPurgeAt":{"type":"string","format":"date-time"},"gracePeriodDays":{"type":"integer"},"cancelBefore":{"type":"string","format":"date-time"}}},"AccountDeleteCancelResponse":{"type":"object","properties":{"cancelled":{"type":"boolean"},"count":{"type":"integer"}}},"FeedbackRequest":{"type":"object","required":["body"],"properties":{"module":{"type":"string","maxLength":50},"rating":{"type":"integer","minimum":1,"maximum":5},"category":{"type":"string","enum":["bug","idea","question","praise","other"]},"body":{"type":"string","maxLength":4000},"contactAllowed":{"type":"boolean"},"contactEmail":{"type":"string","format":"email"},"pageUrl":{"type":"string"}}},"FeedbackCreateResponse":{"type":"object","properties":{"feedbackId":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"RenewalReminderItem":{"type":"object","properties":{"reminder_id":{"type":"string"},"user_id":{"type":"string"},"policy_id":{"type":"string","nullable":true},"carrier":{"type":"string","nullable":true},"policy_number":{"type":"string","nullable":true},"renewal_date":{"type":"string","format":"date"},"remind_in_days":{"type":"integer"},"notify_via":{"type":"array","items":{"type":"string"}},"status":{"type":"string"},"fired_at":{"type":"string","format":"date-time","nullable":true},"dismissed_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"RenewalReminderListResponse":{"type":"object","properties":{"list":{"type":"array","items":{"$ref":"#/components/schemas/RenewalReminderItem"}},"total":{"type":"integer"},"note":{"type":"string"}}},"RenewalReminderCreateRequest":{"type":"object","required":["renewalDate"],"properties":{"policyId":{"type":"string","format":"uuid"},"carrier":{"type":"string"},"policyNumber":{"type":"string"},"renewalDate":{"type":"string","format":"date"},"remindInDays":{"type":"integer","minimum":1,"maximum":180,"default":30},"notifyVia":{"type":"array","items":{"type":"string","enum":["email","sms","in_app","push"]}}}},"RenewalReminderPatchRequest":{"type":"object","properties":{"status":{"type":"string","enum":["active","fired","dismissed","completed"]},"renewalDate":{"type":"string","format":"date"},"remindInDays":{"type":"integer","minimum":1,"maximum":180},"notifyVia":{"type":"array","items":{"type":"string"}}}},"TwoFaEnableResponse":{"type":"object","properties":{"secret":{"type":"string"},"backupCodes":{"type":"array","items":{"type":"string"}},"otpauthUrl":{"type":"string"},"note":{"type":"string"}}},"TwoFaConfirmRequest":{"type":"object","required":["code"],"properties":{"code":{"type":"string","pattern":"^\\\\d{6}$"}}},"TwoFaConfirmResponse":{"type":"object","properties":{"enabled":{"type":"boolean"},"enabledAt":{"type":"string","format":"date-time"}}},"TwoFaDisableRequest":{"type":"object","required":["password"],"properties":{"password":{"type":"string"}}},"TwoFaDisableResponse":{"type":"object","properties":{"disabled":{"type":"boolean"}}},"PasswordResetRequestBody":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"}}},"PasswordResetRequestResponse":{"type":"object","properties":{"sent":{"type":"boolean"},"hint":{"type":"string"},"devToken":{"type":"string","description":"ONLY in dev/staging ??production returns 204 with email-only"},"expiresAt":{"type":"string","format":"date-time"}}},"PasswordResetConfirmRequest":{"type":"object","required":["token","newPassword"],"properties":{"token":{"type":"string"},"newPassword":{"type":"string","minLength":8}}},"MarkThreadReadResponse":{"type":"object","properties":{"markedRead":{"type":"integer"}}},"ThreadArchiveResponse":{"type":"object","properties":{"archived":{"type":"boolean"}}},"ThreadCloseResponse":{"type":"object","properties":{"closed":{"type":"boolean"}}},"AdvisorReviewCreateRequest":{"type":"object","required":["rating","body"],"properties":{"rating":{"type":"integer","minimum":1,"maximum":5},"title":{"type":"string","maxLength":200},"body":{"type":"string","minLength":10,"maxLength":4000},"bookingId":{"type":"string","format":"uuid"}}},"AdvisorReviewCreateResponse":{"type":"object","properties":{"reviewId":{"type":"string"},"rating":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"}}},"AdvisorAvailabilityResponse":{"type":"object","properties":{"advisorId":{"type":"string"},"availability":{"type":"array","items":{"type":"object","properties":{"slotId":{"type":"string"},"date":{"type":"string","format":"date"},"start":{"type":"string","format":"time"},"end":{"type":"string","format":"time"},"slotType":{"type":"string","enum":["video","phone","in_person"]},"status":{"type":"string","enum":["open","booked","blocked"]}}}},"total":{"type":"integer"},"note":{"type":"string"}}},"AdvisorBookingRequest":{"type":"object","required":["slotId"],"properties":{"slotId":{"type":"string","format":"uuid"},"notes":{"type":"string","maxLength":4000},"preferredLanguage":{"type":"string","maxLength":8}}},"AdvisorBookingResponse":{"type":"object","properties":{"bookingId":{"type":"string"},"slot":{"type":"object","properties":{"slotId":{"type":"string"},"date":{"type":"string","format":"date"},"start":{"type":"string","format":"time"}}},"status":{"type":"string","enum":["pending","confirmed","declined","completed"]}}},"Dto_ApiV1DocumentsIdProcess_POSTRequest":{"type":"object","properties":{"extractionTemplatePack":{"type":"string"}}},"Dto_ApiV1DocumentsIdFieldcoordinates_PUTRequest":{"type":"object","required":["fieldCoordinates"],"properties":{"fieldCoordinates":{"type":"object","additionalProperties":true}}},"Dto_ApiV1ProspectDocumentsUpload_POST201":{"type":"object","properties":{"upload":{"$ref":"#/components/schemas/DocumentUpload"},"autoProcessed":{"type":"boolean"},"message":{"type":"string"}}},"Dto_ApiV1ProspectDocumentsUploadsUploadId_GET200":{"type":"object","properties":{"upload":{"$ref":"#/components/schemas/DocumentUpload"}}},"Dto_ApiV1BrokerClientsClientId_GET200":{"type":"object","properties":{"client":{"$ref":"#/components/schemas/BrokerClient"}}},"Dto_ApiV1BrokerProspectuploadsUploadId_GET200":{"type":"object","properties":{"upload":{"$ref":"#/components/schemas/DocumentUpload"}}},"Dto_AdminRbacRoles_GET200":{"type":"object","properties":{"list":{"type":"array","items":{"$ref":"#/components/schemas/RbacRole"}},"total":{"type":"integer"}}},"Dto_AdminRbacRolesId_DELETE200":{"type":"object","properties":{"deleted":{"type":"boolean"}}},"Dto_AdminRbacPermissions_GET200":{"type":"object","properties":{"grouped":{"type":"object","additionalProperties":{"type":"array","items":{"$ref":"#/components/schemas/RbacPermission"}}},"list":{"type":"array","items":{"$ref":"#/components/schemas/RbacPermission"}},"total":{"type":"integer"}}},"Dto_AdminRbacRolesIdPermissions_GET200":{"type":"object","properties":{"list":{"type":"array","items":{"$ref":"#/components/schemas/RbacRolePermission"}},"total":{"type":"integer"}}},"Dto_AdminRbacRolesIdPermissions_PUT200":{"type":"object","properties":{"updated":{"type":"boolean"}}},"Dto_AdminRbacUsersUserIdRoles_GET200":{"type":"object","properties":{"list":{"type":"array","items":{"$ref":"#/components/schemas/RbacUserRole"}}}},"Dto_AdminRbacUsersUserIdRolesRoleId_DELETE200":{"type":"object","properties":{"revoked":{"type":"boolean"}}},"Dto_AdminRbacTeams_GET200":{"type":"object","properties":{"list":{"type":"array","items":{"$ref":"#/components/schemas/RbacTeam"}},"total":{"type":"integer"}}},"Dto_AdminRbacTeamsIdMembers_GET200":{"type":"object","properties":{"list":{"type":"array","items":{"$ref":"#/components/schemas/RbacTeamMember"}},"total":{"type":"integer"}}},"Dto_AdminRbacAudit_GET200":{"type":"object","properties":{"list":{"type":"array","items":{"$ref":"#/components/schemas/RbacAuditLog"}},"total":{"type":"integer"}}},"Dto_AdminRbacTenants_GET200":{"type":"object","properties":{"list":{"type":"array","items":{"$ref":"#/components/schemas/RbacTenant"}},"total":{"type":"integer"}}},"Dto_Advisordirectory_GET200":{"type":"object","required":["list","total","limit","offset"],"properties":{"list":{"type":"array","items":{"$ref":"#/components/schemas/AdvisorPublicSummary"}},"reviewCounts":{"type":"object","additionalProperties":{"type":"integer"},"description":"Map of advisorId -> review count"},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}},"Dto_AdvisordirectoryAdvisorId_GET200":{"type":"object","required":["advisor","reviews","ratingDistribution","totalReviews"],"properties":{"advisor":{"$ref":"#/components/schemas/AdvisorPublicDetail"},"reviews":{"type":"array","items":{"$ref":"#/components/schemas/AdvisorReviewSummary"}},"ratingDistribution":{"type":"object","description":"Map of rating (1-5) -> count","additionalProperties":{"type":"integer"}},"totalReviews":{"type":"integer"}}},"Dto_AdvisordirectoryAdvisorIdReviews_GET200":{"type":"object","required":["list","total"],"properties":{"list":{"type":"array","items":{"$ref":"#/components/schemas/AdvisorReviewSummary"}},"total":{"type":"integer"}}},"Dto_AdvisordirectoryAdvisorIdSlots_GET200":{"type":"object","required":["slots","total","days"],"properties":{"slots":{"type":"array","items":{"$ref":"#/components/schemas/AdvisorSlot"}},"total":{"type":"integer"},"days":{"type":"integer"}}},"Dto_AdvisordirectoryAdvisorIdContact_POSTRequest":{"type":"object","required":["message"],"properties":{"message":{"type":"string","minLength":10,"maxLength":2000}}},"Dto_ClientClaimsTypes_GET200":{"type":"object","required":["types","checklistTemplate"],"properties":{"types":{"type":"array","items":{"$ref":"#/components/schemas/ClaimTypeMeta"}},"checklistTemplate":{"type":"array","items":{"$ref":"#/components/schemas/ClaimChecklistItem"}}}},"Dto_ClientClaims_GET200":{"type":"object","required":["list","total","limit","offset"],"properties":{"list":{"type":"array","items":{"$ref":"#/components/schemas/Claim"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}},"Dto_ClientClaimsIdMatch_GET200":{"type":"object","required":["matched"],"properties":{"matched":{"type":"boolean"},"advisorId":{"type":"string","format":"uuid","nullable":true},"advisor":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/AdvisorMatchSummary"}]},"message":{"type":"string","description":"Human-readable note when matched=false or advisor=null"}}},"Dto_ClientClaimsIdDocuments_POSTRequest":{"type":"object","required":["documentId"],"properties":{"documentId":{"type":"string","format":"uuid"},"docType":{"type":"string","nullable":true,"description":"e.g. 'police_report', 'receipt', 'photo'"}}},"Dto_ClientClaimsIdTimeline_GET200":{"type":"object","required":["timeline"],"properties":{"timeline":{"type":"array","items":{"$ref":"#/components/schemas/ClaimTimelineEntry"}},"note":{"type":"string","description":"Set when timeline is derived from claim status (table not yet deployed)"}}},"Dto_ClientMe_GET200":{"type":"object","required":["user"],"properties":{"user":{"$ref":"#/components/schemas/ConsumerProfile"}}},"Dto_ClientMe_PATCH200":{"type":"object","required":["user"],"properties":{"user":{"$ref":"#/components/schemas/ConsumerProfile"}}},"Dto_ClientSettingsNotifications_GET200":{"type":"object","required":["notifications"],"properties":{"notifications":{"type":"object","additionalProperties":{"type":"boolean"}}}},"Dto_ClientSettingsNotifications_PUTRequest":{"type":"object","additionalProperties":{"type":"boolean"}},"Dto_ClientLifeeventsCatalog_GET200":{"type":"object","required":["catalog"],"properties":{"catalog":{"type":"array","items":{"$ref":"#/components/schemas/LifeEventCatalogItem"}}}},"Dto_ClientLifeevents_GET200":{"type":"object","required":["list","total"],"properties":{"list":{"type":"array","items":{"$ref":"#/components/schemas/UserLifeEvent"}},"total":{"type":"integer"},"note":{"type":"string","description":"Set when table not yet deployed"}}},"Dto_ClientLifeeventsIdWhy_GET200":{"type":"object","required":["eventKey","label","why","suggestedReviews"],"properties":{"eventKey":{"type":"string"},"label":{"type":"string"},"why":{"type":"string"},"suggestedReviews":{"type":"array","items":{"type":"string"}}}},"Dto_ClientDashboardAttention_GET200":{"type":"object","required":["items","total"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/DashboardAttentionItem"}},"total":{"type":"integer"}}},"Dto_ClientDashboardActivity_GET200":{"type":"object","required":["activities"],"properties":{"activities":{"type":"array","items":{"$ref":"#/components/schemas/DashboardActivityItem"}}}},"Dto_ClientHouseholdsIdMembers_GET200":{"type":"object","required":["list","total"],"properties":{"list":{"type":"array","items":{"$ref":"#/components/schemas/HouseholdMember"}},"total":{"type":"integer"},"note":{"type":"string"}}},"Dto_ClientMessagesThreads_GET200":{"type":"object","required":["list","total"],"properties":{"list":{"type":"array","items":{"$ref":"#/components/schemas/MessageThread"}},"total":{"type":"integer"},"note":{"type":"string"}}},"Dto_ClientMessagesThreads_POSTRequest":{"type":"object","properties":{"subject":{"type":"string","nullable":true},"threadType":{"type":"string","enum":["support","advisor","claim","system"],"default":"support"}}},"Dto_ClientMessagesThreadsIdMessages_GET200":{"type":"object","required":["list","total"],"properties":{"list":{"type":"array","items":{"$ref":"#/components/schemas/Message"}},"total":{"type":"integer"}}},"Dto_ClientMessagesThreadsIdMessages_POSTRequest":{"type":"object","required":["content"],"properties":{"content":{"type":"string"},"attachments":{"type":"array","items":{"type":"object"}}}},"Dto_ApiV1AuthOauthApple_POSTRequest":{"type":"object","required":["authorization"],"properties":{"authorization":{"type":"object","properties":{"id_token":{"type":"string"},"email":{"type":"string","format":"email"},"user":{"type":"object","properties":{"name":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"}}}}}}},"name":{"type":"string"}}},"Dto_ApiV1ClientAssistantMessagesMessageIdSave_DELETE200":{"type":"object","properties":{"unsaved":{"type":"boolean"}}},"Dto_ApiV1ClientAssistantRemindersId_DELETE200":{"type":"object","properties":{"dismissed":{"type":"boolean"}}},"Dto_ApiV1ClientAssistantFollowupsId_PATCH200":{"type":"object"},"Dto_ApiV1ClientClaimsIdClose_POST200":{"type":"object"},"Dto_ApiV1ClientClaimsIdDispute_POST200":{"type":"object"},"Dto_ApiV1ClientClaimsIdReopen_POST200":{"type":"object"},"Dto_ApiV1ClientClaimsIdReview_POST200":{"type":"object"},"Dto_ApiV1ClientHouseholdsIdMembersMemberId_PATCH200":{"type":"object"},"Dto_ApiV1ClientSettingsPrivacy_PUT200":{"type":"object","properties":{"updated":{"type":"boolean"}}},"Dto_ApiV1ClientMeChangepassword_POST200":{"type":"object","properties":{"updated":{"type":"boolean"}}},"Dto_ApiV1ClientAccount_DELETERequest":{"type":"object","properties":{"reason":{"type":"string","maxLength":2000}}},"Dto_ApiV1ClientRenewalremindersId_DELETE200":{"type":"object","properties":{"deleted":{"type":"boolean"}}},"Dto_ApiV1ClientPasswordresetConfirm_POST200":{"type":"object","properties":{"updated":{"type":"boolean"}}},"Dto_ApiV1ClientNotifications_GET200":{"type":"object","required":["notifications","total"],"properties":{"notifications":{"type":"array","items":{"$ref":"#/components/schemas/Notification"}},"total":{"type":"integer"}}},"Dto_ApiV1ClientNotificationsUnreadcount_GET200":{"type":"object","required":["count"],"properties":{"count":{"type":"integer","minimum":0}}},"Dto_ApiV1ClientNotificationsReadall_POST200":{"type":"object","required":["ok","updated"],"properties":{"ok":{"type":"boolean"},"updated":{"type":"integer"}}},"Dto_ApiV1ClientNotificationsIdRead_POST200":{"type":"object","required":["ok","updated"],"properties":{"ok":{"type":"boolean"},"updated":{"type":"integer"}}},"Dto_ApiV1Client2faRecoverycodes_GET200":{"type":"object","required":["total","unused","used"],"properties":{"total":{"type":"integer"},"unused":{"type":"integer"},"used":{"type":"integer"}}},"Dto_ApiV1Client2faRecoverycodesRegenerate_POST201":{"type":"object","required":["recoveryCodes","total"],"properties":{"recoveryCodes":{"type":"array","items":{"type":"string","pattern":"^[A-Z0-9]{8}$"},"minItems":10,"maxItems":10},"total":{"type":"integer"}}},"Dto_ApiV1Client2faRecover_POSTRequest":{"type":"object","required":["code"],"properties":{"code":{"type":"string","pattern":"^[A-Z0-9]{8}$"}}},"Dto_ApiV1Client2faRecover_POST200":{"type":"object","required":["recovered","remaining"],"properties":{"recovered":{"type":"boolean"},"remaining":{"type":"integer"}}},"Dto_ApiV1BrokerAuthLogin_POSTRequest":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":8}}},"Dto_ApiV1BrokerAuthLogin_POST200":{"type":"object","required":["token","broker"],"properties":{"token":{"type":"string"},"broker":{"$ref":"#/components/schemas/BrokerPublic"}}},"Dto_ApiV1BrokerAuthRegister_POSTRequest":{"type":"object","required":["email","password","fullName"],"properties":{"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":8},"fullName":{"type":"string"},"licenseState":{"type":"string","maxLength":2},"licenseNumber":{"type":"string","maxLength":20},"yearsExperience":{"type":"integer","minimum":0,"maximum":60},"headline":{"type":"string"},"bio":{"type":"string"}}},"Dto_ApiV1BrokerAuthRegister_POST201":{"type":"object","required":["pendingApproval","message","broker"],"properties":{"pendingApproval":{"type":"boolean","const":true},"message":{"type":"string"},"broker":{"$ref":"#/components/schemas/BrokerPublic"}}},"Dto_ApiV1BrokerAuthRegistrationstatus_GET200":{"type":"object","required":["exists"],"properties":{"exists":{"type":"boolean"},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["pending_approval","approved","rejected","suspended"]}}},"BillingPlan":{"type":"object","properties":{"code":{"type":"string","enum":["starter","professional","enterprise"]},"label":{"type":"string"},"interval":{"type":"string","enum":["month","year"]},"amountCents":{"type":"integer"},"currency":{"type":"string","default":"USD"},"marketingPrice":{"type":"string","description":"$29/mo 形式"},"priceIdEnv":{"type":"string","description":"STRIPE_PRICE_* 环境变量名"},"checkoutHref":{"type":"string"}}},"BillingCheckoutSession":{"type":"object","required":["orderId","orderNo","checkoutUrl"],"properties":{"orderId":{"type":"string","format":"uuid"},"orderNo":{"type":"string","description":"ORD2026072512345 格式"},"checkoutUrl":{"type":"string"},"sessionId":{"type":"string"},"status":{"type":"string","enum":["Pending"]},"mode":{"type":"string","enum":["stripe_subscription_via_unipay","stripe_subscription_direct"]},"stripeCustomerId":{"type":"string"},"stripePriceId":{"type":"string"},"planCode":{"type":"string"},"planInterval":{"type":"string","enum":["month","year"]}}},"Order":{"type":"object","properties":{"order_id":{"type":"string","format":"uuid"},"order_no":{"type":"string"},"broker_id":{"type":"string","format":"uuid"},"portal_user_id":{"type":"string","format":"uuid"},"plan_code":{"type":"string"},"plan_interval":{"type":"string","enum":["month","year","manual"]},"currency":{"type":"string"},"amount_total":{"type":"number"},"status":{"type":"string","enum":["Draft","Pending","Paid","Payment_Failed","Canceled","Refunded"]},"stripe_customer_id":{"type":"string","nullable":true},"stripe_subscription_id":{"type":"string","nullable":true},"stripe_invoice_id":{"type":"string","nullable":true},"stripe_price_id":{"type":"string","nullable":true},"paid_at":{"type":"string","format":"date-time","nullable":true},"canceled_at":{"type":"string","format":"date-time","nullable":true},"refunded_at":{"type":"string","format":"date-time","nullable":true},"failure_reason":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Subscription":{"type":"object","properties":{"subscription_id":{"type":"string","format":"uuid"},"broker_id":{"type":"string","format":"uuid"},"order_id":{"type":"string","format":"uuid"},"plan_code":{"type":"string"},"plan_interval":{"type":"string"},"stripe_customer_id":{"type":"string"},"stripe_subscription_id":{"type":"string"},"status":{"type":"string","enum":["Draft","Pending","Trial","Active","PastDue","Canceled","Expired"]},"current_period_start":{"type":"string","format":"date-time"},"current_period_end":{"type":"string","format":"date-time"},"cancel_at":{"type":"string","format":"date-time","nullable":true}}},"Payout":{"type":"object","properties":{"payout_id":{"type":"string","format":"uuid"},"broker_id":{"type":"string","format":"uuid"},"amount_total":{"type":"number"},"currency":{"type":"string"},"status":{"type":"string","enum":["Pending","Processing","Paid","Failed","Canceled"]},"requested_at":{"type":"string","format":"date-time"},"processed_at":{"type":"string","format":"date-time","nullable":true}}},"LeadMarketplaceMasked":{"type":"object","properties":{"marketplace_id":{"type":"string","format":"uuid"},"primary_state":{"type":"string"},"contact_name":{"type":"string"},"contact_email_masked":{"type":"string","description":"ab***@x.com 形式"},"contact_phone_masked":{"type":"string","description":"415****0000 形式"},"lead_grade":{"type":"string","enum":["A","B","C","D"]},"protection_score":{"type":"integer","nullable":true},"scenario":{"type":"string"},"scenario_label":{"type":"string"},"unlock_fee_cents":{"type":"integer","default":0},"unlocked_count":{"type":"integer"},"created_at":{"type":"string","format":"date-time"}}},"LeadMarketplaceFull":{"allOf":[{"$ref":"#/components/schemas/LeadMarketplaceMasked"},{"type":"object","properties":{"contact_email":{"type":"string","description":"完整联系方式，仅 admin / unlock 后可见"},"contact_phone":{"type":"string"},"intake_json":{"type":"object"},"visibility":{"type":"string","enum":["private","public_pool","invited_only"]},"unlocked_by":{"type":"array","items":{"type":"object"}}}}]},"AuditLog":{"type":"object","properties":{"audit_id":{"type":"string","format":"uuid"},"actor_id":{"type":"string","format":"uuid","nullable":true},"actor_role":{"type":"string","enum":["coverfy-staff","super_broker","broker","agent","client","anonymous"]},"tenant_id":{"type":"string","format":"uuid","nullable":true},"action":{"type":"string"},"method":{"type":"string","enum":["POST","PATCH","DELETE"]},"path":{"type":"string"},"target_type":{"type":"string","nullable":true},"target_id":{"type":"string","nullable":true},"ip":{"type":"string","nullable":true},"user_agent":{"type":"string","nullable":true},"request_id":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"CrmUserInfo":{"type":"object","description":"对齐前端 API.USERMANAGEMENT（camelCase + snake_case 双写）","properties":{"user_id":{"type":"string","format":"uuid"},"userId":{"type":"string","format":"uuid"},"user_name":{"type":"string"},"email":{"type":"string"},"cn_name":{"type":"string"},"fullName":{"type":"string"},"avatar_url":{"type":"string"},"phone":{"type":"string"},"userType":{"type":"string","enum":["broker","agent","platform_admin"]},"tenantId":{"type":"string","format":"uuid"},"parentBrokerId":{"type":"string","format":"uuid","nullable":true},"firmName":{"type":"string"},"isActive":{"type":"boolean"},"status":{"type":"integer"}}},"CrmLoginResponse":{"type":"object","properties":{"token":{"type":"string"},"user_id":{"type":"string"},"user_name":{"type":"string"},"email":{"type":"string"},"userType":{"type":"string"},"tenantId":{"type":"string"},"fullName":{"type":"string"}}},"CrmMenuNode":{"type":"object","properties":{"menu_id":{"type":"string"},"name":{"type":"string"},"menu_type":{"type":"integer"},"path":{"type":"string"},"icon":{"type":"string"},"component":{"type":"string"},"hideChildrenInMenu":{"type":"integer"},"hideInMenu":{"type":"integer"},"hideInBreadcrumb":{"type":"integer"},"headerRender":{"type":"integer"},"footerRender":{"type":"integer"},"menuRender":{"type":"integer"},"menuHeaderRender":{"type":"integer"},"flatMenu":{"type":"integer"},"fixedHeader":{"type":"integer"},"fixSiderbar":{"type":"integer"},"routes":{"type":"array","items":{"$ref":"#/components/schemas/CrmMenuNode"}}}},"CrmBusinessOverview":{"type":"object","properties":{"leads":{"type":"integer"},"mainLeads":{"type":"integer"},"quotes":{"type":"integer"},"opportunities":{"type":"integer"},"bookings":{"type":"integer"},"scope":{"type":"object","properties":{"userType":{"type":"string"},"tenantId":{"type":"string","nullable":true},"isAgent":{"type":"boolean"}}}}},"CrmBusinessLeads":{"type":"object","properties":{"leads":{"type":"array","items":{"type":"object","properties":{"lead_id":{"type":"string","format":"uuid"},"tenant_id":{"type":"string","format":"uuid","nullable":true},"broker_id":{"type":"string","format":"uuid","nullable":true},"full_name":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"},"line_of_business":{"type":"string"},"source":{"type":"string"},"status":{"type":"string"},"estimated_value":{"type":"number","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}}}},"total":{"type":"integer"},"scope":{"type":"object","properties":{"userType":{"type":"string"},"perAgentId":{"type":"string","nullable":true}}}}},"CrmBusinessAgent":{"type":"object","properties":{"brokerId":{"type":"string","format":"uuid"},"email":{"type":"string"},"fullName":{"type":"string"},"userType":{"type":"string"},"tenantId":{"type":"string"},"parentBrokerId":{"type":"string","nullable":true},"isActive":{"type":"boolean"},"createdAt":{"type":"string"}}}},"parameters":{"BrokerIdHeader":{"name":"X-Broker-Id","in":"header","required":false,"schema":{"type":"string"}},"TenantIdHeader":{"name":"X-Tenant-Id","in":"header","required":false,"schema":{"type":"string"}},"DateParam":{"name":"date","in":"query","required":false,"schema":{"type":"string","description":"YYYY-MM-DD or \"today\" or \"all\""}},"LimitParam":{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20,"maximum":500}},"PageParam":{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1,"minimum":1}}},"responses":{"Unauthorized":{"description":"Missing or invalid auth","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"Authenticated but lacking permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ValidationError":{"description":"Request body or params failed validation","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"array","items":{"type":"string"}}}}}}},"RateLimited":{"description":"Rate-limited (OTP send, etc.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"BadRequest":{"description":"Bad request (invalid body / params)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotDeployed":{"description":"Underlying table not yet deployed in DB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/":{"get":{"summary":"BFF index (HTML)","description":"Human-friendly landing page with links to portals and health.","security":[],"tags":["service"],"responses":{"200":{"description":"HTML page","content":{"text/html":{}}}}}},"/health":{"get":{"summary":"Liveness + dependency health","tags":["service"],"security":[],"responses":{"200":{"description":"All dependencies reachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthCheck"}}}},"503":{"description":"Degraded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthCheck"}}}}}}},"/api/v1/status":{"get":{"summary":"API catalog (which endpoints are mounted)","tags":["service"],"security":[],"responses":{"200":{"description":"Status payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceStatus"}}}}}}},"/api/v1/espocrm/ping":{"get":{"summary":"Ping EspoCRM connectivity","tags":["espocrm","espocrm.ping"],"security":[],"responses":{"200":{"description":"EspoCRM reachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EspoPing"}}}}}}},"/api/v1/documents/upload":{"post":{"summary":"Upload a policy document (advisor side)","tags":["documents","documents.upload"],"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file","policyId"],"properties":{"file":{"type":"string","format":"binary"},"policyId":{"type":"string"},"documentType":{"type":"string","enum":["Contract","AnnualStatement","InforceIllustration","Rider"],"default":"Contract"},"version":{"type":"integer","default":1},"autoProcess":{"type":"boolean"},"extractionTemplatePack":{"type":"string"}}}}}},"responses":{"201":{"description":"Document accepted (and possibly processed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolicyDocumentUploadResponse"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"description":"Duplicate file (SHA-256 already on record)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/documents/{id}":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string"}},"tags":["documents"]},"get":{"summary":"Get document by id","tags":["documents"],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Document record (with presigned download URL)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolicyDocument"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/documents/{id}/process":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string"}},"tags":["documents","documents.process"]},"post":{"summary":"Run extraction pipeline on a queued document","tags":["documents","documents.process"],"security":[{"apiKey":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ApiV1DocumentsIdProcess_POSTRequest"}}}},"responses":{"201":{"description":"Processed result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolicyDocumentUploadResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/documents/{id}/field-coordinates":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string"}},"tags":["documents","documents.field-coordinates"]},"get":{"summary":"Read the field coordinates for a document","tags":["documents","documents.field-coordinates"],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Field coordinates payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolicyFieldCoordinates"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"summary":"Replace field coordinates (advisor-corrected)","tags":["documents","documents.field-coordinates"],"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ApiV1DocumentsIdFieldcoordinates_PUTRequest"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolicyFieldCoordinates"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/documents/{id}/certify":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string"}},"tags":["documents","documents.certify"]},"post":{"summary":"Certify document fields (advisor sign-off, gates downstream reports)","tags":["documents","documents.certify"],"security":[{"apiKey":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolicyCertifyRequest"}}}},"responses":{"200":{"description":"Certified","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolicyCertifyResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Certification blocked (missing fields or cross-validation failures)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/policies/{id}":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string"}},"tags":["policies"]},"get":{"summary":"Get policy by id","tags":["policies"],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Policy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Policy"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/policies/{id}/documents":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string"}},"tags":["policies","policies.documents"]},"get":{"summary":"List documents attached to a policy","tags":["policies","policies.documents"],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Documents list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolicyDocumentsResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/policies/{id}/return-cycle":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string"}},"1":{"name":"includeActual","in":"query","schema":{"type":"boolean","default":true}},"2":{"name":"includeProjected","in":"query","schema":{"type":"boolean","default":true}},"3":{"name":"projectionAssumption","in":"query","schema":{"type":"string","enum":["Current","Guaranteed"],"default":"Current"}},"tags":["policies","policies.return-cycle"]},"get":{"summary":"Build return-cycle report (OPIE-powered)","tags":["policies","policies.return-cycle"],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Return cycle nodes + summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnCycleResponse"}}}},"409":{"description":"Not applicable for this product family","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/policies/{id}/return-cycle/nodes":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string"}},"tags":["policies","policies.return-cycle"]},"get":{"summary":"Key nodes only (cheaper than full cycle)","tags":["policies","policies.return-cycle"],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Key nodes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnCycleNodesResponse"}}}}}}},"/api/v1/policies/{id}/return-cycle/scenarios":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string"}},"tags":["policies","policies.return-cycle"]},"post":{"summary":"Apply a what-if scenario on top of the base cycle","tags":["policies","policies.return-cycle"],"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnCycleScenariosRequest"}}}},"responses":{"200":{"description":"Scenario result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnCycleScenarioResponse"}}}},"409":{"description":"Not applicable for product family","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/api/v1/policies/{id}/term-conversion":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string"}},"tags":["policies","policies.term-conversion"]},"get":{"summary":"Build term-conversion report (Term products only)","tags":["policies","policies.term-conversion"],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Term conversion options","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TermConversionResponse"}}}},"409":{"description":"Not applicable for product family","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/policies/{id}/dividend-track":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string"}},"1":{"name":"includeOpie","in":"query","schema":{"type":"boolean","default":true}},"tags":["policies","policies.dividend-track"]},"get":{"summary":"Build dividend-track report (WholeLife products only)","tags":["policies","policies.dividend-track"],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Dividend history + projection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DividendTrackResponse"}}}},"409":{"description":"Not applicable for product family","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/households/{id}/policies":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string"}},"tags":["households","households.policies"]},"get":{"summary":"List policies for a household","tags":["households","households.policies"],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Policies","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HouseholdPoliciesResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/prospect/intake/session":{"post":{"summary":"Create a new intake session","description":"Returns a sessionId used for the rest of the intake flow.","tags":["prospect","prospect.intake"],"security":[],"responses":{"201":{"description":"Session created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntakeSessionCreateResponse"}}}}}}},"/api/v1/prospect/intake/{sessionId}":{"parameters":{"0":{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"}},"tags":["prospect","prospect.intake"]},"patch":{"summary":"Patch intake fields (partial update)","tags":["prospect","prospect.intake"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntakeSessionPatchRequest"}}}},"responses":{"200":{"description":"Updated session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntakeSessionResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/prospect/intake/chat":{"post":{"summary":"Send a chat message to the intake orchestrator (LLM)","tags":["prospect","prospect.intake"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntakeChatRequest"}}}},"responses":{"200":{"description":"Chat reply with chip options","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntakeChatResponse"}}}},"422":{"$ref":"#/components/responses/ValidationError"},"500":{"description":"Orchestrator failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/prospect/intake/{sessionId}/preview":{"parameters":{"0":{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"}},"tags":["prospect","prospect.intake"]},"get":{"summary":"Get the (gated) preview for the current session","tags":["prospect","prospect.intake"],"security":[],"responses":{"200":{"description":"Preview payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntakePreview"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/prospect/auth/otp/send":{"post":{"summary":"Send OTP via SMS","tags":["prospect","prospect.auth"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OtpSendRequest"}}}},"responses":{"200":{"description":"OTP challenge issued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OtpSendResponse"}}}},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/prospect/auth/otp/verify":{"post":{"summary":"Verify OTP and issue session token","tags":["prospect","prospect.auth"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OtpVerifyRequest"}}}},"responses":{"200":{"description":"Authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OtpVerifyResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/api/v1/prospect/followup/intake-call/next":{"get":{"summary":"Voice-worker pulls next queued intake follow-up call","tags":["prospect","prospect.followup"],"security":[{"voiceWorkerKey":[]}],"responses":{"200":{"description":"Job payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntakeFollowUpJob"}}}},"204":{"description":"Queue empty"}}}},"/api/v1/prospect/register":{"post":{"summary":"Register a new prospect (and create household + lead in EspoCRM)","tags":["prospect","prospect.register"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterRequest"}}}},"responses":{"201":{"description":"Account created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginResponse"}}}},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/api/v1/prospect/login":{"post":{"summary":"Login (email + password)","tags":["prospect","prospect.login"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginRequest"}}}},"responses":{"200":{"description":"Authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginResponse"}}}},"401":{"description":"Invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/prospect/me":{"get":{"summary":"Current user (Bearer or X-Prospect-Token)","tags":["prospect","prospect.profile"],"security":[{"bearerAuth":[]},{"prospectTokenHeader":[]}],"responses":{"200":{"description":"User","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/prospect/invite/{token}":{"parameters":{"0":{"name":"token","in":"path","required":true,"schema":{"type":"string"}},"tags":["prospect","prospect.invite"]},"get":{"summary":"Resolve a broker-issued invite token","tags":["prospect","prospect.invite"],"security":[],"responses":{"200":{"description":"Invite details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InviteResponse"}}}},"404":{"description":"Invite not found or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/prospect/reports/{reportId}":{"parameters":{"0":{"name":"reportId","in":"path","required":true,"schema":{"type":"string"}},"tags":["prospect","prospect.reports"]},"get":{"summary":"Get a full report (must be the report owner)","tags":["prospect","prospect.reports"],"security":[{"bearerAuth":[]},{"prospectTokenHeader":[]}],"responses":{"200":{"description":"Report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Report"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/prospect/reports/{reportId}/pdf":{"parameters":{"0":{"name":"reportId","in":"path","required":true,"schema":{"type":"string"}},"tags":["prospect","prospect.reports"]},"get":{"summary":"Render report as HTML (for browser print-to-PDF)","tags":["prospect","prospect.reports"],"security":[{"bearerAuth":[]},{"prospectTokenHeader":[]}],"responses":{"200":{"description":"HTML document","content":{"text/html":{}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/prospect/book-advisor":{"post":{"summary":"Book an advisor call (creates a lead, syncs to EspoCRM)","tags":["prospect","prospect.book-advisor"],"security":[{"bearerAuth":[]},{"prospectTokenHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookAdvisorRequest"}}}},"responses":{"201":{"description":"Lead created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookAdvisorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/api/v1/prospect/leads/today":{"get":{"summary":"Today's leads (internal use)","tags":["prospect","prospect.leads"],"security":[],"responses":{"200":{"description":"Today's leads","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadsTodayResponse"}}}}}}},"/api/v1/prospect/documents/upload":{"post":{"summary":"Upload a personal policy document (consumer side)","tags":["prospect","prospect.documents"],"security":[{"bearerAuth":[]},{"prospectTokenHeader":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file","documentType"],"properties":{"file":{"type":"string","format":"binary"},"documentType":{"type":"string","enum":["contract","annual","illustration","rider"],"default":"contract"}}}}}},"responses":{"201":{"description":"Upload accepted (auto-processed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ApiV1ProspectDocumentsUpload_POST201"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"503":{"description":"Storage unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/prospect/documents/uploads":{"get":{"summary":"List the current user's uploads","tags":["prospect","prospect.documents"],"security":[{"bearerAuth":[]},{"prospectTokenHeader":[]}],"responses":{"200":{"description":"Upload list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadsListResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/prospect/documents/uploads/{uploadId}":{"parameters":{"0":{"name":"uploadId","in":"path","required":true,"schema":{"type":"string"}},"tags":["prospect","prospect.documents"]},"get":{"summary":"Get an upload by id (owner only)","tags":["prospect","prospect.documents"],"security":[{"bearerAuth":[]},{"prospectTokenHeader":[]}],"responses":{"200":{"description":"Upload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ApiV1ProspectDocumentsUploadsUploadId_GET200"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/prospect/documents/uploads/{uploadId}/journey":{"parameters":{"0":{"name":"uploadId","in":"path","required":true,"schema":{"type":"string"}},"tags":["prospect","prospect.documents"]},"get":{"summary":"Lifecycle timeline for an upload","tags":["prospect","prospect.documents"],"security":[{"bearerAuth":[]},{"prospectTokenHeader":[]}],"responses":{"200":{"description":"Journey","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadJourneyResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/broker/leads":{"parameters":{"0":{"$ref":"#/components/parameters/DateParam"},"1":{"name":"scope","in":"query","schema":{"type":"string","enum":["pool","mine","all"],"default":"pool"}},"2":{"name":"pool","in":"query","schema":{"type":"string","enum":["0","1"]}},"3":{"name":"masked","in":"query","schema":{"type":"string","enum":["0","1"]}},"4":{"name":"country","in":"query","schema":{"type":"string"}},"5":{"name":"region","in":"query","schema":{"type":"string"}},"6":{"name":"grade","in":"query","schema":{"type":"string","enum":["A","B","C","D"]}},"7":{"name":"city","in":"query","schema":{"type":"string"}},"tags":["broker","broker.leads"]},"get":{"summary":"Lead pool / my-leads / all-leads list","tags":["broker","broker.leads"],"security":[{"apiKey":[]},{"brokerContext":[]}],"responses":{"200":{"description":"Leads list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadsListResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/broker/prospect-pool":{"parameters":{"0":{"name":"limit","in":"query","schema":{"type":"integer","default":500,"maximum":1000}},"1":{"name":"sort","in":"query","schema":{"type":"string","enum":["sameCity",""]}},"2":{"name":"city","in":"query","schema":{"type":"string"}},"tags":["broker","broker.prospect-pool"]},"get":{"summary":"Admin/ops masked prospect pool view","tags":["broker","broker.prospect-pool"],"security":[{"apiKey":[]},{"brokerContext":[]}],"responses":{"200":{"description":"Masked prospects","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProspectPoolResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/broker/clients":{"get":{"summary":"List clients owned by the current broker","tags":["broker","broker.clients"],"security":[{"apiKey":[]},{"brokerContext":[]}],"responses":{"200":{"description":"Clients","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrokerClientsListResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"summary":"Create a broker client (also creates a Lead)","tags":["broker","broker.clients"],"security":[{"apiKey":[]},{"brokerContext":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrokerClientCreateRequest"}}}},"responses":{"201":{"description":"Client + lead created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrokerClientCreateResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/api/v1/broker/clients/{clientId}":{"parameters":{"0":{"name":"clientId","in":"path","required":true,"schema":{"type":"string"}},"tags":["broker","broker.clients"]},"get":{"summary":"Get a single client (must be owner)","tags":["broker","broker.clients"],"security":[{"apiKey":[]},{"brokerContext":[]}],"responses":{"200":{"description":"Client","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ApiV1BrokerClientsClientId_GET200"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/broker/clients/{clientId}/detail":{"parameters":{"0":{"name":"clientId","in":"path","required":true,"schema":{"type":"string"}},"tags":["broker","broker.clients"]},"get":{"summary":"Aggregate client detail (household + policies + docs + activity)","tags":["broker","broker.clients"],"security":[{"apiKey":[]},{"brokerContext":[]}],"responses":{"200":{"description":"Detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrokerClientDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/broker/clients/{clientId}/portal-link":{"parameters":{"0":{"name":"clientId","in":"path","required":true,"schema":{"type":"string"}},"tags":["broker","broker.clients"]},"post":{"summary":"Issue a magic-link portal login for a client","tags":["broker","broker.clients"],"security":[{"apiKey":[]},{"brokerContext":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrokerClientPortalLinkRequest"}}}},"responses":{"201":{"description":"Link issued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrokerClientPortalLinkResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/broker/clients/{clientId}/send-portal-email":{"parameters":{"0":{"name":"clientId","in":"path","required":true,"schema":{"type":"string"}},"tags":["broker","broker.clients"]},"post":{"summary":"Send the magic link to the client's email","tags":["broker","broker.clients"],"security":[{"apiKey":[]},{"brokerContext":[]}],"responses":{"201":{"description":"Email queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendPortalEmailResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Client has no email/userId","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/broker/clients/intake/steps":{"get":{"summary":"Schema of the broker-side intake conversation","tags":["broker","broker.clients"],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Steps","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrokerIntakeStepsResponse"}}}}}}},"/api/v1/broker/clients/intake":{"post":{"summary":"Submit a broker-led intake (creates client + lead + portal link)","tags":["broker","broker.clients"],"security":[{"apiKey":[]},{"brokerContext":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrokerIntakeSubmitRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrokerIntakeSubmitResponse"}}}},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/api/v1/broker/follow-ups":{"get":{"summary":"List open follow-up tasks for the broker","tags":["broker","broker.follow-ups"],"security":[{"apiKey":[]},{"brokerContext":[]}],"responses":{"200":{"description":"Follow-ups","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrokerFollowUpsResponse"}}}}}}},"/api/v1/broker/prospect-uploads":{"parameters":{"0":{"name":"status","in":"query","schema":{"type":"string","default":"Queued"}},"tags":["broker","broker.prospect-uploads"]},"get":{"summary":"List prospect uploads (broker review queue)","tags":["broker","broker.prospect-uploads"],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Uploads","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrokerProspectUploadsResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/broker/prospect-uploads/{uploadId}":{"parameters":{"0":{"name":"uploadId","in":"path","required":true,"schema":{"type":"string"}},"tags":["broker","broker.prospect-uploads"]},"get":{"summary":"Get a single prospect upload (broker review)","tags":["broker","broker.prospect-uploads"],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Upload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ApiV1BrokerProspectuploadsUploadId_GET200"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/broker/prospect-uploads/{uploadId}/adopt":{"parameters":{"0":{"name":"uploadId","in":"path","required":true,"schema":{"type":"string"}},"tags":["broker","broker.prospect-uploads"]},"post":{"summary":"Broker adopts a prospect upload (claim ownership)","tags":["broker","broker.prospect-uploads"],"security":[{"apiKey":[]}],"responses":{"201":{"description":"Adopted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProspectUploadAdoptResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/broker/prospect-uploads/{uploadId}/reject":{"parameters":{"0":{"name":"uploadId","in":"path","required":true,"schema":{"type":"string"}},"tags":["broker","broker.prospect-uploads"]},"post":{"summary":"Broker rejects an upload","tags":["broker","broker.prospect-uploads"],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProspectUploadActionResponse"}}}}}}},"/api/v1/broker/prospect-uploads/{uploadId}/need-more-info":{"parameters":{"0":{"name":"uploadId","in":"path","required":true,"schema":{"type":"string"}},"tags":["broker","broker.prospect-uploads"]},"post":{"summary":"Mark upload as needing more info","tags":["broker","broker.prospect-uploads"],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Flagged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProspectUploadActionResponse"}}}}}}},"/api/v1/broker/opportunities":{"parameters":{"0":{"name":"view","in":"query","schema":{"type":"string","enum":["all","mine","hot"],"default":"all"}},"1":{"name":"state","in":"query","schema":{"type":"string","enum":["available","claimed","expired","locked"]}},"2":{"name":"insurance_type","in":"query","schema":{"type":"string"}},"3":{"name":"language","in":"query","schema":{"type":"string"}},"4":{"name":"intent_level","in":"query","schema":{"type":"string","enum":["high","medium","low"]}},"5":{"name":"min_price","in":"query","schema":{"type":"number"}},"6":{"name":"max_price","in":"query","schema":{"type":"number"}},"7":{"name":"time_remaining_max","in":"query","schema":{"type":"integer","description":"Seconds remaining on SLA"}},"8":{"name":"sort","in":"query","schema":{"type":"string","enum":["intent","sla","recency","price"],"default":"intent"}},"9":{"$ref":"#/components/parameters/PageParam"},"10":{"$ref":"#/components/parameters/LimitParam"},"tags":["broker","broker.opportunities"]},"get":{"summary":"List opportunities (v2 lead/opportunity system)","tags":["broker","broker.opportunities"],"security":[{"apiKey":[]},{"brokerContext":[]}],"responses":{"200":{"description":"Opportunities","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpportunityListResponse"}}}}}}},"/api/v1/broker/opportunities-claimed":{"get":{"summary":"List opportunities already claimed by this broker","tags":["broker","broker.opportunities-claimed"],"security":[{"apiKey":[]},{"brokerContext":[]}],"responses":{"200":{"description":"Claimed opportunities","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimedOpportunitiesResponse"}}}}}}},"/api/v1/broker/opportunities/{id}":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string"}},"tags":["broker","broker.opportunities"]},"get":{"summary":"Get one opportunity","tags":["broker","broker.opportunities"],"security":[{"apiKey":[]},{"brokerContext":[]}],"responses":{"200":{"description":"Opportunity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Opportunity"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/broker/opportunities/{id}/claim":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string"}},"tags":["broker","broker.opportunities"]},"post":{"summary":"Claim an opportunity (atomically)","tags":["broker","broker.opportunities"],"security":[{"apiKey":[]},{"brokerContext":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpportunityClaimRequest"}}}},"responses":{"200":{"description":"Claimed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpportunityClaimResponse"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"409":{"description":"Claim conflict (already claimed, expired, locked)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/advisor/apply":{"post":{"summary":"Public — submit advisor application","description":"Public endpoint. Advisors fill out the advisor-web \"Apply to Join\" form,\nthe submission lands in the advisor_applications table for manual review.\n","tags":["advisor","advisor.apply"],"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdvisorApplicationCreateRequest"}}}},"responses":{"201":{"description":"Application accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdvisorApplicationCreateResponse"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"409":{"description":"Duplicate pending application","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/advisor/applications":{"parameters":{"0":{"name":"status","in":"query","schema":{"type":"string","enum":["new","reviewing","approved","rejected","on_hold"]}},"1":{"name":"plan_tier","in":"query","schema":{"type":"string","enum":["starter","professional","enterprise"]}},"2":{"name":"license_state","in":"query","schema":{"type":"string","minLength":2,"maxLength":2}},"3":{"name":"q","in":"query","schema":{"type":"string","maxLength":80}},"4":{"name":"from","in":"query","schema":{"type":"string","format":"date-time"}},"5":{"name":"to","in":"query","schema":{"type":"string","format":"date-time"}},"6":{"name":"sort","in":"query","schema":{"type":"string","enum":["created_at","updated_at","status","plan_tier"],"default":"created_at"}},"7":{"name":"order","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},"8":{"$ref":"#/components/parameters/PageParam"},"9":{"$ref":"#/components/parameters/LimitParam"},"tags":["advisor","advisor.applications"]},"get":{"summary":"List advisor applications (admin/reviewer)","tags":["advisor","advisor.applications"],"security":[{"apiKey":[]}],"responses":{"200":{"description":"List with pagination","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdvisorApplicationListResponse"}}}}}}},"/api/v1/advisor/applications/{id}":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"tags":["advisor","advisor.applications"]},"get":{"summary":"Get one application","tags":["advisor","advisor.applications"],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Application","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdvisorApplicationDetailResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"summary":"Update status / reviewer_notes","tags":["advisor","advisor.applications"],"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdvisorApplicationUpdateRequest"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdvisorApplicationCreateResponse"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/client/assistant/conversations":{"parameters":{"0":{"name":"limit","in":"query","schema":{"type":"integer","default":10,"maximum":100}},"1":{"name":"offset","in":"query","schema":{"type":"integer","default":0,"minimum":0}},"tags":["client","client.assistant"]},"get":{"summary":"List the user's AI conversation history","tags":["client","client.assistant"],"security":[{"userIdHeader":[]}],"responses":{"200":{"description":"Conversations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantConversationsListResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"summary":"Create a new AI conversation","tags":["client","client.assistant"],"security":[{"userIdHeader":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantConversationCreateRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantConversationCreateResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/client/assistant/conversations/{id}":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"tags":["client","client.assistant"]},"delete":{"summary":"Soft-delete a conversation","tags":["client","client.assistant"],"security":[{"userIdHeader":[]}],"responses":{"204":{"description":"Deleted"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"summary":"Rename a conversation","tags":["client","client.assistant"],"security":[{"userIdHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenameConversationRequest"}}}},"responses":{"200":{"description":"Renamed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenameConversationResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/client/assistant/conversations/{id}/messages":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"1":{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":200}},"2":{"name":"offset","in":"query","schema":{"type":"integer","default":0}},"tags":["client","client.assistant"]},"get":{"summary":"Get messages in a conversation","tags":["client","client.assistant"],"security":[{"userIdHeader":[]}],"responses":{"200":{"description":"Messages","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantMessagesListResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"summary":"Send a user message (AI reply is currently STUB — TODO(P0-2))","description":"**Implementation note**: the `aiResponse` payload returned is currently a\nstatic stub (see `bff/src/routes/assistant.js` `STUB_RETURN` flag).\nProduction deployment must replace it with a call to\n`packages/ai-clients/llm.generateAssistantResponse()` before relying\non AI responses.\n","tags":["client","client.assistant"],"security":[{"userIdHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantMessageSendRequest"}}}},"responses":{"201":{"description":"User message + AI reply","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantMessageSendResponse"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/admin/rbac/roles":{"parameters":{"0":{"name":"level","in":"query","schema":{"type":"integer","description":"Role level (1=platform, 2=tenant, 3=custom)"}},"1":{"name":"isPlatformLevel","in":"query","schema":{"type":"boolean"}},"tags":["admin","admin.rbac"]},"get":{"summary":"List roles (platform sees all, tenant sees own + platform-level)","tags":["admin","admin.rbac"],"responses":{"200":{"description":"Roles","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_AdminRbacRoles_GET200"}}}}}},"post":{"summary":"Create a role","tags":["admin","admin.rbac"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RbacRoleCreateRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RbacRole"}}}},"403":{"description":"Tenant admin tried to create platform-level role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Role key already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/admin/rbac/roles/{id}":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string"}},"tags":["admin","admin.rbac"]},"put":{"summary":"Update role (name, description, parent, permission set)","tags":["admin","admin.rbac"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RbacRoleUpdateRequest"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RbacRole"}}}},"403":{"description":"Cannot modify system role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"summary":"Delete a role (must have no active users and no children)","tags":["admin","admin.rbac"],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_AdminRbacRolesId_DELETE200"}}}},"403":{"description":"Cannot delete system role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Role has active users or is a parent of other roles","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/admin/rbac/permissions":{"parameters":{"0":{"name":"resourceType","in":"query","schema":{"type":"string"}},"1":{"name":"action","in":"query","schema":{"type":"string"}},"tags":["admin","admin.rbac"]},"get":{"summary":"List all available permissions","tags":["admin","admin.rbac"],"responses":{"200":{"description":"Permissions (also grouped by resource_type)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_AdminRbacPermissions_GET200"}}}}}}},"/admin/rbac/roles/{id}/permissions":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string"}},"tags":["admin","admin.rbac"]},"get":{"summary":"Get a role's effective permissions","tags":["admin","admin.rbac"],"responses":{"200":{"description":"Permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_AdminRbacRolesIdPermissions_GET200"}}}}}},"put":{"summary":"Replace the role's permission set (atomic)","tags":["admin","admin.rbac"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RbacRolePermissionsUpdateRequest"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_AdminRbacRolesIdPermissions_PUT200"}}}},"403":{"description":"Cannot modify system role permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/admin/rbac/users/{userId}/roles":{"parameters":{"0":{"name":"userId","in":"path","required":true,"schema":{"type":"string"}},"1":{"name":"userType","in":"path","required":false,"schema":{"type":"string","enum":["broker","admin","prospect"],"default":"broker"}},"tags":["admin","admin.rbac"]},"get":{"summary":"List roles assigned to a user","tags":["admin","admin.rbac"],"responses":{"200":{"description":"Roles","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_AdminRbacUsersUserIdRoles_GET200"}}}}}},"post":{"summary":"Assign a role to a user","tags":["admin","admin.rbac"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RbacAssignRoleRequest"}}}},"responses":{"201":{"description":"Assigned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RbacUserRole"}}}},"403":{"description":"Cannot assign role from another tenant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"User already has this role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/admin/rbac/users/{userId}/roles/{roleId}":{"parameters":{"0":{"name":"userId","in":"path","required":true,"schema":{"type":"string"}},"1":{"name":"roleId","in":"path","required":true,"schema":{"type":"string"}},"tags":["admin","admin.rbac"]},"delete":{"summary":"Revoke a role from a user","tags":["admin","admin.rbac"],"responses":{"200":{"description":"Revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_AdminRbacUsersUserIdRolesRoleId_DELETE200"}}}},"403":{"description":"Cannot revoke role from another tenant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/admin/rbac/teams":{"parameters":{"0":{"name":"parentTeamId","in":"query","schema":{"type":"string"}},"tags":["admin","admin.rbac"]},"get":{"summary":"List teams in tenant scope","tags":["admin","admin.rbac"],"responses":{"200":{"description":"Teams","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_AdminRbacTeams_GET200"}}}}}},"post":{"summary":"Create a team","tags":["admin","admin.rbac"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RbacTeamCreateRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RbacTeam"}}}}}}},"/admin/rbac/teams/{id}/members":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string"}},"tags":["admin","admin.rbac"]},"get":{"summary":"List members of a team","tags":["admin","admin.rbac"],"responses":{"200":{"description":"Members","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_AdminRbacTeamsIdMembers_GET200"}}}}}},"post":{"summary":"Add a broker to a team","tags":["admin","admin.rbac"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RbacAddTeamMemberRequest"}}}},"responses":{"201":{"description":"Added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RbacTeamMember"}}}},"403":{"description":"Tenant mismatch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Broker already in team","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/admin/rbac/audit":{"parameters":{"0":{"name":"entityType","in":"query","schema":{"type":"string"}},"1":{"name":"entityId","in":"query","schema":{"type":"string"}},"2":{"name":"actorType","in":"query","schema":{"type":"string"}},"3":{"name":"actorId","in":"query","schema":{"type":"string"}},"4":{"name":"action","in":"query","schema":{"type":"string"}},"5":{"name":"from","in":"query","schema":{"type":"string","format":"date-time"}},"6":{"name":"to","in":"query","schema":{"type":"string","format":"date-time"}},"7":{"name":"limit","in":"query","schema":{"type":"integer","default":100,"maximum":1000}},"tags":["admin","admin.rbac"]},"get":{"summary":"Audit log query (tenant-scoped unless platform admin)","tags":["admin","admin.rbac"],"responses":{"200":{"description":"Audit log entries","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_AdminRbacAudit_GET200"}}}}}}},"/admin/rbac/tenants":{"get":{"summary":"List all tenants (platform admin only)","tags":["admin","admin.rbac"],"responses":{"200":{"description":"Tenants","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_AdminRbacTenants_GET200"}}}},"403":{"description":"Platform admin only","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/advisor-directory":{"get":{"tags":["advisor-directory"],"summary":"List advisors in the public directory","parameters":[{"name":"state","in":"query","schema":{"type":"string","description":"Filter by US state (e.g. CA","NY)":null}},{"name":"specialty","in":"query","schema":{"type":"string","description":"Filter by specialty (life","health":null,"annuity":null,"etc.)":null}},{"name":"accepting","in":"query","schema":{"type":"string","enum":["true","false"]}},{"name":"sort","in":"query","schema":{"type":"string","enum":["rating","response_time","years","newest"],"default":"rating"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Paginated advisor list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_Advisordirectory_GET200"}}}}}}},"/advisor-directory/{advisorId}":{"get":{"tags":["advisor-directory"],"summary":"Advisor detail (public profile + recent reviews + rating distribution)","parameters":[{"name":"advisorId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Advisor detail payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_AdvisordirectoryAdvisorId_GET200"}}}},"404":{"description":"Advisor not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/advisor-directory/{advisorId}/reviews":{"get":{"tags":["advisor-directory","advisor-directory.reviews"],"summary":"Full review list for an advisor (paginated)","parameters":[{"name":"advisorId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"min_rating","in":"query","schema":{"type":"integer","minimum":1,"maximum":5}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Review list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_AdvisordirectoryAdvisorIdReviews_GET200"}}}}}}},"/advisor-directory/{advisorId}/slots":{"get":{"tags":["advisor-directory","advisor-directory.slots"],"summary":"Available booking slots for an advisor (next N days)","parameters":[{"name":"advisorId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":60,"default":14}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"Available slots","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_AdvisordirectoryAdvisorIdSlots_GET200"}}}}}}},"/advisor-directory/{advisorId}/contact":{"post":{"tags":["advisor-directory","advisor-directory.contact"],"summary":"Submit an inquiry to an advisor (requires x-user-id)","parameters":[{"name":"advisorId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_AdvisordirectoryAdvisorIdContact_POSTRequest"}}}},"responses":{"201":{"description":"Inquiry created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdvisorInquiryCreated"}}}},"401":{"description":"Missing x-user-id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Advisor not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Advisor not currently accepting clients","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/client/claims/types":{"get":{"tags":["client","client.claims"],"summary":"Static list of claim types + checklist template","responses":{"200":{"description":"Types + checklist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ClientClaimsTypes_GET200"}}}}}}},"/client/claims":{"get":{"tags":["client","client.claims"],"summary":"List claims for the current user","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["draft","submitted","matching","in_progress","closed","denied"]}},{"name":"claimType","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Paginated claims list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ClientClaims_GET200"}}}},"401":{"description":"Missing x-user-id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["client","client.claims"],"summary":"Create a draft claim","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Claim"}}}},"400":{"description":"Invalid claimType","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing x-user-id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/client/claims/{id}":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"tags":["client","client.claims"]},"get":{"tags":["client","client.claims"],"summary":"Claim detail","responses":{"200":{"description":"Claim + document count","content":{"application/json":{"allOf":[{"$ref":"#/components/schemas/Claim"},{"type":"object","properties":{"documentCount":{"type":"integer"}}}]}}},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"tags":["client","client.claims"],"summary":"Partial update (only allowed in draft / matching)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimPatch"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Claim"}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Conflict (wrong status / advisor selection before submit)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/client/claims/{id}/submit":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"tags":["client","client.claims"]},"patch":{"tags":["client","client.claims"],"summary":"Submit a draft claim (triggers auto-match to an advisor)","responses":{"200":{"description":"Submitted + matched","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Claim"}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Not in draft state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/client/claims/{id}/match":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"tags":["client","client.claims"]},"get":{"tags":["client","client.claims"],"summary":"View the advisor matched to this claim","responses":{"200":{"description":"Match result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ClientClaimsIdMatch_GET200"}}}}}}},"/client/claims/{id}/documents":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"tags":["client","client.claims"]},"post":{"tags":["client","client.claims"],"summary":"Attach an existing uploaded document to this claim","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ClientClaimsIdDocuments_POSTRequest"}}}},"responses":{"201":{"description":"Attached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimDocument"}}}}}}},"/client/claims/{id}/timeline":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"tags":["client","client.claims"]},"get":{"tags":["client","client.claims"],"summary":"Claim progress timeline (auto-derived from status if timeline table not yet deployed)","responses":{"200":{"description":"Timeline entries","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ClientClaimsIdTimeline_GET200"}}}}}}},"/client/me":{"get":{"tags":["client","client.profile"],"summary":"Get current user's profile","responses":{"200":{"description":"Profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ClientMe_GET200"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"patch":{"tags":["client","client.profile"],"summary":"Update current user's profile","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsumerProfilePatch"}}}},"responses":{"200":{"description":"Updated profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ClientMe_PATCH200"}}}}}}},"/client/settings/notifications":{"get":{"tags":["client","client.settings"],"summary":"Get notification preferences","responses":{"200":{"description":"Notifications object","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ClientSettingsNotifications_GET200"}}}},"503":{"description":"Settings module not yet deployed (Wave 2)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["client","client.settings"],"summary":"Replace notification preferences","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ClientSettingsNotifications_PUTRequest"}}}},"responses":{"200":{"description":"Updated"}}}},"/client/life-events/catalog":{"get":{"tags":["client","client.life-events"],"summary":"Static life-event catalog (11 standard events)","responses":{"200":{"description":"Catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ClientLifeeventsCatalog_GET200"}}}}}}},"/client/life-events":{"get":{"tags":["client","client.life-events"],"summary":"List the current user's tracked life events","responses":{"200":{"description":"Tracked events list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ClientLifeevents_GET200"}}}}}},"post":{"tags":["client","client.life-events"],"summary":"Track a new life event","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserLifeEventCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserLifeEvent"}}}}}}},"/client/life-events/{id}":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"tags":["client","client.life-events"]},"get":{"tags":["client","client.life-events"],"summary":"Single tracked life event","responses":{"200":{"description":"Event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserLifeEvent"}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"tags":["client","client.life-events"],"summary":"Update a tracked event (status / progress)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserLifeEventPatch"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserLifeEvent"}}}}}}},"/client/life-events/{id}/why":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"eventKey (e.g. married, baby, home_purchase)"}},"tags":["client","client.life-events"]},"get":{"tags":["client","client.life-events"],"summary":"Why this matters + suggested reviews","responses":{"200":{"description":"Narrative","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ClientLifeeventsIdWhy_GET200"}}}}}}},"/client/dashboard/attention":{"get":{"tags":["client","client.dashboard"],"summary":"Needs Attention list (unfinished uploads + missing policies)","responses":{"200":{"description":"Attention items","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ClientDashboardAttention_GET200"}}}}}}},"/client/dashboard/activity":{"get":{"tags":["client","client.dashboard"],"summary":"Recent Activity feed (uploads + conversations + claims)","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}}],"responses":{"200":{"description":"Activities","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ClientDashboardActivity_GET200"}}}}}}},"/client/households/{id}/members":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"tags":["client","client.households"]},"get":{"tags":["client","client.households"],"summary":"List household members","responses":{"200":{"description":"Members","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ClientHouseholdsIdMembers_GET200"}}}}}},"post":{"tags":["client","client.households"],"summary":"Add a household member","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HouseholdMemberCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HouseholdMember"}}}}}}},"/client/households/{id}/members/{memberId}":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"1":{"name":"memberId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"tags":["client","client.households"]},"delete":{"tags":["client","client.households"],"summary":"Remove a household member","responses":{"200":{"description":"Removed"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/client/messages/threads":{"get":{"tags":["client","client.messages"],"summary":"List message threads","responses":{"200":{"description":"Threads","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ClientMessagesThreads_GET200"}}}}}},"post":{"tags":["client","client.messages"],"summary":"Create a message thread","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ClientMessagesThreads_POSTRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageThread"}}}}}}},"/client/messages/threads/{id}/messages":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"tags":["client","client.messages"]},"get":{"tags":["client","client.messages"],"summary":"List messages in a thread","responses":{"200":{"description":"Messages","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ClientMessagesThreadsIdMessages_GET200"}}}}}},"post":{"tags":["client","client.messages"],"summary":"Send a message in a thread","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ClientMessagesThreadsIdMessages_POSTRequest"}}}},"responses":{"201":{"description":"Sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}}}}}},"/api/v1/auth/oauth/providers":{"get":{"summary":"List enabled OAuth providers","tags":["auth","auth.oauth"],"responses":{"200":{"description":"Providers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderListResponse"}}}}}}},"/api/v1/auth/oauth/google":{"post":{"summary":"Google Sign-In","tags":["auth","auth.oauth"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthLoginRequest"}}}},"responses":{"200":{"description":"Logged in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthLoginResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/auth/oauth/apple":{"post":{"summary":"Apple Sign-In","tags":["auth","auth.oauth"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ApiV1AuthOauthApple_POSTRequest"}}}},"responses":{"200":{"description":"Logged in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthLoginResponse"}}}}}}},"/api/v1/policies/{id}/fields":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string"}},"tags":["policies","policies.fields"]},"get":{"summary":"List extracted + reviewed fields for a policy","tags":["policies","policies.fields"],"security":[{"userIdHeader":[]}],"responses":{"200":{"description":"Field list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolicyFieldsResponse"}}}}}}},"/api/v1/policies/{id}/fields/{fieldKey}/review":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string"}},"1":{"name":"fieldKey","in":"path","required":true,"schema":{"type":"string"}},"tags":["policies","policies.fields"]},"post":{"summary":"Review/edit a single field","tags":["policies","policies.fields"],"security":[{"userIdHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FieldReviewRequest"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FieldReviewResponse"}}}}}}},"/api/v1/policies/{id}/fields/confirm-all":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string"}},"tags":["policies","policies.fields"]},"post":{"summary":"Bulk confirm all fields","tags":["policies","policies.fields"],"security":[{"userIdHeader":[]}],"responses":{"200":{"description":"Confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmAllResponse"}}}}}}},"/api/v1/policies/{id}/adopt":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string"}},"tags":["policies","policies.adopt"]},"post":{"summary":"Adopt a parsed-but-uncertified upload","tags":["policies","policies.adopt"],"security":[{"userIdHeader":[]}],"responses":{"200":{"description":"Adopted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdoptResponse"}}}}}}},"/api/v1/policies/{id}/certify":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string"}},"tags":["policies","policies.certify"]},"post":{"summary":"Mark as certified (broker review complete)","tags":["policies","policies.certify"],"security":[{"userIdHeader":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CertifyRequest"}}}},"responses":{"200":{"description":"Certified","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CertifyResponse"}}}}}}},"/api/v1/policies/{id}/metadata":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string"}},"tags":["policies","policies.metadata"]},"patch":{"summary":"Edit policy metadata (planType / notes / tags)","tags":["policies","policies.metadata"],"security":[{"userIdHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolicyMetadataPatch"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolicyMetadataResponse"}}}}}}},"/api/v1/client/assistant/messages/{messageId}/save":{"parameters":{"0":{"name":"messageId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"tags":["client","client.assistant"]},"post":{"summary":"Save a message to user's library","tags":["client","client.assistant"],"security":[{"userIdHeader":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveMessageRequest"}}}},"responses":{"201":{"description":"Saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveMessageResponse"}}}}}},"delete":{"summary":"Unsave a message","tags":["client","client.assistant"],"security":[{"userIdHeader":[]}],"responses":{"200":{"description":"Unsaved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ApiV1ClientAssistantMessagesMessageIdSave_DELETE200"}}}}}}},"/api/v1/client/assistant/saved":{"get":{"summary":"List user's saved messages","tags":["client","client.assistant"],"security":[{"userIdHeader":[]}],"responses":{"200":{"description":"Saved list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedMessagesResponse"}}}}}}},"/api/v1/client/assistant/reminders":{"post":{"summary":"Create a reminder","tags":["client","client.assistant"],"security":[{"userIdHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReminderCreateRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReminderCreateResponse"}}}}}},"get":{"summary":"List reminders","tags":["client","client.assistant"],"security":[{"userIdHeader":[]}],"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["active","dismissed","fired"]}}],"responses":{"200":{"description":"Reminders","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReminderListResponse"}}}}}}},"/api/v1/client/assistant/reminders/{id}":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"tags":["client","client.assistant"]},"delete":{"summary":"Dismiss a reminder","tags":["client","client.assistant"],"security":[{"userIdHeader":[]}],"responses":{"200":{"description":"Dismissed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ApiV1ClientAssistantRemindersId_DELETE200"}}}}}}},"/api/v1/client/assistant/action-plans":{"post":{"summary":"Create an action plan","tags":["client","client.assistant"],"security":[{"userIdHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionPlanCreateRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionPlanCreateResponse"}}}}}},"get":{"summary":"List action plans","tags":["client","client.assistant"],"security":[{"userIdHeader":[]}],"responses":{"200":{"description":"Plans","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionPlanListResponse"}}}}}}},"/api/v1/client/assistant/action-plans/{id}":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"tags":["client","client.assistant"]},"patch":{"summary":"Update action plan steps / complete","tags":["client","client.assistant"],"security":[{"userIdHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionPlanPatchRequest"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionPlanItem"}}}}}}},"/api/v1/client/assistant/follow-ups":{"post":{"summary":"Create a follow-up","tags":["client","client.assistant"],"security":[{"userIdHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FollowUpCreateRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FollowUpCreateResponse"}}}}}},"get":{"summary":"List follow-ups","tags":["client","client.assistant"],"security":[{"userIdHeader":[]}],"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["pending","done","skipped","expired"]}}],"responses":{"200":{"description":"Follow-ups","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FollowUpListResponse"}}}}}}},"/api/v1/client/assistant/follow-ups/{id}":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"tags":["client","client.assistant"]},"patch":{"summary":"Mark follow-up done / skipped / expired","tags":["client","client.assistant"],"security":[{"userIdHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FollowUpPatchRequest"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ApiV1ClientAssistantFollowupsId_PATCH200"}}}}}}},"/api/v1/client/claims/{id}/close":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"tags":["client","client.claims"]},"post":{"summary":"Close a claim","tags":["client","client.claims"],"security":[{"userIdHeader":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimCloseRequest"}}}},"responses":{"200":{"description":"Closed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ApiV1ClientClaimsIdClose_POST200"}}}}}}},"/api/v1/client/claims/{id}/dispute":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"tags":["client","client.claims"]},"post":{"summary":"Dispute a closed/denied claim decision","tags":["client","client.claims"],"security":[{"userIdHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimDisputeRequest"}}}},"responses":{"200":{"description":"Disputed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ApiV1ClientClaimsIdDispute_POST200"}}}}}}},"/api/v1/client/claims/{id}/reopen":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"tags":["client","client.claims"]},"post":{"summary":"Reopen a disputed claim","tags":["client","client.claims"],"security":[{"userIdHeader":[]}],"responses":{"200":{"description":"Reopened","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ApiV1ClientClaimsIdReopen_POST200"}}}}}}},"/api/v1/client/claims/{id}/review":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"tags":["client","client.claims"]},"post":{"summary":"Submit a 1-5 star review for a claim experience","tags":["client","client.claims"],"security":[{"userIdHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimReviewRequest"}}}},"responses":{"200":{"description":"Recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ApiV1ClientClaimsIdReview_POST200"}}}}}}},"/api/v1/client/households/{id}/members/{memberId}":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"1":{"name":"memberId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"tags":["client","client.households"]},"patch":{"summary":"Update household member","tags":["client","client.households"],"security":[{"userIdHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HouseholdMemberPatch"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ApiV1ClientHouseholdsIdMembersMemberId_PATCH200"}}}}}}},"/api/v1/client/settings/privacy":{"get":{"summary":"Get privacy settings","tags":["client","client.settings"],"security":[{"userIdHeader":[]}],"responses":{"200":{"description":"Privacy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrivacySettingsResponse"}}}}}},"put":{"summary":"Update privacy settings","tags":["client","client.settings"],"security":[{"userIdHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrivacySettingsUpdateRequest"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ApiV1ClientSettingsPrivacy_PUT200"}}}}}}},"/api/v1/client/settings/security":{"get":{"summary":"Get security settings (2FA / password last changed)","tags":["client","client.settings"],"security":[{"userIdHeader":[]}],"responses":{"200":{"description":"Security","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SecuritySettingsResponse"}}}}}}},"/api/v1/client/me/change-password":{"post":{"summary":"Change password","tags":["client","client.profile"],"security":[{"userIdHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangePasswordRequest"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ApiV1ClientMeChangepassword_POST200"}}}}}}},"/api/v1/client/me/avatar":{"post":{"summary":"Upload avatar (data URL)","tags":["client","client.profile"],"security":[{"userIdHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarUploadRequest"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarUploadResponse"}}}}}}},"/api/v1/client/me/export":{"get":{"summary":"Export all user data (GDPR)","tags":["client","client.profile"],"security":[{"userIdHeader":[]}],"responses":{"200":{"description":"Data export (JSON)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataExportResponse"}}}}}}},"/api/v1/client/account":{"delete":{"summary":"Request account deletion (30-day grace period)","tags":["client","client.account"],"security":[{"userIdHeader":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ApiV1ClientAccount_DELETERequest"}}}},"responses":{"202":{"description":"Scheduled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountDeleteResponse"}}}}}}},"/api/v1/client/account/cancel-deletion":{"post":{"summary":"Cancel a pending account deletion","tags":["client","client.account"],"security":[{"userIdHeader":[]}],"responses":{"200":{"description":"Cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountDeleteCancelResponse"}}}}}}},"/api/v1/client/feedback":{"post":{"summary":"Submit feedback","tags":["client","client.feedback"],"security":[{"userIdHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackRequest"}}}},"responses":{"201":{"description":"Recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackCreateResponse"}}}}}}},"/api/v1/client/renewal-reminders":{"get":{"summary":"List renewal reminders","tags":["client","client.renewal-reminders"],"security":[{"userIdHeader":[]}],"responses":{"200":{"description":"Reminders","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenewalReminderListResponse"}}}}}},"post":{"summary":"Create renewal reminder","tags":["client","client.renewal-reminders"],"security":[{"userIdHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenewalReminderCreateRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenewalReminderItem"}}}}}}},"/api/v1/client/renewal-reminders/{id}":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"tags":["client","client.renewal-reminders"]},"patch":{"summary":"Update reminder","tags":["client","client.renewal-reminders"],"security":[{"userIdHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenewalReminderPatchRequest"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenewalReminderItem"}}}}}},"delete":{"summary":"Delete reminder","tags":["client","client.renewal-reminders"],"security":[{"userIdHeader":[]}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ApiV1ClientRenewalremindersId_DELETE200"}}}}}}},"/api/v1/client/2fa/enable":{"post":{"summary":"Start 2FA setup (returns secret + backup codes)","tags":["client","client.security"],"security":[{"userIdHeader":[]}],"responses":{"201":{"description":"Pending","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TwoFaEnableResponse"}}}}}}},"/api/v1/client/2fa/confirm":{"post":{"summary":"Confirm 2FA setup with a TOTP code","tags":["client","client.security"],"security":[{"userIdHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TwoFaConfirmRequest"}}}},"responses":{"200":{"description":"Enabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TwoFaConfirmResponse"}}}}}}},"/api/v1/client/2fa/disable":{"post":{"summary":"Disable 2FA (requires password)","tags":["client","client.security"],"security":[{"userIdHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TwoFaDisableRequest"}}}},"responses":{"200":{"description":"Disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TwoFaDisableResponse"}}}}}}},"/api/v1/client/password-reset/request":{"post":{"summary":"Request password reset email","tags":["client","client.password-reset"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PasswordResetRequestBody"}}}},"responses":{"200":{"description":"Sent (or not ??never reveal if email exists)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PasswordResetRequestResponse"}}}}}}},"/api/v1/client/password-reset/confirm":{"post":{"summary":"Confirm password reset with token + new password","tags":["client","client.password-reset"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PasswordResetConfirmRequest"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ApiV1ClientPasswordresetConfirm_POST200"}}}}}}},"/api/v1/client/messages/threads/{id}/read":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"tags":["client","client.messages"]},"post":{"summary":"Mark all messages in a thread as read","tags":["client","client.messages"],"security":[{"userIdHeader":[]}],"responses":{"200":{"description":"Marked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkThreadReadResponse"}}}}}}},"/api/v1/client/messages/threads/{id}/archive":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"tags":["client","client.messages"]},"post":{"summary":"Archive a thread","tags":["client","client.messages"],"security":[{"userIdHeader":[]}],"responses":{"200":{"description":"Archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThreadArchiveResponse"}}}}}}},"/api/v1/client/messages/threads/{id}/close":{"parameters":{"0":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"tags":["client","client.messages"]},"post":{"summary":"Close a thread","tags":["client","client.messages"],"security":[{"userIdHeader":[]}],"responses":{"200":{"description":"Closed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThreadCloseResponse"}}}}}}},"/api/v1/advisor-directory/{advisorId}/reviews":{"parameters":{"0":{"name":"advisorId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"tags":["advisor-directory","advisor-directory.reviews"]},"post":{"summary":"Submit a review (requires prior booking)","tags":["advisor-directory","advisor-directory.reviews"],"security":[{"userIdHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdvisorReviewCreateRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdvisorReviewCreateResponse"}}}}}}},"/api/v1/advisor-directory/{advisorId}/availability":{"parameters":{"0":{"name":"advisorId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"tags":["advisor-directory","advisor-directory.availability"]},"get":{"summary":"List 14-day availability window","tags":["advisor-directory","advisor-directory.availability"],"responses":{"200":{"description":"Slots","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdvisorAvailabilityResponse"}}}}}}},"/api/v1/advisor-directory/{advisorId}/bookings":{"parameters":{"0":{"name":"advisorId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"tags":["advisor-directory","advisor-directory.bookings"]},"post":{"summary":"Book a slot","tags":["advisor-directory","advisor-directory.bookings"],"security":[{"userIdHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdvisorBookingRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdvisorBookingResponse"}}}},"409":{"description":"Slot no longer available","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/v1/client/notifications":{"get":{"operationId":"listNotifications","summary":"List current user's in-app notifications","description":"Returns recent notifications (default 50, max 200). Pass ?unread=true to filter.","tags":["client","client.notifications"],"parameters":[{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"in":"query","name":"unread","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Notifications list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ApiV1ClientNotifications_GET200"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"503":{"$ref":"#/components/responses/NotDeployed"}}}},"/api/v1/client/notifications/unread-count":{"get":{"operationId":"getUnreadNotificationCount","summary":"Get count of unread notifications (used by header bell)","tags":["client","client.notifications"],"responses":{"200":{"description":"Count","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ApiV1ClientNotificationsUnreadcount_GET200"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/client/notifications/read-all":{"post":{"operationId":"markAllNotificationsRead","summary":"Mark every unread notification as read","tags":["client","client.notifications"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ApiV1ClientNotificationsReadall_POST200"}}}}}}},"/api/v1/client/notifications/{id}/read":{"post":{"operationId":"markNotificationRead","summary":"Mark a single notification as read","tags":["client","client.notifications"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ApiV1ClientNotificationsIdRead_POST200"}}}}}}},"/api/v1/client/notifications/{id}/dismiss":{"post":{"operationId":"dismissNotification","summary":"Dismiss a notification (set dismissed_at)","tags":["client","client.notifications"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmptyOk"}}}}}}},"/api/v1/client/notifications/{id}":{"delete":{"operationId":"deleteNotification","summary":"Hard-delete a notification","tags":["client","client.notifications"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmptyOk"}}}}}}},"/api/v1/client/2fa/recovery-codes":{"get":{"operationId":"listRecoveryCodes","summary":"List recovery code counts (codes shown only once at regeneration)","tags":["client","client.security"],"responses":{"200":{"description":"Counts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ApiV1Client2faRecoverycodes_GET200"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/client/2fa/recovery-codes/regenerate":{"post":{"operationId":"regenerateRecoveryCodes","summary":"Issue a fresh batch of 10 recovery codes (shown once)","tags":["client","client.security"],"responses":{"201":{"description":"New codes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ApiV1Client2faRecoverycodesRegenerate_POST201"}}}},"409":{"description":"2FA not enabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/client/2fa/recover":{"post":{"operationId":"redeemRecoveryCode","summary":"Use a recovery code to bypass 2FA on next login","tags":["client","client.security"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ApiV1Client2faRecover_POSTRequest"}}}},"responses":{"200":{"description":"Recovered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ApiV1Client2faRecover_POST200"}}}},"401":{"description":"Invalid or used code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/client/claims/{id}/documents/{docId}":{"delete":{"operationId":"detachClaimDocument","summary":"Detach a document from a claim","tags":["client","client.claims"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}},{"in":"path","name":"docId","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Detached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmptyOk"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/broker/auth/login":{"post":{"operationId":"brokerLogin","summary":"Broker sign-in (returns session token)","tags":["broker","broker.auth"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ApiV1BrokerAuthLogin_POSTRequest"}}}},"responses":{"200":{"description":"Signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ApiV1BrokerAuthLogin_POST200"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"503":{"$ref":"#/components/responses/NotDeployed"}}}},"/api/v1/broker/auth/logout":{"post":{"operationId":"brokerLogout","summary":"Broker sign-out (clears session)","tags":["broker","broker.auth"],"responses":{"200":{"description":"Signed out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmptyOk"}}}}}}},"/api/v1/broker/auth/register":{"post":{"operationId":"brokerRegister","summary":"Broker self-service signup (creates pending application; admin must approve)","tags":["broker","broker.auth"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ApiV1BrokerAuthRegister_POSTRequest"}}}},"responses":{"201":{"description":"Application created (pending approval)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ApiV1BrokerAuthRegister_POST201"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"409":{"description":"Email already registered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"$ref":"#/components/responses/NotDeployed"}}}},"/api/v1/broker/auth/registration-status":{"get":{"operationId":"getBrokerRegistrationStatus","summary":"Check whether an email has an existing pending broker application","tags":["broker","broker.auth"],"parameters":[{"in":"query","name":"email","required":true,"schema":{"type":"string","format":"email"}}],"responses":{"200":{"description":"Status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dto_ApiV1BrokerAuthRegistrationstatus_GET200"}}}}}}},"/api/v1/billing/plans":{"get":{"summary":"列出 4 档订阅套餐（公开，可缓存 5min）","tags":["admin","admin.plans"],"security":[],"responses":{"200":{"description":"Plans list","content":{"application/json":{"schema":{"type":"object","properties":{"plans":{"type":"array","items":{"$ref":"#/components/schemas/BillingPlan"}}}}}}}}}},"/api/v1/billing/checkout":{"post":{"summary":"创建 Stripe / UniPay Checkout Session（落本地 order → 拿 checkoutUrl 跳转）","description":"流程：客户端 POST plan + interval → BFF 落 orders (Pending) → 调 UniPay 中转创建 Stripe Checkout Session →\n把 sessionId 回写到 orders → 返回 checkoutUrl + sessionId + orderNo。\n**不要**前端自接 Stripe SDK，因为走 UniPay 中转（参考 STRIPE_DEPLOY_PARAMS.md §3.2）。\n","tags":["admin","admin.checkout"],"security":[{"brokerContext":[]},{"userIdHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["planCode","planInterval"],"properties":{"planCode":{"type":"string","enum":["starter","professional","enterprise"]},"planInterval":{"type":"string","enum":["month","year"]},"currency":{"type":"string","default":"USD"}}}}}},"responses":{"200":{"description":"Checkout session created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingCheckoutSession"}}}}}}},"/api/v1/billing/subscriptions/me":{"get":{"summary":"当前 broker 的订阅快照","tags":["admin","admin.subscriptions"],"security":[{"brokerContext":[]},{"userIdHeader":[]}],"responses":{"200":{"description":"Active subscription","content":{"application/json":{"schema":{"type":"object","properties":{"subscription":{"$ref":"#/components/schemas/Subscription"}}}}}}}}},"/api/v1/billing/orders/me":{"get":{"summary":"当前 broker 的历史订单","tags":["admin","admin.orders"],"security":[{"brokerContext":[]},{"userIdHeader":[]}],"parameters":[{"in":"query","name":"page","schema":{"type":"integer","default":1}},{"in":"query","name":"limit","schema":{"type":"integer","default":20,"maximum":100}}],"responses":{"200":{"description":"Orders page"}}}},"/api/v1/billing/stripe/webhook":{"post":{"summary":"Stripe / UniPay webhook 接收器（必须在 raw body 模式下挂载）","description":"UniPay 中转模式：UniPay 已验签，本接口不再二次验签（trust downstream）。\n直连 Stripe 模式（STRIPE_DIRECT=1）：用 HMAC-SHA256 验签（参考 STRIPE_DEPLOY_PARAMS.md §4）。\n处理 6 类事件：checkout.session.completed / invoice.paid / invoice.payment_failed\n             / customer.subscription.created / customer.subscription.updated / customer.subscription.deleted\n**必须**响应 < 5s，否则 Stripe 会重试。\n","tags":["admin","admin.stripe"],"security":[],"requestBody":{"required":true,"content":{"application/json":{}}},"responses":{"200":{"description":"Event received"}}}},"/api/v1/admin/billing/summary":{"get":{"summary":"大后台 billing dashboard 聚合（MRR / ARR / Paying brokers）","tags":["admin","admin.billing"],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Summary"}}}},"/api/v1/admin/billing/orders":{"get":{"summary":"大后台看所有订单","tags":["admin","admin.billing"],"security":[{"apiKey":[]}],"parameters":[{"in":"query","name":"brokerId","schema":{"type":"string","format":"uuid"}},{"in":"query","name":"status","schema":{"type":"string","enum":["Draft","Pending","Paid","Payment_Failed","Canceled","Refunded"]}},{"in":"query","name":"planCode","schema":{"type":"string","enum":["starter","professional","enterprise"]}},{"in":"query","name":"page","schema":{"type":"integer","default":1}},{"in":"query","name":"limit","schema":{"type":"integer","default":50,"maximum":200}}],"responses":{"200":{"description":"Orders page"}}}},"/api/v1/admin/billing/orders/{id}":{"get":{"summary":"订单详情（含 items）","tags":["admin","admin.billing"],"security":[{"apiKey":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Order with items"}}}},"/api/v1/admin/billing/orders/{id}/refund":{"post":{"summary":"退款（标记本地 order 为 Refunded）","tags":["admin","admin.billing"],"security":[{"apiKey":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Refunded"}}}},"/api/v1/admin/billing/subscriptions":{"get":{"summary":"所有订阅快照（按 broker 维度）","tags":["admin","admin.billing"],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Subscriptions page"}}}},"/api/v1/admin/billing/payouts":{"get":{"summary":"Payout 列表（broker 提现请求）","tags":["admin","admin.billing"],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Payouts page"}}}},"/api/v1/admin/billing/payouts/{id}/process":{"post":{"summary":"处理 payout（Pending → Processing）","tags":["admin","admin.billing"],"security":[{"apiKey":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Processing"}}}},"/api/v1/admin/audit/log":{"get":{"summary":"审计日志（90 天，PATCH/POST/DELETE）","tags":["admin","admin.audit"],"security":[{"apiKey":[]}],"parameters":[{"in":"query","name":"actorId","schema":{"type":"string","format":"uuid"}},{"in":"query","name":"tenantId","schema":{"type":"string","format":"uuid"}},{"in":"query","name":"action","schema":{"type":"string"}}],"responses":{"200":{"description":"Audit log page"}}}},"/api/v1/admin/marketplace/leads":{"get":{"summary":"大后台看所有 leads（含完整 contact_email / contact_phone）","tags":["admin","admin.marketplace"],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Leads"}}}},"/api/v1/marketplace/leads":{"get":{"summary":"Broker 公开池自查 leads（联系方式已掩码）","description":"默认走 lead_marketplace_masked 视图（mask_email / mask_phone）。\n解锁联系方式需 POST /api/v1/marketplace/leads/{id}/unlock。\n","tags":["marketplace","marketplace.leads"],"security":[{"brokerContext":[]}],"parameters":[{"in":"query","name":"state","schema":{"type":"string","description":"2字母州缩写，如 CA"}},{"in":"query","name":"grade","schema":{"type":"string","enum":["A","B","C","D"]}},{"in":"query","name":"zip","schema":{"type":"string"}},{"in":"query","name":"q","schema":{"type":"string","description":"模糊匹配 scenario_label / contact_name"}}],"responses":{"200":{"description":"Leads with masked contact"}}}},"/api/v1/marketplace/leads/{id}":{"get":{"summary":"单条 lead 详情（仍掩码）","tags":["marketplace","marketplace.leads"],"security":[{"brokerContext":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Lead"}}}},"/api/v1/marketplace/leads/{id}/unlock":{"post":{"summary":"解锁 lead 的真实联系方式（幂等）","description":"写入 unlocked_by；下次 GET /:id/contact 拿原始值。","tags":["marketplace","marketplace.leads"],"security":[{"brokerContext":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Unlocked"}}}},"/api/v1/marketplace/leads/{id}/contact":{"get":{"summary":"拿 lead 完整联系方式（必须先 unlock）","tags":["marketplace","marketplace.leads"],"security":[{"brokerContext":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Contact info"},"402":{"description":"Lead not unlocked by this broker"}}}},"/api/v1/marketplace/recommendations":{"get":{"summary":"按 broker 执照州自动推荐 leads（地理推荐）","tags":["marketplace","marketplace.recommendations"],"security":[{"brokerContext":[]}],"responses":{"200":{"description":"Recommendations"}}}},"/api/crm/auth/login":{"post":{"summary":"Coverfy CRM 登录（明文 email/password，复用 broker_sessions token）","description":"校验 brokers.password_hash（scrypt）→ 插入 broker_sessions →\n返回 {code:200, data:{token, ...user}, msg}。user 字段对齐前端 API.USERMANAGEMENT。\n","tags":["api","api.crm"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string","example":"michael.chen@coverfy.demo"},"password":{"type":"string","format":"password"}}}}}},"responses":{"200":{"description":"Login success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrmLoginResponse"}}}},"400":{"description":"Missing email/password"},"401":{"description":"Invalid credentials"},"403":{"description":"Account not active"}}}},"/api/crm/auth/user-info":{"get":{"summary":"当前登录用户信息（API.USERMANAGEMENT shape）","tags":["api","api.crm"],"security":[{"brokerContext":[]}],"responses":{"200":{"description":"User profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrmUserInfo"}}}},"401":{"description":"Unauthorized"}}}},"/api/crm/auth/permissions":{"get":{"summary":"操作权限 + 字段权限（access.ts 消费）","tags":["api","api.crm"],"security":[{"brokerContext":[]}],"responses":{"200":{"description":"Permissions","content":{"application/json":{"schema":{"type":"object","properties":{"operationPermissions":{"type":"array","items":{"type":"string"}},"fieldPermissions":{"type":"object","additionalProperties":true}}}}}},"401":{"description":"Unauthorized"}}}},"/api/crm/auth/routes-menu":{"get":{"summary":"按角色返回菜单树（normalizeRouteMenus 消费）","tags":["api","api.crm"],"security":[{"brokerContext":[]}],"responses":{"200":{"description":"Menu tree","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CrmMenuNode"}}}}},"401":{"description":"Unauthorized"}}}},"/api/crm/auth/logout":{"post":{"summary":"登出（删除当前 token 的 session）","tags":["api","api.crm"],"security":[{"brokerContext":[]}],"responses":{"200":{"description":"Logout success"}}}},"/api/crm/business/overview":{"get":{"summary":"业务概览聚合计数（leads/mainLeads/quotes/opportunities/bookings + scope）","tags":["api","api.crm"],"security":[{"brokerContext":[]}],"responses":{"200":{"description":"Overview counts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrmBusinessOverview"}}}},"401":{"description":"Unauthorized"}}}},"/api/crm/business/leads":{"get":{"summary":"商机列表（分页 + 筛选 + 排序；agent 只看 assigned）","description":"current/pageSize 分页；status/line_of_business 筛选；\nstart_time/end_time 日期范围；sortField/sortOrder 排序白名单；\nbroker 可传 perAgentId 过滤指定 agent。\nagent（user_type='agent'）恒返回 assigned_agent_id=自己的 lead。\n","tags":["api","api.crm"],"security":[{"brokerContext":[]}],"parameters":[{"name":"current","in":"query","schema":{"type":"integer","default":1}},{"name":"pageSize","in":"query","schema":{"type":"integer","default":20}},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"line_of_business","in":"query","schema":{"type":"string"}},{"name":"perAgentId","in":"query","schema":{"type":"string"}},{"name":"start_time","in":"query","schema":{"type":"string"}},{"name":"end_time","in":"query","schema":{"type":"string"}},{"name":"sortField","in":"query","schema":{"type":"string","enum":["created_at","updated_at","status","line_of_business","estimated_value"]}},{"name":"sortOrder","in":"query","schema":{"type":"string","enum":["ascend","descend"]}}],"responses":{"200":{"description":"Paged leads","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrmBusinessLeads"}}}},"401":{"description":"Unauthorized"}}}},"/api/crm/business/agents":{"get":{"summary":"本司 agent 列表（broker 可见；agent 返回空数组）","tags":["api","api.crm"],"security":[{"brokerContext":[]}],"responses":{"200":{"description":"Agents list","content":{"application/json":{"schema":{"type":"object","properties":{"agents":{"type":"array","items":{"$ref":"#/components/schemas/CrmBusinessAgent"}}}}}}},"401":{"description":"Unauthorized"}}}}},"tags":[{"name":"admin.audit","description":"子模块 audit"},{"name":"admin.billing","description":"子模块 billing"},{"name":"admin.checkout","description":"子模块 checkout"},{"name":"admin.marketplace","description":"子模块 marketplace"},{"name":"admin.orders","description":"子模块 orders"},{"name":"admin.plans","description":"子模块 plans"},{"name":"admin.rbac","description":"子模块 rbac"},{"name":"admin.stripe","description":"子模块 stripe"},{"name":"admin.subscriptions","description":"子模块 subscriptions"},{"name":"advisor-directory","description":"Public advisor directory + detail + reviews + slots + contact (Wave 1)"},{"name":"advisor-directory.availability","description":"子模块 availability"},{"name":"advisor-directory.bookings","description":"子模块 bookings"},{"name":"advisor-directory.contact","description":"子模块 contact"},{"name":"advisor-directory.reviews","description":"子模块 reviews"},{"name":"advisor-directory.slots","description":"子模块 slots"},{"name":"advisor.applications","description":"子模块 applications"},{"name":"advisor.apply","description":"子模块 apply"},{"name":"api.crm","description":"子模块 crm"},{"name":"auth.oauth","description":"子模块 oauth"},{"name":"broker.auth","description":"子模块 auth"},{"name":"broker.clients","description":"子模块 clients"},{"name":"broker.follow-ups","description":"子模块 follow-ups"},{"name":"broker.leads","description":"子模块 leads"},{"name":"broker.opportunities","description":"子模块 opportunities"},{"name":"broker.opportunities-claimed","description":"子模块 opportunities-claimed"},{"name":"broker.prospect-pool","description":"子模块 prospect-pool"},{"name":"broker.prospect-uploads","description":"子模块 prospect-uploads"},{"name":"client.account","description":"子模块 account"},{"name":"client.assistant","description":"子模块 assistant"},{"name":"client.claims","description":"子模块 claims"},{"name":"client.dashboard","description":"子模块 dashboard"},{"name":"client.feedback","description":"子模块 feedback"},{"name":"client.households","description":"子模块 households"},{"name":"client.life-events","description":"子模块 life-events"},{"name":"client.messages","description":"子模块 messages"},{"name":"client.notifications","description":"子模块 notifications"},{"name":"client.password-reset","description":"子模块 password-reset"},{"name":"client.profile","description":"子模块 profile"},{"name":"client.renewal-reminders","description":"子模块 renewal-reminders"},{"name":"client.security","description":"子模块 security"},{"name":"client.settings","description":"子模块 settings"},{"name":"documents","description":"Document upload, extraction, certification (advisor side)"},{"name":"documents.certify","description":"子模块 certify"},{"name":"documents.field-coordinates","description":"子模块 field-coordinates"},{"name":"documents.process","description":"子模块 process"},{"name":"documents.upload","description":"子模块 upload"},{"name":"espocrm.ping","description":"子模块 ping"},{"name":"households.policies","description":"子模块 policies"},{"name":"marketplace.leads","description":"子模块 leads"},{"name":"marketplace.recommendations","description":"子模块 recommendations"},{"name":"policies","description":"Espo Policy records"},{"name":"policies.adopt","description":"子模块 adopt"},{"name":"policies.certify","description":"子模块 certify"},{"name":"policies.dividend-track","description":"子模块 dividend-track"},{"name":"policies.documents","description":"子模块 documents"},{"name":"policies.fields","description":"子模块 fields"},{"name":"policies.metadata","description":"子模块 metadata"},{"name":"policies.return-cycle","description":"子模块 return-cycle"},{"name":"policies.term-conversion","description":"子模块 term-conversion"},{"name":"prospect.auth","description":"子模块 auth"},{"name":"prospect.book-advisor","description":"子模块 book-advisor"},{"name":"prospect.documents","description":"子模块 documents"},{"name":"prospect.followup","description":"子模块 followup"},{"name":"prospect.intake","description":"子模块 intake"},{"name":"prospect.invite","description":"子模块 invite"},{"name":"prospect.leads","description":"子模块 leads"},{"name":"prospect.login","description":"子模块 login"},{"name":"prospect.profile","description":"子模块 profile"},{"name":"prospect.register","description":"子模块 register"},{"name":"prospect.reports","description":"子模块 reports"},{"name":"service","description":"Liveness, status, index"}],"x-espocrm-proxy":{"description":"全局索引：**BFF 哪些公开端点 → 内部调 espocrm.js 的哪些函数 → 落在 Espo 哪个 entity。**\n用于评估 P2/RBAC 边界 + 应急切换 / 故障排查。\n","mappings":[{"bff_endpoint":"/api/v1/documents/upload","method":"POST","espocrm_fn":"createRecord('PolicyDocument')","espocrm_entity":"PolicyDocument","x-rbac-impact":"high"},{"bff_endpoint":"/api/v1/documents/{id}","method":"GET","espocrm_fn":"getRecord('PolicyDocument') | findPolicyExtractionByDocumentId | getRecord('Policy')","espocrm_entity":"PolicyDocument / PolicyExtraction / Policy","x-rbac-impact":"high"},{"bff_endpoint":"/api/v1/documents/{id}/extract","method":"POST","espocrm_fn":"findPolicyExtractionByDocumentId / updateRecord('PolicyExtraction') / createRecord('PolicyExtraction') / updateRecord('PolicyDocument')","espocrm_entity":"PolicyExtraction / PolicyDocument","x-rbac-impact":"medium"},{"bff_endpoint":"/api/v1/documents/{id}/certify","method":"POST","espocrm_fn":"getRecord('Policy') / getCertifiedExtractionsForPolicy / updateRecord('PolicyDocument')","espocrm_entity":"Policy / PolicyDocument","x-rbac-impact":"high"},{"bff_endpoint":"/api/v1/policies/{id}","method":"GET","espocrm_fn":"getRecord('Policy')","espocrm_entity":"Policy","x-rbac-impact":"high"},{"bff_endpoint":"/api/v1/policies/{id}/documents","method":"GET","espocrm_fn":"getRecord('Policy') / listPolicyDocumentsByPolicyId","espocrm_entity":"Policy / PolicyDocument","x-rbac-impact":"high"},{"bff_endpoint":"/api/v1/policies/{id}/return-cycle","method":"GET","espocrm_fn":"getRecord('Policy') / getCertifiedExtractionsForPolicy","espocrm_entity":"Policy / PolicyExtraction","x-rbac-impact":"medium"},{"bff_endpoint":"/api/v1/policies/{id}/term-conversion","method":"GET","espocrm_fn":"getRecord('Policy') / getCertifiedExtractionsForPolicy","espocrm_entity":"Policy / PolicyExtraction","x-rbac-impact":"medium"},{"bff_endpoint":"/api/v1/policies/{id}/dividend-track","method":"GET","espocrm_fn":"getRecord('Policy') / getCertifiedExtractionsForPolicy","espocrm_entity":"Policy / PolicyExtraction","x-rbac-impact":"medium"},{"bff_endpoint":"/api/v1/households/{id}/policies","method":"GET","espocrm_fn":"listPoliciesByHouseholdId","espocrm_entity":"Policy","x-rbac-impact":"medium"},{"bff_endpoint":"/api/v1/prospect/*","method":"*","espocrm_fn":"prospectEspo.syncProspectHouseholdToEspo / syncProspectLeadToEspo / syncBrokerIntakeToEspo","espocrm_entity":"ProspectHousehold / Lead / Contact","x-rbac-impact":"low"}]}}