openapi: 3.1.0 info: title: Healthspan Score API version: 1.0.0 summary: PlanScout intake scoring and Genworth cost-of-care analysis description: Receives PlanScout intake events, produces versioned person and household Healthspan scores, and delivers results through an asynchronous callback. The API also exposes the existing Genworth 2024 care-analysis model as a standalone operation. contact: name: Black Flag Design url: https://blackflag.design servers: - url: https://blessed-squirrel-650.convex.site description: Active QA deployment tags: - name: Integration description: PlanScout intake and score status - name: Care analysis description: Genworth 2024 cost-of-care model - name: Operations description: Deployment readiness paths: /oauth/token: post: tags: - Integration operationId: issuePlanScoutAccessToken summary: Exchange PlanScout machine credentials for a Clerk M2M token description: Implements the OAuth 2.0 client-credentials request shape requested by PlanScout. The opaque bearer token is issued and verified by Clerk M2M authentication and expires after one hour. security: [] requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object required: - grant_type properties: grant_type: type: string const: client_credentials scope: type: string const: healthspan.intakes.write client_id: type: string description: Optional when HTTP Basic authentication is used. client_secret: type: string format: password description: Optional when HTTP Basic authentication is used. responses: "200": description: Clerk M2M access token content: application/json: schema: $ref: "#/components/schemas/OAuthTokenResponse" "400": $ref: "#/components/responses/OAuthError" "401": $ref: "#/components/responses/OAuthError" /v1/intakes: post: tags: - Integration operationId: submitPlanScoutIntake summary: Accept a PlanScout intake for asynchronous scoring description: Production requests use a Clerk-backed OAuth 2.0 client-credentials bearer token. HMAC-SHA256 remains available as a compatibility fallback. Delivery is at least once; duplicate eventId values return the original status without creating a second score or callback. security: - planScoutOAuth: - healthspan.intakes.write - planScoutHmac: [] parameters: - $ref: "#/components/parameters/PlanScoutTimestamp" - $ref: "#/components/parameters/PlanScoutSignature" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PlanScoutIntake" examples: complete: summary: Complete synthetic intake value: eventType: intake.submitted eventId: f1c2e0a4-9b6d-4f2a-8e21-2c7b9a0d4e55 eventTimestamp: 2026-07-10T16:30:00.000Z schemaVersion: v1 advisorId: "10482" clientGuid: b7e63d4a-1f88-4c0e-9a2f-3d51c6e9aa10 planscoutPlanRequestId: 665f0a1b2c3d4e5f60718293 advisor: name: Jane Advisor company: Summit Wealth Partners email: jane@summitwealth.example client: hasPartner: true primary: firstName: Robert lastName: Miyazaki age: 64 partner: firstName: Susan lastName: Miyazaki age: 61 intake: employment: primary: isRetired: false currentIncome: 145000 expectedRetirementAge: 67 partner: isRetired: false currentIncome: 60000 expectedRetirementAge: 65 savings: totalAssets: 1170000 goals: targetIncome: 164000 legacyGoal: 250000 healthSupport: schemaVersion: v1 answers: - key: diet_frequency questionId: HQ1 type: single_choice_scale subject: primary selected: value: often label: Often ordinal: 3 - key: community_connection questionId: HQ2 type: single_choice_scale subject: primary selected: value: somewhat_connected label: Somewhat connected ordinal: 2 - key: health_conditions questionId: HQ3 type: multi_select subject: primary selected: - value: hypertension label: Hypertension noneSelected: false - key: care_reliance questionId: HQ4 type: multi_select subject: primary selected: - value: spouse_partner label: Spouse / partner - value: adult_child label: Adult child - key: care_dependents questionId: HQ5 type: multi_select subject: primary selected: - value: parent label: Parent - key: emergency_contact questionId: HQ6 type: single_choice_with_name subject: primary selected: value: adult_child label: Adult child contactName: Emily Miyazaki healthspan: state: Colorado careAssessment: conditionSummary: Hypertension managed with medication cognitionStage: none adlGrid: bathing: independent dressing: independent toileting: independent transferring: independent continence: independent feeding: independent iadlGrid: medication_management: cueing meal_prep: independent housekeeping: assist shopping: independent transportation: independent finances: independent communication: independent riskFlags: [] dmeInUse: [] caregiverHoursPerWeek: 20 carePreferences: Remain at home as long as practical state: Colorado responses: "200": description: Duplicate event already accepted content: application/json: schema: $ref: "#/components/schemas/AcceptedResponse" "202": description: Accepted for scoring content: application/json: schema: $ref: "#/components/schemas/AcceptedResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "422": $ref: "#/components/responses/UnprocessableEntity" /v1/intakes/{eventId}: get: tags: - Integration operationId: getIntakeStatus summary: Read score and callback status by PlanScout event ID security: - planScoutOAuth: - healthspan.intakes.write - planScoutHmac: [] parameters: - name: eventId in: path required: true schema: type: string format: uuid responses: "200": description: Current processing state with generated callback payload content: application/json: schema: $ref: "#/components/schemas/IntakeStatus" "404": description: Event not found /v1/care-cost/estimate: post: tags: - Care analysis operationId: estimateCareCost summary: Run the Genworth 2024 care-needs and cost model description: Derives weekly care needs, matches appropriate settings to state median costs, and generates multi-stage care scenarios. security: - planScoutOAuth: - healthspan.intakes.write - planScoutHmac: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CareAssessment" responses: "200": description: Care analysis result content: application/json: schema: type: object additionalProperties: true "422": $ref: "#/components/responses/UnprocessableEntity" /health: get: tags: - Operations operationId: getHealth summary: Check API readiness responses: "200": description: Healthy deployment content: application/json: schema: type: object components: securitySchemes: planScoutOAuth: type: oauth2 description: PlanScout machine authentication. Exchange client credentials at the token endpoint, cache the returned Clerk M2M bearer token until expiry, and send it in the Authorization header. flows: clientCredentials: tokenUrl: https://blessed-squirrel-650.convex.site/oauth/token scopes: healthspan.intakes.write: Submit intakes and read scoring status. planScoutHmac: type: apiKey in: header name: X-PlanScout-Signature description: sha256=. Pair with X-PlanScout-Timestamp; requests more than five minutes old are rejected. parameters: PlanScoutTimestamp: name: X-PlanScout-Timestamp in: header required: false schema: type: integer format: int64 description: Current Unix time in seconds. PlanScoutSignature: name: X-PlanScout-Signature in: header required: false schema: type: string pattern: ^sha256=[0-9a-f]{64}$ responses: BadRequest: description: Malformed JSON or request headers content: application/json: schema: $ref: "#/components/schemas/Error" Unauthorized: description: Missing, expired, or invalid bearer token or HMAC signature content: application/json: schema: $ref: "#/components/schemas/Error" OAuthError: description: OAuth client authentication or token request failed content: application/json: schema: $ref: "#/components/schemas/OAuthError" UnprocessableEntity: description: Payload does not satisfy schema v1 content: application/json: schema: $ref: "#/components/schemas/Error" schemas: OAuthTokenResponse: type: object required: - access_token - token_type - expires_in - scope properties: access_token: type: string description: Opaque Clerk M2M token. token_type: type: string const: Bearer expires_in: type: integer minimum: 1 maximum: 3600 scope: type: string const: healthspan.intakes.write OAuthError: type: object required: - error - error_description properties: error: type: string error_description: type: string PlanScoutIntake: type: object required: - eventType - eventId - eventTimestamp - schemaVersion - advisorId - clientGuid - planscoutPlanRequestId - advisor - client - intake - healthSupport properties: eventType: const: intake.submitted eventId: type: string format: uuid eventTimestamp: type: string format: date-time schemaVersion: const: v1 advisorId: type: string clientGuid: type: string format: uuid planscoutPlanRequestId: type: string advisor: type: object additionalProperties: true client: type: object additionalProperties: true intake: type: object additionalProperties: true estimatesApplied: type: object additionalProperties: type: boolean estimatedValues: type: object additionalProperties: true healthSupport: type: object required: - schemaVersion - answers properties: schemaVersion: const: v1 answers: type: array minItems: 1 items: $ref: "#/components/schemas/HealthAnswer" healthspan: type: object description: Optional extension for state-specific Genworth care analysis. properties: state: type: string careAssessment: $ref: "#/components/schemas/CareAssessment" additionalProperties: true HealthAnswer: type: object required: - key - questionId - subject properties: key: type: string questionId: type: string examples: - HQ1 label: type: string type: type: string subject: type: string enum: - primary - partner selected: {} noneSelected: type: boolean otherText: type: - string - "null" contactName: type: string additionalProperties: true CareAssessment: type: object required: - conditionSummary - cognitionStage - adlGrid - iadlGrid - riskFlags - dmeInUse - caregiverHoursPerWeek - carePreferences - state properties: conditionSummary: type: string cognitionStage: type: string enum: - none - mci - mild_dementia - moderate_dementia - severe_dementia adlGrid: type: object additionalProperties: $ref: "#/components/schemas/AbilityLevel" iadlGrid: type: object additionalProperties: $ref: "#/components/schemas/AbilityLevel" riskFlags: type: array items: type: string dmeInUse: type: array items: type: string caregiverHoursPerWeek: type: number minimum: 0 maximum: 168 carePreferences: type: string state: type: string AbilityLevel: type: string enum: - independent - cueing - assist - dependent AcceptedResponse: type: object required: - accepted - eventId - duplicate - status - statusUrl properties: accepted: const: true eventId: type: string format: uuid duplicate: type: boolean status: type: string enum: - accepted - completed statusUrl: type: string format: uri IntakeStatus: type: object properties: eventId: type: string format: uuid scoreStatus: type: string callbackStatus: type: string score: type: object additionalProperties: true callback: type: object additionalProperties: true Error: type: object required: - error - message properties: error: type: string message: type: string details: type: array items: type: object