{ "openapi": "3.0.4", "info": { "title": "AIT Risk Adjustment API", "description": "CMS-HCC risk adjustment factor (RAF) scoring. Send a beneficiary's demographics, enrollment facts and ICD-10-CM diagnoses; receive every model segment's score with a full term-by-term breakdown, the diagnosis-to-HCC trail, and the payment adjustments applied. The same engine is available in-process as the Ait.RiskAdjustment.Engine package.", "version": "1.0.0" }, "servers": [ { "url": "https://rafscore.beta.aithealth.net/" } ], "paths": { "/api/v1/scores": { "post": { "tags": [ "Scoring" ], "summary": "Score one beneficiary", "description": "Maps the submitted ICD-10-CM codes to HCCs (with CMS age and sex edits and hierarchies), computes every model segment's raw, normalized and payment scores with a term-by-term breakdown, and selects the applicable segment when the enrollment inputs allow it.", "operationId": "ScoreBeneficiary", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoreRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoreResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/v1/scores/batch": { "post": { "tags": [ "Scoring" ], "summary": "Score up to 500 beneficiaries under one model", "description": "Each item succeeds or fails on its own; item-level validation errors are returned per item rather than failing the batch. Your plan may allow fewer beneficiaries per call than the service maximum of 500; a larger batch is refused with errorCode Plan.BatchTooLarge.", "operationId": "ScoreBatch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchScoreRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchScoreResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-ait-subjects-property": "items" } }, "/api/v1/models": { "get": { "tags": [ "Models" ], "summary": "List the loaded CMS model packs", "operationId": "ListModels", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ModelDescriptor" } } } } } } } }, "/api/v1/models/mappings/{code}": { "get": { "tags": [ "Models" ], "summary": "Look an ICD-10-CM code up in a model's mapping table", "description": "Optional query parameters family, version and paymentYear select the model; omitted parts use the default pack.", "operationId": "LookupMapping", "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "family", "in": "query", "schema": { "enum": [ "CmsHcc", "Esrd", "RxHcc" ], "type": "string" } }, { "name": "version", "in": "query", "schema": { "type": "string" } }, { "name": "paymentYear", "in": "query", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MappingLookupResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/v1/hhs-hcc/scores": { "post": { "tags": [ "Scoring (ACA)" ], "summary": "Score one member against the HHS-HCC (ACA) model", "description": "Maps the submitted ICD-10-CM codes to condition categories (with CMS's age and sex rules and hierarchies), reads drug and procedure codes into drug categories for adults, chooses the infant, child or adult model from the member's age, and pays that model's groups and interactions at the plan's metal level, then applies the cost-sharing factor. The response carries every term, every diagnosis and drug code outcome, every category a hierarchy took away and what superseded it, and the places this engine deliberately differs from CMS's published software.", "operationId": "ScoreHhsMember", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HhsScoreRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HhsScoreResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/v1/hhs-hcc/scores/batch": { "post": { "tags": [ "Scoring (ACA)" ], "summary": "Score up to 500 members under one HHS-HCC model", "description": "Each member carries their own plan, because one population sits in many metal levels; only the model pack is shared, and the response reports it once rather than on every member. Each item succeeds or fails on its own; item-level validation errors are returned per item rather than failing the batch. Your plan may allow fewer members per call than the service maximum of 500; a larger batch is refused with errorCode Plan.BatchTooLarge.", "operationId": "ScoreHhsBatch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HhsBatchScoreRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HhsBatchScoreResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-ait-subjects-property": "items" } }, "/api/v1/hhs-hcc/large-group-proxy/scores": { "post": { "tags": [ "Scoring (ACA)" ], "summary": "Score a large-group member with the HHS-HCC model, as a labelled proxy", "description": "CMS calibrates these models on ACA individual and small-group data, and publishes nothing about how well they predict for large-group plans. The mechanics are identical to the official route and the number is exact; what it means for a large-group population is not established and is not claimed. Every answer says so. A large-group plan has no metal level of its own, so send either plan.metalLevel or plan.actuarialValue and the answer reports which model was scored. There is no market and no cost-sharing indicator: the route fixes both. This operation is enabled per plan; a subscription whose plan does not include it is refused with errorCode Plan.LargeGroupProxyNotIncluded.", "operationId": "ScoreLargeGroupProxy", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LargeGroupProxyScoreRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LargeGroupProxyScoreResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/v1/hhs-hcc/large-group-proxy/scores/batch": { "post": { "tags": [ "Scoring (ACA)" ], "summary": "Score many large-group members against one model, as labelled proxies", "description": "The same proxy as the single route, for a whole population in one call, and labelled the same way. The plan is on the request rather than on each item: no member here has a metal level of their own, so one is chosen for all of them, and scoring two members of one group against different columns would make the only comparison these numbers support unsafe. Each item succeeds or fails on its own. This operation is enabled per plan; a subscription whose plan does not include it is refused with errorCode Plan.LargeGroupProxyNotIncluded.", "operationId": "ScoreLargeGroupProxyBatch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LargeGroupProxyBatchScoreRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LargeGroupProxyBatchScoreResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-ait-subjects-property": "items" } }, "/api/v1/hhs-hcc/models": { "get": { "tags": [ "Scoring (ACA)" ], "summary": "List the loaded HHS-HCC model packs", "description": "One entry per benefit year this build carries, with the CMS package each came from, the rule decisions where this engine differs from CMS's software, and the model's stated limitations. Exactly one is marked isDefault: that is the pack a request naming no benefit year is scored against.", "operationId": "ListHhsModels", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HhsModelInfo" } } } } } } } }, "/api/v1/hhs-hcc/models/mappings/{code}": { "get": { "tags": [ "Scoring (ACA)" ], "summary": "Look one diagnosis code up in an HHS-HCC benefit year's crosswalk", "description": "Reports every condition category the code can reach and what CMS requires of the member to reach each one: whether the code is valid for the benefit year, the Medicare Code Editor age restriction (tested against the age at service), the model's own age edit (tested against the age at the end of enrollment) and any sex edit. Codes are normalized but not held to the ICD-10-CM shape, because CMS's own crosswalk for this family contains codes that shape would refuse. There is no category label, because CMS ships no table of them. Omit benefitYear and version for the default pack.", "operationId": "LookupHhsMapping", "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "benefitYear", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "version", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HhsMappingLookupResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } } } } }, "/api/v1/hhs-hcc/transfer-estimates": { "post": { "tags": [ "Transfers (ACA)" ], "summary": "Estimate an ACA risk adjustment transfer for the plans in a state market risk pool", "description": "Applies the HHS state transfer formula to the plan-level figures you supply, and reports each plan's transfer per member per month and in total. Where the two market denominators come from is yours to state: a complete pool computes them from the plans, stated figures are taken as given, and CMS's published state averages are an approximation that comes with a range rather than a single number. The high-cost risk pool is estimated separately when asked for and is never netted against a transfer. The answer lists every assumption it rests on and what a CMS settlement would include that it does not, and reports itself as a projection unless you state that the figures you supplied are CMS's published ones. It carries no member data at all: even the optional enrollee rows are a risk score and two month counts. This operation is enabled per plan; a subscription whose plan does not include it is refused with errorCode Plan.TransferEstimateNotIncluded.", "operationId": "EstimateHhsTransfer", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferEstimateRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferEstimateResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } } } } }, "/api/v1/medicaid/risk-index": { "post": { "tags": [ "Medicaid" ], "summary": "Rank a Medicaid population by relative risk", "description": "Scores every member with the HHS-HCC model and reports each one's score divided by the population's mean, so 1.000 is exactly average for the panel you sent and 2.000 is twice its risk. The whole population comes in one call because it is the denominator: a member sent alone is their own mean and would index 1.000 whoever they are, so fewer than two members is refused. A member who cannot be scored fails the whole call rather than being dropped, since dropping one would move every other member's index. This is not a Medicaid risk score and not a payment estimate. No state's model, weights or normalization are used; the coefficients are calibrated on commercial claims at commercial prices, so the ordering is roughly right and the levels are not, which is what dividing by the population's own mean is for. How well it ranks a Medicaid population has not been measured. The route carries no options at all, which is what keeps a payment estimate out of the answer. This operation is enabled per plan; a subscription whose plan does not include it is refused with errorCode Plan.MedicaidIndexNotIncluded.", "operationId": "IndexMedicaidPopulation", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MedicaidRiskIndexRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MedicaidRiskIndexResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } } }, "x-ait-subjects-property": "members" } } }, "components": { "schemas": { "AttributedInput": { "required": [ "codes", "categories", "leaveOneOut" ], "type": "object", "properties": { "codes": { "type": "array", "items": { "type": "string" }, "description": "The normalized codes this input stands for." }, "categories": { "type": "array", "items": { "type": "string" }, "description": "The conditions they reach, before hierarchies." }, "leaveOneOut": { "type": "number", "description": "The score with every input minus the score without this one.", "format": "double" }, "share": { "type": "number", "description": "This input's share of decimal ScoreAttributionInfo.Attributed. Null when the method reports no\r\nshares. Can be negative, where an input pushes the member into a count band that pays less than the terms\r\nit replaces.", "format": "double", "nullable": true } }, "additionalProperties": false, "description": "One clinical input's two figures, and the codes it stands for." }, "AttributionMethod": { "enum": [ "Shapley", "LeaveOneOut" ], "type": "string", "description": "Which of §6's two methods produced the shares in an attribution." }, "BatchScoreItem": { "required": [ "beneficiary" ], "type": "object", "properties": { "correlationId": { "type": "string", "nullable": true }, "beneficiary": { "$ref": "#/components/schemas/BeneficiaryInput" }, "diagnoses": { "type": "array", "items": { "$ref": "#/components/schemas/DiagnosisInput" } }, "contract": { "oneOf": [ { "enum": [ null ], "nullable": true }, { "$ref": "#/components/schemas/ContractInput" } ] }, "documentationCandidates": { "type": "array", "items": { "$ref": "#/components/schemas/DiagnosisInput" }, "description": "Codes not yet documented, scored as a separate second beneficiary so they reach only the revenue estimate.\r\nProvider view only." }, "priorPeriodCodes": { "type": "array", "items": { "$ref": "#/components/schemas/DiagnosisInput" }, "description": "Codes documented in the prior period, for recapture. Provider view only." } }, "additionalProperties": false, "description": "One beneficiary in a batch: the same inputs a single request carries, minus the model and the options." }, "BatchScoreRequest": { "required": [ "items" ], "type": "object", "properties": { "model": { "oneOf": [ { "enum": [ null ], "nullable": true }, { "$ref": "#/components/schemas/ModelSelector" } ] }, "options": { "$ref": "#/components/schemas/ScoreOptions" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/BatchScoreItem" } } }, "additionalProperties": false, "description": "Score many beneficiaries under one model in a single call." }, "BatchScoreResponse": { "required": [ "results", "succeeded", "failed" ], "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/BatchScoreResult" } }, "succeeded": { "type": "integer", "format": "int32" }, "failed": { "type": "integer", "format": "int32" } }, "additionalProperties": false }, "BatchScoreResult": { "required": [ "beneficiaryId" ], "type": "object", "properties": { "correlationId": { "type": "string", "nullable": true }, "beneficiaryId": { "type": "string" }, "score": { "oneOf": [ { "enum": [ null ], "nullable": true }, { "$ref": "#/components/schemas/ScoreResponse" } ] }, "errors": { "type": "array", "items": { "type": "string" }, "nullable": true } }, "additionalProperties": false, "description": "One item's outcome. Exactly one of ScoreResponse? BatchScoreResult.Score and IReadOnlyList<string>? BatchScoreResult.Errors is populated." }, "BenchmarkRiskAdjustment": { "enum": [ "MultiplyByScore", "ScaleByScoreRatio" ], "type": "string", "nullable": true }, "BeneficiaryDerived": { "required": [ "id", "age", "sex", "originalEntitlementReason", "isDisabled", "isOriginallyDisabled", "medicaidEligible", "ageSexCell", "newEnrolleeAgeSexCell" ], "type": "object", "properties": { "id": { "type": "string", "description": "The caller's opaque reference, echoed back." }, "age": { "type": "integer", "description": "The age that was scored, as submitted.", "format": "int32" }, "sex": { "$ref": "#/components/schemas/BeneficiarySex" }, "originalEntitlementReason": { "$ref": "#/components/schemas/OriginalEntitlementReason" }, "isDisabled": { "type": "boolean", "description": "Under 65 and entitled by disability or ESRD (CMS DISABL)." }, "isOriginallyDisabled": { "type": "boolean", "description": "65 or older and originally entitled by disability (CMS ORIGDIS)." }, "medicaidEligible": { "type": "boolean", "description": "Medicaid flag actually used in scoring." }, "ageSexCell": { "type": "string", "description": "Continuing-enrollee age/sex cell, e.g. F75_79." }, "newEnrolleeAgeSexCell": { "type": "string", "description": "New-enrollee age/sex cell, e.g. NEF75_79 (age 64 with OREC Aged lands in the 65 cell)." } }, "additionalProperties": false }, "BeneficiaryInput": { "required": [ "id", "age", "sex" ], "type": "object", "properties": { "id": { "type": "string", "description": "Opaque reference the caller uses to correlate the result (a request-scoped token, a surrogate key).\r\nIt is echoed back and never stored. It must not be a Medicare Beneficiary Identifier, medical record\r\nnumber, or any other identifier of a person." }, "age": { "type": "integer", "description": " Age in whole years measured on one specific day: the model's age-as-of date, which is February 1 of the\r\n payment year and is reported as `model.ageAsOfDate` by the models endpoint.\r\n This is not the beneficiary's age today, and not their age at any date of service. Someone who turns 65\r\nin March 2026 is 64 for a payment year 2026 request all year long; sending 65 scores them in the\r\naged segments instead of the disabled ones and pays the wrong amount. The service receives one number\r\nand cannot detect the difference, so the caller has to measure it on the right day.The caller computes it; the service never sees a birth date. Applications holding one should use\r\nAgeCalculator.AgeAt(dateOfBirth, model.ageAsOfDate) from the Domain package rather than\r\nsubtracting years. Only the age band matters to the model, whose top band is 95 and over, so an exact\r\nage above 95 adds nothing: send 95 for anyone 95 or older.", "format": "int32" }, "sex": { "$ref": "#/components/schemas/BeneficiarySex" }, "enrollment": { "$ref": "#/components/schemas/EnrollmentInput" } }, "additionalProperties": false }, "BeneficiarySex": { "enum": [ "Female", "Male" ], "type": "string", "description": "The sex recorded for the beneficiary in the payer's enrollment data, which is the value CMS's models are\r\ncalibrated on and apply their sex edits and coefficients by. It is not a clinical finding and not a statement\r\nof gender identity.\r\nSend one of exactly two names, `Female` or `Male`; letter case does not matter, so `male` is\r\naccepted. CMS's numeric codes (1, 2) and abbreviations (M, F) are not: a request carrying anything else is\r\nrefused with \"'1' is not one of: Female, Male.\" CMS defines no third value, so there is none for unknown; when\r\na source system holds one, send what the CMS enrollment record for that beneficiary carries, because that is\r\nthe value CMS scored. This service never guesses one." }, "ContractArrangement": { "enum": [ "PercentOfPremium", "RiskAdjustedCapitation", "SharedSavings", "FeeForService" ], "type": "string", "nullable": true }, "ContractInput": { "required": [ "arrangement" ], "type": "object", "properties": { "arrangement": { "$ref": "#/components/schemas/ContractArrangement" }, "scoreBasis": { "oneOf": [ { "enum": [ null ], "nullable": true }, { "$ref": "#/components/schemas/ContractScoreBasis" } ] }, "memberMonths": { "type": "integer", "description": "Months of the year the member is under this contract, 1 to 12.", "format": "int32", "nullable": true }, "monthlyRevenueBasis": { "type": "number", "description": "Percent of premium: the payer's monthly revenue for this member before risk adjustment.", "format": "double", "nullable": true }, "shareOfPremium": { "type": "number", "description": "Percent of premium: the provider's share, as a fraction. Forty-two per cent is `0.42`.", "format": "double", "nullable": true }, "basePmpm": { "type": "number", "description": "Capitation: the per-member-per-month rate the risk factor multiplies.", "format": "double", "nullable": true }, "populationAverageScore": { "type": "number", "description": "Capitation: the contract population's average score, when the contract divides by it.", "format": "double", "nullable": true }, "riskFactorFloor": { "type": "number", "description": "Capitation: the least the risk factor may be.", "format": "double", "nullable": true }, "riskFactorCap": { "type": "number", "description": "Capitation: the most the risk factor may be.", "format": "double", "nullable": true }, "benchmark": { "type": "number", "description": "Shared savings: the benchmark for this member over the period, before risk adjustment.", "format": "double", "nullable": true }, "riskAdjustmentMethod": { "oneOf": [ { "enum": [ null ], "nullable": true }, { "$ref": "#/components/schemas/BenchmarkRiskAdjustment" } ] }, "baselineScore": { "type": "number", "description": "Shared savings: the baseline population score, required by `ScaleByScoreRatio`.", "format": "double", "nullable": true }, "riskAdjustmentCap": { "type": "number", "description": "Shared savings: the most the risk adjustment may move the benchmark, as a factor.", "format": "double", "nullable": true }, "sharingRate": { "type": "number", "description": "Shared savings: the provider's share of savings, as a fraction. Reported, never estimated with.", "format": "double", "nullable": true }, "minimumSavingsRate": { "type": "number", "description": "Shared savings: the savings threshold, as a fraction. Reported, never estimated with.", "format": "double", "nullable": true }, "qualityGate": { "type": "number", "description": "Shared savings: the quality score required, as a fraction. Reported, never estimated with.", "format": "double", "nullable": true } }, "additionalProperties": false, "description": "One payer contract, as much of it as you choose to state." }, "ContractScoreBasis": { "enum": [ "RawScore", "NormalizedScore", "PaymentScore", "CsrAdjustedScore" ], "type": "string", "description": "Which of the member's scores the contract pays on. The contract names one, and only that one is used: two of\r\nthese are different numbers for the same member, and picking the wrong one gives a plausible wrong answer." }, "ContractTermInfo": { "required": [ "name", "value", "source" ], "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "number", "format": "double" }, "source": { "$ref": "#/components/schemas/ContractTermSource" }, "notEstimatedBecause": { "type": "string", "description": "Set when the term was supplied and reported but deliberately not used, with the reason.", "nullable": true } }, "additionalProperties": false, "description": "One named value an estimate used." }, "ContractTermSource": { "enum": [ "Contract", "Score", "Computed" ], "type": "string", "description": "Where a reported value came from." }, "DenominatorsInput": { "required": [ "source" ], "type": "object", "properties": { "source": { "$ref": "#/components/schemas/DenominatorSource" }, "stated": { "oneOf": [ { "enum": [ null ], "nullable": true }, { "$ref": "#/components/schemas/StatedDenominatorsInput" } ] }, "stateAverages": { "oneOf": [ { "enum": [ null ], "nullable": true }, { "$ref": "#/components/schemas/StateAveragesInput" } ] } }, "additionalProperties": false, "description": "Where the pool's two denominators come from, and the figures for that source." }, "DenominatorSource": { "enum": [ "CompletePool", "Stated", "StateAverages" ], "type": "string", "description": "Where the two sums a transfer divides by come from. Always stated by the caller, never inferred." }, "DiagnosisInput": { "required": [ "code" ], "type": "object", "properties": { "code": { "type": "string", "description": "ICD-10-CM code, with or without the dot, any case. Normalized before lookup." }, "source": { "oneOf": [ { "enum": [ null ], "nullable": true }, { "$ref": "#/components/schemas/DiagnosisSource" } ] } }, "additionalProperties": false }, "DiagnosisOutcome": { "required": [ "code", "normalizedCode", "status", "conditionCategories", "exclusions" ], "type": "object", "properties": { "code": { "type": "string", "description": "The code exactly as submitted." }, "normalizedCode": { "type": "string", "description": "Upper-case, no dot, trimmed. This is what was looked up." }, "status": { "$ref": "#/components/schemas/DiagnosisStatus" }, "conditionCategories": { "type": "array", "items": { "type": "integer", "format": "int32" }, "description": "Condition categories assigned from this code after age and sex edits." }, "exclusions": { "type": "array", "items": { "$ref": "#/components/schemas/MappingExclusion" }, "description": "Mapping rows that were rejected by an edit, with the rule that rejected them." } }, "additionalProperties": false }, "DiagnosisSource": { "enum": [ "Encounter", "ProblemList", "Claim", "ChartReview", "Other" ], "type": "string", "nullable": true }, "DiagnosisStatus": { "enum": [ "Mapped", "NotInModel", "ExcludedByEdits", "Duplicate" ], "type": "string" }, "DocumentationSupport": { "required": [ "disclaimer", "recapture", "notPrompted", "specificity", "priorPeriodSupplied" ], "type": "object", "properties": { "disclaimer": { "type": "string" }, "recapture": { "type": "array", "items": { "$ref": "#/components/schemas/RecapturePrompt" }, "description": "Conditions the prior-period codes reached that this period's neither reach nor outrank. Empty when the\r\ncaller sent no prior period, which is not the same as there being nothing to recapture, and the response\r\nsays which it is." }, "notPrompted": { "type": "array", "items": { "$ref": "#/components/schemas/PriorConditionNotPrompted" }, "description": "Every other condition the prior-period codes reached, with the reason it needs no prompt. Together with\r\nIReadOnlyList<RecapturePrompt> DocumentationSupport.Recapture this covers all of them: a prior condition appears in exactly one of the two\r\nlists, never neither, so a coder can see that a condition was weighed rather than wonder whether it was\r\noverlooked." }, "specificity": { "type": "array", "items": { "$ref": "#/components/schemas/SpecificityReference" }, "description": "For each condition this period documents, the conditions the model ranks above it (§7.1). It answers\r\n\"could what I coded have been more specific\" and needs no prior period, so it is present whenever the\r\nprovider view is." }, "priorPeriodSupplied": { "type": "boolean", "description": "Whether a prior period was supplied at all. Without one both recapture lists are empty because nothing\r\nwas compared, and a reader who cannot tell that from \"nothing to recapture\" would draw the wrong\r\nconclusion. IReadOnlyList<SpecificityReference> DocumentationSupport.Specificity does not depend on it." } }, "additionalProperties": false, "description": "What the documented conditions suggest is worth a second look, and nothing about money." }, "DualStatus": { "enum": [ "NonDual", "PartialBenefit", "FullBenefit" ], "type": "string", "nullable": true }, "EnrollmentInput": { "type": "object", "properties": { "originalEntitlementReason": { "oneOf": [ { "enum": [ null ], "nullable": true }, { "$ref": "#/components/schemas/OriginalEntitlementReason" } ] }, "medicaidEligible": { "type": "boolean", "description": "Medicaid eligibility for one or more months (CMS LTIMCAID for continuing enrollees, NEMCAID for\r\nnew enrollees). Null is derived from DualStatus? EnrollmentInput.DualStatus when present, otherwise scored as\r\nnot Medicaid and reported as an assumption.", "nullable": true }, "dualStatus": { "oneOf": [ { "enum": [ null ], "nullable": true }, { "$ref": "#/components/schemas/DualStatus" } ] }, "isLongTermInstitutional": { "type": "boolean", "description": "Long-term institutional (90+ days, MDS-based). Needed to pick the institutional segment.", "nullable": true }, "isNewEnrollee": { "type": "boolean", "description": "Fewer than 12 months of Part B in the data-collection year. Needed to pick the new-enrollee segment.", "nullable": true }, "isChronicConditionSnp": { "type": "boolean", "description": "Enrolled in a chronic-condition special needs plan (C-SNP). Only affects new enrollees.", "nullable": true } }, "additionalProperties": false, "description": "Medicare enrollment facts the CMS models need. Every field is optional because an EHR rarely holds\r\nthem; a null is treated as \"unknown\", the assumption used is reported back, and segment selection\r\nis left undetermined when a deciding input is missing." }, "ExcludedFromTransferResult": { "required": [ "item", "reason" ], "type": "object", "properties": { "item": { "$ref": "#/components/schemas/TransferExclusion" }, "reason": { "type": "string", "description": "Why, in a sentence a caller can put in front of an actuary." } }, "additionalProperties": false, "description": "Something CMS settles alongside a transfer that this estimate leaves out, and why." }, "ExclusionReason": { "enum": [ "MceAgeEdit", "AgeEdit", "SexEdit" ], "type": "string" }, "HccOutcome": { "required": [ "hcc", "label", "status", "sourceCodes" ], "type": "object", "properties": { "hcc": { "type": "integer", "format": "int32" }, "label": { "type": "string" }, "status": { "$ref": "#/components/schemas/HccStatus" }, "droppedBy": { "type": "integer", "description": "For DroppedByHierarchy, the higher HCC that caused the drop.", "format": "int32", "nullable": true }, "sourceCodes": { "type": "array", "items": { "type": "string" }, "description": "Normalized diagnosis codes that produced this HCC." } }, "additionalProperties": false }, "HccStatus": { "enum": [ "Active", "DroppedByHierarchy", "RecodedOut" ], "type": "string" }, "HhsBatchScoreItem": { "required": [ "member", "plan" ], "type": "object", "properties": { "correlationId": { "type": "string", "description": "The caller's own reference for this item, echoed back on its result.", "nullable": true }, "member": { "$ref": "#/components/schemas/HhsMemberInput" }, "plan": { "$ref": "#/components/schemas/HhsPlanInput" }, "diagnoses": { "type": "array", "items": { "$ref": "#/components/schemas/HhsDiagnosisRequestInput" } }, "drugs": { "oneOf": [ { "enum": [ null ], "nullable": true }, { "$ref": "#/components/schemas/HhsDrugInput" } ] }, "contract": { "oneOf": [ { "enum": [ null ], "nullable": true }, { "$ref": "#/components/schemas/ContractInput" } ] }, "documentationCandidates": { "type": "array", "items": { "$ref": "#/components/schemas/HhsDiagnosisRequestInput" }, "description": "Codes not yet documented, scored as a separate second member so they reach only the revenue estimate.\r\nProvider view only." }, "priorPeriodCodes": { "type": "array", "items": { "$ref": "#/components/schemas/HhsDiagnosisRequestInput" }, "description": "Codes documented earlier in the benefit year, for recapture. Provider view only." } }, "additionalProperties": false, "description": "One member in a batch: the same inputs a single request carries, minus the model and the options." }, "HhsBatchScoreRequest": { "required": [ "items" ], "type": "object", "properties": { "model": { "oneOf": [ { "enum": [ null ], "nullable": true }, { "$ref": "#/components/schemas/HhsModelSelector" } ] }, "options": { "$ref": "#/components/schemas/HhsScoreOptions" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/HhsBatchScoreItem" } } }, "additionalProperties": false, "description": "Score many members under one HHS-HCC model pack in a single call." }, "HhsBatchScoreResponse": { "required": [ "model", "results", "succeeded", "failed" ], "type": "object", "properties": { "model": { "$ref": "#/components/schemas/HhsModelInfo" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/HhsBatchScoreResult" } }, "succeeded": { "type": "integer", "format": "int32" }, "failed": { "type": "integer", "format": "int32" } }, "additionalProperties": false, "description": "Every item's outcome, and the one model they were all scored against." }, "HhsBatchScoreResult": { "required": [ "memberId" ], "type": "object", "properties": { "correlationId": { "type": "string", "nullable": true }, "memberId": { "type": "string", "description": "The caller's own member reference, echoed back." }, "score": { "oneOf": [ { "enum": [ null ], "nullable": true }, { "$ref": "#/components/schemas/HhsMemberScore" } ] }, "errors": { "type": "array", "items": { "type": "string" }, "description": "Why the item could not be scored, when it could not.", "nullable": true } }, "additionalProperties": false, "description": "One member's outcome. Exactly one of HhsMemberScore? HhsBatchScoreResult.Score and IReadOnlyList<string>? HhsBatchScoreResult.Errors is populated: an item that\r\ncannot be scored fails on its own rather than failing the batch." }, "HhsDiagnosisOutcomeInfo": { "required": [ "code", "normalizedCode", "status", "categories" ], "type": "object", "properties": { "code": { "type": "string", "description": "The code exactly as the caller sent it." }, "normalizedCode": { "type": "string", "description": "The code after normalization, which is what was looked up." }, "status": { "$ref": "#/components/schemas/HhsDiagnosisStatus" }, "categories": { "type": "array", "items": { "type": "string" }, "description": "The condition categories this diagnosis reached, before hierarchies." }, "reason": { "type": "string", "description": "Why it reached none, when it reached none.", "nullable": true } }, "additionalProperties": false }, "HhsDiagnosisRequestInput": { "required": [ "code" ], "type": "object", "properties": { "code": { "type": "string", "description": "ICD-10-CM code, with or without the dot, any case. Normalized before lookup." }, "ageAtService": { "type": "integer", "description": "The member's age in whole years when the service happened, which is what CMS's instructions test its\r\ncode-editor age restrictions against. Capped at 90, must not exceed the age at the end of enrollment,\r\nand must not be more than one year below it. Omitted means the age at the end of enrollment is used and\r\nthe response says so.", "format": "int32", "nullable": true } }, "additionalProperties": false, "description": "One diagnosis. No date: the benefit year is on the request and the model is concurrent, so a date would say\r\nnothing the request does not already say while making every request an identifiable record." }, "HhsDiagnosisStatus": { "enum": [ "Mapped", "NotInModel", "ExcludedByEdits", "Duplicate" ], "type": "string", "description": "What became of one submitted diagnosis." }, "HhsDrugCodeKind": { "enum": [ "Ndc", "Hcpcs" ], "type": "string", "description": "Which code space a submitted drug or procedure code came from." }, "HhsDrugInput": { "type": "object", "properties": { "ndc": { "type": "array", "items": { "type": "string" }, "description": "National drug codes, eleven characters, no dashes. Pharmacy claims only, as CMS requires." }, "hcpcs": { "type": "array", "items": { "type": "string" }, "description": "HCPCS codes, five characters. Any medical claim." } }, "additionalProperties": false }, "HhsDrugOutcomeInfo": { "required": [ "code", "normalizedCode", "kind", "status" ], "type": "object", "properties": { "code": { "type": "string", "description": "The code exactly as the caller sent it." }, "normalizedCode": { "type": "string", "description": "The code after normalization, which is what was looked up." }, "kind": { "$ref": "#/components/schemas/HhsDrugCodeKind" }, "status": { "$ref": "#/components/schemas/HhsDrugStatus" }, "drugCategory": { "type": "integer", "description": "The drug category it reached, before the drug hierarchy. Null when it reached none.", "format": "int32", "nullable": true }, "costFactor": { "type": "string", "description": "The additional cost factor it names, when it is in that table rather than the drug category one. Whether\r\nthe factor was paid is visible in `terms`: CMS's own rules can withhold it on age, or because a\r\ncondition or drug category the member holds blocks it.", "nullable": true }, "reason": { "type": "string", "description": "Why it reached none, when it reached none.", "nullable": true } }, "additionalProperties": false }, "HhsDrugStatus": { "enum": [ "Mapped", "NotInModel", "Duplicate", "MappedToCostFactor", "NoCostFactorRuleApplies", "NotReadForThisModelSet" ], "type": "string", "description": "What became of one submitted drug or procedure code." }, "HhsHierarchyDropInfo": { "required": [ "category", "supersededBy" ], "type": "object", "properties": { "category": { "type": "string", "description": "The category that was zeroed, for example `HHS_HCC021`." }, "supersededBy": { "type": "array", "items": { "type": "string" }, "description": "Every category the member reached that supersedes this one, in CMS's hierarchy-table order. Never\r\nempty." } }, "additionalProperties": false, "description": "One condition category the member reached and a higher one zeroed." }, "HhsMappingLookupResponse": { "required": [ "code", "normalizedCode", "inModel", "rows" ], "type": "object", "properties": { "code": { "type": "string", "description": "The code as the caller sent it." }, "normalizedCode": { "type": "string", "description": "The code as it was looked up: whitespace removed, upper-cased, the ICD-10-CM dot removed." }, "inModel": { "type": "boolean", "description": "Whether the crosswalk carries this code at all. A code it does not carry cannot change a score." }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/HhsMappingRow" }, "description": "One row per way the code can reach a condition category. A code appears more than once for the same\r\ncategory when different age or sex conditions select it." } }, "additionalProperties": false, "description": "Result of looking one diagnosis code up in an HHS-HCC (ACA) benefit year's crosswalk." }, "HhsMappingRow": { "required": [ "conditionCategory", "validInBenefitYear" ], "type": "object", "properties": { "conditionCategory": { "type": "string", "description": "The HHS-HCC condition category, e.g. `HHS_HCC021`." }, "validInBenefitYear": { "type": "boolean", "description": "Whether CMS marks the code valid for this benefit year. A row that is not valid is excluded before any\r\nage or sex edit is considered, so it is reported first here too." }, "mceAgeCondition": { "type": "string", "description": "Medicare Code Editor age restriction, e.g. \"0 <= age <= 17\", or null. Tested against the age when the\r\nservice happened (owner decision D1).", "nullable": true }, "ageEditCondition": { "type": "string", "description": "The model's own age edit, e.g. \"age >= 50\", or null. Tested against the age at the end of enrollment,\r\nwhich is a different age from the one above (owner decision D1).", "nullable": true }, "sexEdit": { "oneOf": [ { "enum": [ null ], "nullable": true }, { "$ref": "#/components/schemas/BeneficiarySex" } ] } }, "additionalProperties": false, "description": "One crosswalk row: a condition this code can reach, and what CMS requires of the member to reach it." }, "HhsMemberInput": { "required": [ "id", "ageAtEndOfEnrollment", "sex", "enrollmentMonths" ], "type": "object", "properties": { "id": { "type": "string", "description": "Opaque reference the caller uses to correlate the result. It is echoed back and never stored, and must\r\nnot be a member number, medical record number or any other identifier of a person." }, "ageAtEndOfEnrollment": { "type": "integer", "description": " Age in whole years on the last day of enrollment in the benefit year, which is CMS's `AGE_LAST`.\r\n It chooses the model set — infant, child or adult — and the age band inside it.\r\n Capped at 90 and refused above it. The model's top adult band is 60 and over, so an exact age above\r\nthat changes no score, and reporting one would be reporting an identifier for nothing in return.", "format": "int32" }, "sex": { "$ref": "#/components/schemas/BeneficiarySex" }, "enrollmentMonths": { "type": "integer", "description": "Whole months enrolled in the benefit year, 1 to 12. CMS's day ranges are 1–31 days = 1, up to\r\n336–366 = 12. Used for the enrollment-duration terms, which apply only to a member with a condition.", "format": "int32" } }, "additionalProperties": false }, "HhsMemberScore": { "required": [ "memberId", "modelSet", "diagnoses", "drugs", "categories", "supersededCategories", "drugCategories", "supersededDrugCategories", "terms", "score", "csrFactor", "csrAdjustedScore", "assumptions", "warnings" ], "type": "object", "properties": { "memberId": { "type": "string", "description": "The caller's own reference, echoed back." }, "modelSet": { "$ref": "#/components/schemas/HhsModelSet" }, "diagnoses": { "type": "array", "items": { "$ref": "#/components/schemas/HhsDiagnosisOutcomeInfo" }, "description": "What became of every submitted diagnosis. Nothing is dropped silently." }, "drugs": { "type": "array", "items": { "$ref": "#/components/schemas/HhsDrugOutcomeInfo" }, "description": "What became of every drug and procedure code that was looked up: exactly one entry per submitted code,\r\nnever more, so an answer stays proportional to the request that asked for it. Empty outside the adult\r\nmodel, where CMS reads none of them and a warning names how many were sent instead." }, "categories": { "type": "array", "items": { "type": "string" }, "description": "The condition categories the member holds, after hierarchies and before grouping." }, "supersededCategories": { "type": "array", "items": { "$ref": "#/components/schemas/HhsHierarchyDropInfo" }, "description": "Every category the member reached that a higher one zeroed, and which categories superseded it." }, "drugCategories": { "type": "array", "items": { "type": "integer", "format": "int32" }, "description": "The drug categories the member holds. Always empty outside the adult model." }, "supersededDrugCategories": { "type": "array", "items": { "$ref": "#/components/schemas/HhsRxcDropInfo" }, "description": "The same for drug categories: what a higher drug category zeroed, and what zeroed it." }, "terms": { "type": "array", "items": { "$ref": "#/components/schemas/HhsScoreTermInfo" }, "description": "Every variable that contributed, with what it paid at this member's metal level." }, "score": { "type": "number", "description": "The model score, rounded as CMS rounds it.", "format": "double" }, "csrFactor": { "type": "number", "description": "The cost-sharing factor the member's indicator selects.", "format": "double" }, "csrAdjustedScore": { "type": "number", "description": "The score after that factor. This is the figure a plan is paid on.", "format": "double" }, "assumptions": { "type": "array", "items": { "type": "string" }, "description": "Anything the engine had to supply because the request did not." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Anything worth the caller's attention that did not stop the score." }, "providerView": { "oneOf": [ { "enum": [ null ], "nullable": true }, { "$ref": "#/components/schemas/ProviderView" } ] } }, "additionalProperties": false, "description": "One member's HHS-HCC score and everything that produced it, with no model on it." }, "HhsModelInfo": { "required": [ "version", "benefitYear", "packageLabel", "isDefault", "tables", "ruleDecisions", "limitations" ], "type": "object", "properties": { "version": { "type": "string", "description": "CMS's classification version, for example `V08`." }, "benefitYear": { "type": "integer", "format": "int32" }, "packageLabel": { "type": "string", "description": "The CMS package the tables were taken from." }, "isDefault": { "type": "boolean", "description": "Whether this is the pack a request that names no benefit year is scored against. Reported for the same\r\nreason the Medicare descriptor reports it: a caller reading the model list otherwise cannot tell which\r\npack an omitted selector would pick, and would have to score something to find out." }, "tables": { "$ref": "#/components/schemas/HhsTableCounts" }, "ruleDecisions": { "type": "array", "items": { "$ref": "#/components/schemas/RuleDecisionInfo" }, "description": "Where this engine scores differently from CMS's published software, and what CMS's software does\r\ninstead. Reported on every response so a caller reconciling against CMS sees the difference rather than\r\ndiscovering it." }, "limitations": { "type": "array", "items": { "type": "string" }, "description": "Known differences from CMS production logic that callers should be aware of." } }, "additionalProperties": false }, "HhsModelSelector": { "type": "object", "properties": { "benefitYear": { "type": "integer", "description": "The plan year being scored. Omitted means the service's default benefit year.", "format": "int32", "nullable": true }, "version": { "type": "string", "description": "CMS's classification version, for example `V08`. Omitted means the only one loaded.", "nullable": true } }, "additionalProperties": false }, "HhsModelSet": { "enum": [ "Infant", "Child", "Adult" ], "type": "string", "description": "Which of CMS's three model sets scored the member. Decided by age at the end of enrollment, never by the\r\ncaller: CMS calibrates infants, children and adults as separate models with different variables." }, "HhsPlanInput": { "required": [ "metalLevel", "csrIndicator", "market" ], "type": "object", "properties": { "metalLevel": { "$ref": "#/components/schemas/MetalLevel" }, "csrIndicator": { "type": "integer", "description": "The member-level cost-sharing reduction indicator, 1 to 11, from CMS's table. The mapping from a plan's\r\nHIOS variant to this indicator is state-specific, so it stays with the caller; the response echoes the\r\nfactor that was applied.", "format": "int32" }, "market": { "$ref": "#/components/schemas/InsuranceMarket" } }, "additionalProperties": false }, "HhsRxcDropInfo": { "required": [ "drugCategory", "supersededBy" ], "type": "object", "properties": { "drugCategory": { "type": "integer", "format": "int32" }, "supersededBy": { "type": "array", "items": { "type": "integer", "format": "int32" }, "description": "Every drug category the member holds that supersedes it, in CMS's table order." } }, "additionalProperties": false, "description": "One drug category the member reached and a higher one zeroed." }, "HhsScoreOptions": { "type": "object", "properties": { "view": { "$ref": "#/components/schemas/ScoreView" }, "includeAttribution": { "type": "boolean", "description": "Work out how much of the score is due to each submitted code (§6). Default false." } }, "additionalProperties": false, "description": "What the caller wants back besides the score." }, "HhsScoreRequest": { "required": [ "member", "plan" ], "type": "object", "properties": { "member": { "$ref": "#/components/schemas/HhsMemberInput" }, "plan": { "$ref": "#/components/schemas/HhsPlanInput" }, "diagnoses": { "type": "array", "items": { "$ref": "#/components/schemas/HhsDiagnosisRequestInput" }, "description": "Diagnoses from services in the benefit year. Each gets an outcome in the response." }, "drugs": { "oneOf": [ { "enum": [ null ], "nullable": true }, { "$ref": "#/components/schemas/HhsDrugInput" } ] }, "model": { "oneOf": [ { "enum": [ null ], "nullable": true }, { "$ref": "#/components/schemas/HhsModelSelector" } ] }, "documentationCandidates": { "type": "array", "items": { "$ref": "#/components/schemas/HhsDiagnosisRequestInput" }, "description": "Conditions being considered but not documented today, for the provider view only. They are scored\r\nseparately to work out what documenting them would be worth, and are never counted into the member's own\r\nscore: the answer's score is the same whichever view is asked for." }, "priorPeriodCodes": { "type": "array", "items": { "$ref": "#/components/schemas/HhsDiagnosisRequestInput" }, "description": "Conditions documented earlier in the benefit year, for the provider view only. HHS-HCC is concurrent, so\r\nthe gap that matters is within this same year rather than last one. Codes only: this carries no dates." }, "contract": { "oneOf": [ { "enum": [ null ], "nullable": true }, { "$ref": "#/components/schemas/ContractInput" } ] }, "options": { "$ref": "#/components/schemas/HhsScoreOptions" } }, "additionalProperties": false, "description": "One member to score against the HHS-HCC (ACA) model." }, "HhsScoreResponse": { "required": [ "memberId", "model", "modelSet", "diagnoses", "drugs", "categories", "supersededCategories", "drugCategories", "supersededDrugCategories", "terms", "score", "csrFactor", "csrAdjustedScore", "assumptions", "warnings" ], "type": "object", "properties": { "memberId": { "type": "string", "description": "The caller's own reference, echoed back." }, "model": { "$ref": "#/components/schemas/HhsModelInfo" }, "modelSet": { "$ref": "#/components/schemas/HhsModelSet" }, "diagnoses": { "type": "array", "items": { "$ref": "#/components/schemas/HhsDiagnosisOutcomeInfo" }, "description": "What became of every submitted diagnosis. Nothing is dropped silently." }, "drugs": { "type": "array", "items": { "$ref": "#/components/schemas/HhsDrugOutcomeInfo" }, "description": "What became of every drug and procedure code that was looked up: exactly one entry per submitted code,\r\nnever more, so an answer stays proportional to the request that asked for it. Empty outside the adult\r\nmodel, where CMS reads none of them and a warning names how many were sent instead." }, "categories": { "type": "array", "items": { "type": "string" }, "description": "The condition categories the member holds, after hierarchies and before grouping." }, "supersededCategories": { "type": "array", "items": { "$ref": "#/components/schemas/HhsHierarchyDropInfo" }, "description": "Every category the member reached that a higher one zeroed, and which categories superseded it,\r\nordered by category. Empty when nothing was superseded. IReadOnlyList<string> HhsScoreResponse.Categories holds what survived;\r\nthis holds what did not, so a coder can see that a condition was documented and outranked rather than\r\nnever documented at all." }, "drugCategories": { "type": "array", "items": { "type": "integer", "format": "int32" }, "description": "The drug categories the member holds. Always empty outside the adult model." }, "supersededDrugCategories": { "type": "array", "items": { "$ref": "#/components/schemas/HhsRxcDropInfo" }, "description": "The same for drug categories: what a higher drug category zeroed, and what zeroed it." }, "terms": { "type": "array", "items": { "$ref": "#/components/schemas/HhsScoreTermInfo" }, "description": "Every variable that contributed, with what it paid at this member's metal level." }, "score": { "type": "number", "description": "The model score, rounded as CMS rounds it.", "format": "double" }, "csrFactor": { "type": "number", "description": "The cost-sharing factor the member's indicator selects.", "format": "double" }, "csrAdjustedScore": { "type": "number", "description": "The score after that factor. This is the figure a plan is paid on.", "format": "double" }, "assumptions": { "type": "array", "items": { "type": "string" }, "description": "Anything the engine had to supply because the request did not." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Anything scored but worth a second look, such as a bundled mother and infant claim." }, "attribution": { "oneOf": [ { "enum": [ null ], "nullable": true }, { "$ref": "#/components/schemas/ScoreAttributionInfo" } ] }, "providerView": { "oneOf": [ { "enum": [ null ], "nullable": true }, { "$ref": "#/components/schemas/ProviderView" } ] } }, "additionalProperties": false, "description": "One member's HHS-HCC score and everything that produced it, so a caller can see why rather than take a\r\nnumber on trust." }, "HhsScoreTermInfo": { "required": [ "variable", "coefficient" ], "type": "object", "properties": { "variable": { "type": "string", "description": "The coefficient variable, exactly as CMS names it." }, "coefficient": { "type": "number", "format": "double" } }, "additionalProperties": false }, "HhsTableCounts": { "required": [ "mappingRows", "distinctDiagnosisCodes", "conditionCategories", "drugCategories", "distinctDrugCodes", "hierarchyRules", "conditionGroups", "drugInteractions" ], "type": "object", "properties": { "mappingRows": { "type": "integer", "description": "Rows in the crosswalk. More than the codes, because one code reaches a category several ways.", "format": "int32" }, "distinctDiagnosisCodes": { "type": "integer", "format": "int32" }, "conditionCategories": { "type": "integer", "description": "Condition categories the crosswalk can reach.", "format": "int32" }, "drugCategories": { "type": "integer", "description": "Drug categories read from NDC and HCPCS codes, for the adult model only.", "format": "int32" }, "distinctDrugCodes": { "type": "integer", "format": "int32" }, "hierarchyRules": { "type": "integer", "format": "int32" }, "conditionGroups": { "type": "integer", "description": "Condition groups in the adult and child models, which pay in place of their members.", "format": "int32" }, "drugInteractions": { "type": "integer", "description": "Drug-category interactions, which pay a drug category only beside a condition.", "format": "int32" } }, "additionalProperties": false, "description": "How much of CMS's model a pack carries. Deliberately not `TableCounts`, the Medicare shape: this model\r\nhas drug categories, condition groups and three model sets, and none of them fit a field named for segments\r\nand payment HCCs." }, "HighCostRiskPoolInput": { "required": [ "premiumSubjectToCharge", "attachmentPoint", "coinsuranceRate", "chargeRate" ], "type": "object", "properties": { "paidClaims": { "type": "array", "items": { "type": "number", "format": "double" }, "description": "What the issuer paid for each enrollee, one entry per enrollee." }, "premiumSubjectToCharge": { "type": "number", "description": "The issuer's premium in the market the charge rate applies to.", "format": "double" }, "attachmentPoint": { "type": "number", "description": "The paid-claims figure an enrollee has to exceed before the pool pays: $1,000,000 for 2025.", "format": "double" }, "coinsuranceRate": { "type": "number", "description": "The share of the excess the pool pays, as a fraction: sixty per cent is 0.60, not 60.", "format": "double" }, "chargeRate": { "type": "number", "description": "The share of premium that funds the pool, as a fraction: 0.47 per cent is 0.0047, not 0.47.", "format": "double" } }, "additionalProperties": false, "description": "What the high-cost risk pool is asked to estimate, if anything." }, "HighCostRiskPoolResult": { "required": [ "payment", "charge", "enrolleesAboveAttachment" ], "type": "object", "properties": { "payment": { "type": "number", "description": "What the pool pays towards claims above the attachment point.", "format": "double" }, "charge": { "type": "number", "description": "What the issuer pays in to fund the pool.", "format": "double" }, "enrolleesAboveAttachment": { "type": "integer", "description": "How many enrollees were above the attachment point. Never which.", "format": "int32" } }, "additionalProperties": false, "description": "What the high-cost risk pool is estimated to pay an issuer, and to charge them." }, "HttpValidationProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "status": { "type": "integer", "format": "int32", "nullable": true }, "detail": { "type": "string", "nullable": true }, "instance": { "type": "string", "nullable": true }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "additionalProperties": false }, "InsuranceMarket": { "enum": [ "Individual", "SmallGroup", "Merged" ], "type": "string", "description": "The market a plan is sold in." }, "LargeGroupPlanInput": { "type": "object", "properties": { "metalLevel": { "oneOf": [ { "enum": [ null ], "nullable": true }, { "$ref": "#/components/schemas/MetalLevel" } ] }, "actuarialValue": { "type": "number", "description": "The plan's actuarial value as a fraction, mapped to the nearest tier: Bronze 0.60, Silver 0.70, Gold 0.80,\r\nPlatinum 0.90. A value exactly between two tiers is refused naming both, rather than resolved by a rule\r\nnobody chose.", "format": "double", "nullable": true } }, "additionalProperties": false, "description": "Which of CMS's metal-level models to score against. Send exactly one of these." }, "LargeGroupProxyBatchScoreItem": { "required": [ "member" ], "type": "object", "properties": { "correlationId": { "type": "string", "description": "Your own reference for this item, echoed back on its result.", "nullable": true }, "member": { "$ref": "#/components/schemas/HhsMemberInput" }, "diagnoses": { "type": "array", "items": { "$ref": "#/components/schemas/HhsDiagnosisRequestInput" } }, "drugs": { "oneOf": [ { "enum": [ null ], "nullable": true }, { "$ref": "#/components/schemas/HhsDrugInput" } ] } }, "additionalProperties": false, "description": "One member in a large-group proxy batch: the member and their codes, and no plan of their own." }, "LargeGroupProxyBatchScoreRequest": { "required": [ "plan", "items" ], "type": "object", "properties": { "model": { "oneOf": [ { "enum": [ null ], "nullable": true }, { "$ref": "#/components/schemas/HhsModelSelector" } ] }, "plan": { "$ref": "#/components/schemas/LargeGroupPlanInput" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/LargeGroupProxyBatchScoreItem" } } }, "additionalProperties": false, "description": "Many large-group members under one model and one metal level, in a single call." }, "LargeGroupProxyBatchScoreResponse": { "required": [ "purpose", "isOfficialPayerScore", "disclaimer", "model", "planModel", "succeeded", "failed", "results" ], "type": "object", "properties": { "purpose": { "type": "string", "description": "Always string LargeGroupProxyScoreResponse.LargeGroupProxy." }, "isOfficialPayerScore": { "type": "boolean", "description": "Always false. No payer pays on any number in here." }, "disclaimer": { "type": "string", "description": "Always string LargeGroupProxyScoreResponse.FixedDisclaimer." }, "model": { "$ref": "#/components/schemas/HhsModelInfo" }, "planModel": { "$ref": "#/components/schemas/MetalLevelChoice" }, "succeeded": { "type": "integer", "format": "int32" }, "failed": { "type": "integer", "format": "int32" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/LargeGroupProxyBatchScoreResult" }, "description": "Every item, in the order supplied." } }, "additionalProperties": false, "description": "Proxy scores for many members, labelled exactly as the single answer is." }, "LargeGroupProxyBatchScoreResult": { "required": [ "memberId" ], "type": "object", "properties": { "correlationId": { "type": "string", "nullable": true }, "memberId": { "type": "string" }, "score": { "oneOf": [ { "enum": [ null ], "nullable": true }, { "$ref": "#/components/schemas/HhsMemberScore" } ] }, "errors": { "type": "array", "items": { "type": "string" }, "description": "Why this item has no score. Null when it has one.", "nullable": true } }, "additionalProperties": false, "description": "One item's outcome: a score, or the reasons it has none." }, "LargeGroupProxyScoreRequest": { "required": [ "member", "plan" ], "type": "object", "properties": { "member": { "$ref": "#/components/schemas/HhsMemberInput" }, "plan": { "$ref": "#/components/schemas/LargeGroupPlanInput" }, "diagnoses": { "type": "array", "items": { "$ref": "#/components/schemas/HhsDiagnosisRequestInput" }, "description": "Diagnoses from services in the benefit year. Each gets an outcome in the response." }, "drugs": { "oneOf": [ { "enum": [ null ], "nullable": true }, { "$ref": "#/components/schemas/HhsDrugInput" } ] }, "model": { "oneOf": [ { "enum": [ null ], "nullable": true }, { "$ref": "#/components/schemas/HhsModelSelector" } ] } }, "additionalProperties": false, "description": "Score a member of a large-group plan with the HHS-HCC model, as a proxy." }, "LargeGroupProxyScoreResponse": { "required": [ "purpose", "isOfficialPayerScore", "disclaimer", "model", "planModel", "score" ], "type": "object", "properties": { "purpose": { "type": "string", "description": "Always string LargeGroupProxyScoreResponse.LargeGroupProxy." }, "isOfficialPayerScore": { "type": "boolean", "description": "Always false. No payer pays on this number." }, "disclaimer": { "type": "string", "description": "Always string LargeGroupProxyScoreResponse.FixedDisclaimer." }, "model": { "$ref": "#/components/schemas/HhsModelInfo" }, "planModel": { "$ref": "#/components/schemas/MetalLevelChoice" }, "score": { "$ref": "#/components/schemas/HhsMemberScore" } }, "additionalProperties": false, "description": "A proxy score, labelled as one everywhere it can be." }, "MappingExclusion": { "required": [ "conditionCategory", "reason", "condition" ], "type": "object", "properties": { "conditionCategory": { "type": "integer", "format": "int32" }, "reason": { "$ref": "#/components/schemas/ExclusionReason" }, "condition": { "type": "string", "description": "The CMS condition text, e.g. \"age >= 15\" or \"sex = 1\"." } }, "additionalProperties": false }, "MappingLookupResponse": { "required": [ "code", "normalizedCode", "inModel", "rows" ], "type": "object", "properties": { "code": { "type": "string" }, "normalizedCode": { "type": "string" }, "inModel": { "type": "boolean" }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/MappingRow" } } }, "additionalProperties": false, "description": "Result of looking one ICD-10-CM code up in a model's mapping table." }, "MappingRow": { "required": [ "conditionCategory", "hccLabel" ], "type": "object", "properties": { "conditionCategory": { "type": "integer", "format": "int32" }, "hccLabel": { "type": "string" }, "mceAgeCondition": { "type": "string", "description": "Medicare Code Editor age restriction, e.g. \"0 <= age <= 17\", or null.", "nullable": true }, "ageEditCondition": { "type": "string", "description": "Model age edit, e.g. \"age >= 50\", or null.", "nullable": true }, "sexEdit": { "oneOf": [ { "enum": [ null ], "nullable": true }, { "$ref": "#/components/schemas/BeneficiarySex" } ] } }, "additionalProperties": false }, "MedicaidMemberIndex": { "required": [ "memberId", "score" ], "type": "object", "properties": { "correlationId": { "type": "string", "nullable": true }, "memberId": { "type": "string" }, "index": { "type": "number", "description": "This member's model score divided by decimal MedicaidPopulation.MeanScore, to three places. 1.000\r\nis exactly average for this population; 2.000 is twice its risk. Null when the call carried one\r\nmember, because a ratio to a one-member mean is 1.000 whoever they are.", "format": "double", "nullable": true }, "score": { "$ref": "#/components/schemas/HhsMemberScore" } }, "additionalProperties": false, "description": "One member's place in the population." }, "MedicaidMemberInput": { "required": [ "id", "ageAtEndOfEnrollment", "sex", "enrollmentMonths" ], "type": "object", "properties": { "correlationId": { "type": "string", "description": "Your own reference for this member, echoed back. Optional.", "nullable": true }, "id": { "type": "string", "description": "An opaque reference. Never a Medicaid identifier, a medical record number, or anything else that\r\nidentifies a person." }, "ageAtEndOfEnrollment": { "type": "integer", "description": "Whole years at the end of the member's enrollment in the year, capped at 90.", "format": "int32" }, "sex": { "$ref": "#/components/schemas/BeneficiarySex" }, "enrollmentMonths": { "type": "integer", "description": "Whole months enrolled, 1 to 12.", "format": "int32" }, "diagnoses": { "type": "array", "items": { "$ref": "#/components/schemas/HhsDiagnosisRequestInput" } }, "drugs": { "oneOf": [ { "enum": [ null ], "nullable": true }, { "$ref": "#/components/schemas/HhsDrugInput" } ] } }, "additionalProperties": false, "description": "One member of the population." }, "MedicaidModelAssumptions": { "required": [ "metalLevel", "metalLevelReason", "market", "csrIndicator" ], "type": "object", "properties": { "metalLevel": { "$ref": "#/components/schemas/MetalLevel" }, "metalLevelReason": { "type": "string", "description": "Why that one." }, "market": { "$ref": "#/components/schemas/InsuranceMarket" }, "csrIndicator": { "type": "integer", "description": "The cost-sharing reduction indicator used. Always the one whose factor is 1.00, so the adjusted score\r\nequals the model score and nothing is scaled by a variant Medicaid does not have.", "format": "int32" } }, "additionalProperties": false, "description": "What the route fixed because Medicaid has no equivalent, each with the reason." }, "MedicaidPopulation": { "required": [ "members", "meanScore", "assumptions" ], "type": "object", "properties": { "members": { "type": "integer", "format": "int32" }, "meanScore": { "type": "number", "description": "The mean model score this population was divided by. The denominator, reported.", "format": "double" }, "assumptions": { "$ref": "#/components/schemas/MedicaidModelAssumptions" } }, "additionalProperties": false, "description": "What the indices are relative to, and what had to be assumed to get them." }, "MedicaidRiskIndexRequest": { "type": "object", "properties": { "model": { "oneOf": [ { "enum": [ null ], "nullable": true }, { "$ref": "#/components/schemas/HhsModelSelector" } ] }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/MedicaidMemberInput" }, "description": "The population. Every member is scored, and every index is relative to this set." } }, "additionalProperties": false, "description": "A Medicaid population, scored for relative risk." }, "MedicaidRiskIndexResponse": { "required": [ "purpose", "isOfficialPayerScore", "disclaimer", "model", "population", "members" ], "type": "object", "properties": { "purpose": { "type": "string", "description": "Always string MedicaidRiskIndexResponse.MedicaidRelativeRisk." }, "isOfficialPayerScore": { "type": "boolean", "description": "Always false. No state pays on this number." }, "disclaimer": { "type": "string", "description": "Always string MedicaidRiskIndexResponse.FixedDisclaimer." }, "model": { "$ref": "#/components/schemas/HhsModelInfo" }, "population": { "$ref": "#/components/schemas/MedicaidPopulation" }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/MedicaidMemberIndex" }, "description": "Every member, in the order supplied." }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/ScoringWarning" }, "description": "What a caller needs to know about this answer beyond the numbers in it." } }, "additionalProperties": false, "description": "Relative risk across a Medicaid population. Not a score anyone pays on." }, "MetalLevel": { "enum": [ "Platinum", "Gold", "Silver", "Bronze", "Catastrophic" ], "type": "string", "description": "A plan's generosity level. CMS calibrates a separate set of coefficients for each, so the same member scores\r\ndifferently on each, and the level is not a property of the member.\r\nSend the name, for example `Silver`; letter case does not matter. CMS's single-letter codes (P, G, S,\r\nB, C) are not accepted, because a code is easy to send by accident and impossible to read by eye." }, "MetalLevelChoice": { "required": [ "metalLevel", "selection" ], "type": "object", "properties": { "metalLevel": { "$ref": "#/components/schemas/MetalLevel" }, "selection": { "$ref": "#/components/schemas/MetalLevelSelection" }, "actuarialValue": { "type": "number", "description": "The actuarial value the level was mapped from, when it was.", "format": "double", "nullable": true } }, "additionalProperties": false, "description": "Which metal-level model was used, and how it was chosen." }, "MetalLevelSelection": { "enum": [ "Stated", "MappedFromActuarialValue" ], "type": "string", "description": "How the metal-level model was chosen for a proxy score." }, "ModelDescriptor": { "required": [ "family", "version", "paymentYear", "packageLabel", "isDefault", "ageAsOfDate", "segments", "tables", "adjustments", "limitations" ], "type": "object", "properties": { "family": { "$ref": "#/components/schemas/ModelFamily" }, "version": { "type": "string" }, "paymentYear": { "type": "integer", "format": "int32" }, "packageLabel": { "type": "string" }, "isDefault": { "type": "boolean" }, "ageAsOfDate": { "type": "string", "format": "date" }, "segments": { "type": "array", "items": { "$ref": "#/components/schemas/SegmentDescriptor" } }, "tables": { "$ref": "#/components/schemas/TableCounts" }, "adjustments": { "$ref": "#/components/schemas/PaymentAdjustments" }, "limitations": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false, "description": "Describes one loaded model pack." }, "ModelFamily": { "enum": [ "CmsHcc", "Esrd", "RxHcc" ], "type": "string", "description": "CMS risk-adjustment model family. Only ModelFamily.CmsHcc ships a model pack." }, "ModelInfo": { "required": [ "family", "version", "paymentYear", "packageLabel", "ageAsOfDate", "limitations" ], "type": "object", "properties": { "family": { "$ref": "#/components/schemas/ModelFamily" }, "version": { "type": "string" }, "paymentYear": { "type": "integer", "format": "int32" }, "packageLabel": { "type": "string", "description": "The CMS package the tables came from, e.g. CMS_HCC_v28_2026_T_package_v3." }, "ageAsOfDate": { "type": "string", "description": "The date the submitted age must be measured as of (February 1 of the payment year).", "format": "date" }, "limitations": { "type": "array", "items": { "type": "string" }, "description": "Known differences from CMS's full production logic that callers should be aware of." }, "ruleDecisions": { "type": "array", "items": { "$ref": "#/components/schemas/RuleDecisionInfo" }, "description": "Where CMS's own published artefacts contradict each other and this engine had to choose." } }, "additionalProperties": false }, "ModelSelector": { "type": "object", "properties": { "family": { "oneOf": [ { "enum": [ null ], "nullable": true }, { "$ref": "#/components/schemas/ModelFamily" } ] }, "version": { "type": "string", "description": "Model version label, e.g. \"V28\".", "nullable": true }, "paymentYear": { "type": "integer", "format": "int32", "nullable": true } }, "additionalProperties": false, "description": "Identifies a model pack. Any omitted part falls back to the service default." }, "MoreSpecificCondition": { "required": [ "category", "codeCount" ], "type": "object", "properties": { "category": { "type": "string" }, "categoryLabel": { "type": "string", "description": "CMS's own description of it, where the model publishes one.", "nullable": true }, "codeCount": { "type": "integer", "description": "How many distinct ICD-10-CM codes could reach it for this member, so its breadth is visible without\r\nthe codes being present. Never zero: a condition no code of theirs can reach is not named at all.", "format": "int32" } }, "additionalProperties": false, "description": "One condition the model ranks above a documented one." }, "OriginalEntitlementReason": { "enum": [ "Aged", "Disability", "Esrd", "DisabilityAndEsrd" ], "type": "string", "description": "Original reason for Medicare entitlement (CMS OREC)." }, "PaymentAdjustments": { "required": [ "normalizationFactor", "codingIntensityAdjustment", "source" ], "type": "object", "properties": { "normalizationFactor": { "type": "number", "format": "double" }, "codingIntensityAdjustment": { "type": "number", "description": "MA coding-pattern difference adjustment as a fraction (0.059 for CY2026).", "format": "double" }, "source": { "type": "string" } }, "additionalProperties": false }, "PlanTransferResult": { "required": [ "planId", "planLiabilityRiskScore", "perMemberPerMonth", "total" ], "type": "object", "properties": { "planId": { "type": "string", "description": "The plan, as the caller named it." }, "planLiabilityRiskScore": { "type": "number", "description": "The plan liability risk score the figures were computed from.", "format": "double" }, "perMemberPerMonth": { "type": "number", "description": "The transfer per member per month. Positive is a receipt, negative is a charge.", "format": "double" }, "total": { "type": "number", "description": "The same figure over the plan's billable member months.", "format": "double" }, "range": { "oneOf": [ { "enum": [ null ], "nullable": true }, { "$ref": "#/components/schemas/TransferRangeResult" } ] } }, "additionalProperties": false, "description": "What one plan pays into, or receives from, the pool." }, "PriorConditionNotPrompted": { "required": [ "category", "priorCodes", "outcome", "outrankedBy" ], "type": "object", "properties": { "category": { "type": "string", "description": "The condition category, in the model's own vocabulary (`HCC18`, `HHS_HCC021`)." }, "categoryLabel": { "type": "string", "description": "CMS's own description of it, where the model publishes one.", "nullable": true }, "priorCodes": { "type": "array", "items": { "type": "string" }, "description": "The prior-period codes that reached this condition, normalized." }, "outcome": { "$ref": "#/components/schemas/PriorConditionOutcome" }, "outrankedBy": { "type": "array", "items": { "type": "string" }, "description": "The conditions held this period that outrank this one, in the model's order. Always empty for\r\nPriorConditionOutcome.Documented; never empty for\r\nPriorConditionOutcome.OutrankedByHigherCondition, which is defined by it. For\r\nPriorConditionOutcome.DocumentedButNotHeld it names the higher conditions where a\r\nhierarchy is the reason, and is empty where a model recode is." } }, "additionalProperties": false, "description": "One condition the prior period documented that needs no prompt, and why." }, "PriorConditionOutcome": { "enum": [ "Documented", "DocumentedButNotHeld", "OutrankedByHigherCondition" ], "type": "string", "description": "Why a condition the prior period documented is not prompted for." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "status": { "type": "integer", "format": "int32", "nullable": true }, "detail": { "type": "string", "nullable": true }, "instance": { "type": "string", "nullable": true } }, "additionalProperties": false }, "PromptSource": { "required": [ "table", "release" ], "type": "object", "properties": { "table": { "type": "string", "description": "The table this pack read the mapping from, as the pack names it — `mappings.csv` for CMS-HCC, whose\r\nfiles this service renames, and CMS's own filename for HHS-HCC, whose it does not. Together with\r\nstring PromptSource.Release it locates the row: the pack's `derivation.md` ties each file to the CMS\r\npackage it was copied from, with hashes." }, "release": { "type": "string", "description": "The CMS package it was published in." } }, "additionalProperties": false, "description": "Where a prompt came from, so it can be checked rather than believed." }, "ProviderView": { "required": [ "revenueImpact" ], "type": "object", "properties": { "revenueImpact": { "$ref": "#/components/schemas/RevenueImpact" }, "documentation": { "oneOf": [ { "enum": [ null ], "nullable": true }, { "$ref": "#/components/schemas/DocumentationSupport" } ] } }, "additionalProperties": false, "description": "What the provider view adds. The member's score is unchanged by its presence." }, "RafSegment": { "enum": [ "CommunityNonDualAged", "CommunityPartialDualAged", "CommunityFullDualAged", "CommunityNonDualDisabled", "CommunityPartialDualDisabled", "CommunityFullDualDisabled", "Institutional", "NewEnrollee", "NewEnrolleeChronicSnp" ], "type": "string", "nullable": true }, "RecapturePrompt": { "required": [ "category", "priorCodes", "prompt", "source" ], "type": "object", "properties": { "category": { "type": "string", "description": "The condition category, in the model's own vocabulary (`HCC18`, `HHS_HCC021`)." }, "categoryLabel": { "type": "string", "description": "CMS's own description of it, where the model publishes one.", "nullable": true }, "priorCodes": { "type": "array", "items": { "type": "string" }, "description": "The prior-period codes that reached this condition, normalized." }, "prompt": { "type": "string", "description": "Always string DocumentationSupport.EvaluatePrompt." }, "source": { "$ref": "#/components/schemas/PromptSource" } }, "additionalProperties": false, "description": "One condition documented in the prior period that this period neither reaches nor outranks." }, "RevenueImpact": { "required": [ "status", "message" ], "type": "object", "properties": { "status": { "$ref": "#/components/schemas/RevenueImpactStatus" }, "message": { "type": "string" }, "arrangement": { "oneOf": [ { "enum": [ null ], "nullable": true }, { "$ref": "#/components/schemas/ContractArrangement" } ] }, "formula": { "type": "string", "description": "The formula that was applied, in the same words as the terms.", "nullable": true }, "estimatedAmount": { "type": "number", "description": "The revenue difference, exact and unrounded. No contract here stated a rounding rule, so rounding for\r\npresentation is yours: inventing one would be this estimate guessing a term.", "format": "double", "nullable": true }, "scoreChange": { "oneOf": [ { "enum": [ null ], "nullable": true }, { "$ref": "#/components/schemas/ScoreChangeInfo" } ] }, "terms": { "type": "array", "items": { "$ref": "#/components/schemas/ContractTermInfo" }, "description": "Every value the estimate used, with where it came from." }, "missingTerms": { "type": "array", "items": { "type": "string" }, "description": "Every term the estimate could not use, each named with why." }, "validation": { "type": "string", "description": "Set whenever an amount was produced. `FormulaTestedNotReconciled` means the formula is tested but has\r\nnot yet been checked against a real settlement or remittance statement for this arrangement type.", "nullable": true } }, "additionalProperties": false, "description": "What a change in the member's documented conditions is worth under the contract supplied." }, "RevenueImpactStatus": { "enum": [ "Estimated", "Unknown", "NoRiskAdjustmentLink" ], "type": "string", "description": "What an estimate could be made of." }, "RuleDecisionInfo": { "required": [ "id", "question", "ruling", "cmsSoftwareBehavior" ], "type": "object", "properties": { "id": { "type": "string", "description": "The decision's identifier in the design record, for example `D2`." }, "question": { "type": "string" }, "ruling": { "type": "string", "description": "What this engine does." }, "cmsSoftwareBehavior": { "type": "string", "description": "What CMS's published software does instead." } }, "additionalProperties": false, "description": "One place CMS's published software and CMS's published instructions disagree, and what this engine does." }, "ScoreAttributionInfo": { "required": [ "method", "scoreAttributed", "baseline", "attributed", "inputs" ], "type": "object", "properties": { "method": { "$ref": "#/components/schemas/AttributionMethod" }, "scoreAttributed": { "type": "string", "description": "The score these figures are about, named so there is no doubt which of a response's several it is. The\r\nfactors that turn it into what a plan is paid on apply to every input alike, so attributing that instead\r\nwould scale every figure by the same amount and round each one again." }, "baseline": { "type": "number", "description": "The score with none of the clinical inputs: age, sex and enrollment alone. It is not attributed to any\r\ninput because no input earned it, and leaving it out of the shares is what lets them add up.", "format": "double" }, "attributed": { "type": "number", "description": "What the clinical inputs added to that baseline, which the shares account for.", "format": "double" }, "exactLimit": { "type": "integer", "description": "The most inputs that can be attributed exactly, set only when there were more than that and shares were\r\ntherefore withheld. Null when every input got a share.", "format": "int32", "nullable": true }, "roundingResidual": { "type": "number", "description": "What rounding the shares left over: decimal ScoreAttributionInfo.Attributed minus the shares as reported. Null when the\r\nmethod reports no shares.", "format": "double", "nullable": true }, "inputs": { "type": "array", "items": { "$ref": "#/components/schemas/AttributedInput" }, "description": "One entry per input that reaches a condition the model pays on, in the order the codes were submitted.\r\nInputs reaching nothing are absent: they cannot move the score, so they have no share, and their own\r\noutcome already says why they reached nothing." } }, "additionalProperties": false, "description": "How much of the score is due to each clinical input (§6)." }, "ScoreChangeInfo": { "required": [ "basis", "without", "with", "delta" ], "type": "object", "properties": { "basis": { "$ref": "#/components/schemas/ContractScoreBasis" }, "without": { "type": "number", "description": "The member's score as documented today. This is the score reported elsewhere in the answer.", "format": "double" }, "with": { "type": "number", "description": "The same member with the documentation candidates added.", "format": "double" }, "delta": { "type": "number", "format": "double" } }, "additionalProperties": false, "description": "The two scores a revenue estimate rests on, so the difference can be checked rather than taken." }, "ScoreOptions": { "type": "object", "properties": { "includeTerms": { "type": "boolean", "description": "Include the per-variable term breakdown on every segment. Default true." }, "includeAllSegments": { "type": "boolean", "description": "Return every segment's score, not just the selected one (useful for what-if views: dual status or institutional\r\nstatus changing during the year). Default false. When a deciding enrollment input is missing and no segment can be\r\nselected, every segment is returned regardless." }, "monthlyBaseRate": { "type": "number", "description": "Optional plan base rate per member per month. When supplied, each segment also reports the\r\nestimated monthly payment (payment score times base rate).", "format": "double", "nullable": true }, "view": { "$ref": "#/components/schemas/ScoreView" }, "includeAttribution": { "type": "boolean", "description": "Work out how much of the score is due to each submitted code (§6). Default false." } }, "additionalProperties": false }, "ScoreRequest": { "required": [ "beneficiary" ], "type": "object", "properties": { "correlationId": { "type": "string", "description": "Optional caller-supplied correlation id, echoed back unchanged. Must not be an identifier of a person.", "nullable": true }, "model": { "oneOf": [ { "enum": [ null ], "nullable": true }, { "$ref": "#/components/schemas/ModelSelector" } ] }, "beneficiary": { "$ref": "#/components/schemas/BeneficiaryInput" }, "diagnoses": { "type": "array", "items": { "$ref": "#/components/schemas/DiagnosisInput" }, "description": "Diagnoses to score. An empty list yields a demographic-only score." }, "documentationCandidates": { "type": "array", "items": { "$ref": "#/components/schemas/DiagnosisInput" }, "description": "Conditions being considered but not documented today, for the provider view only. They are scored\r\nseparately to work out what documenting them would be worth, and are never counted into the\r\nbeneficiary's own score: the answer's score is the same whichever view is asked for." }, "priorPeriodCodes": { "type": "array", "items": { "$ref": "#/components/schemas/DiagnosisInput" }, "description": "Conditions documented in the prior period, for the provider view only. CMS-HCC is prospective, so a\r\ncondition documented last year and not this one is the gap that matters. Codes only: this carries no\r\ndates, as nothing in this contract does, and the period it refers to is the caller's own." }, "contract": { "oneOf": [ { "enum": [ null ], "nullable": true }, { "$ref": "#/components/schemas/ContractInput" } ] }, "options": { "$ref": "#/components/schemas/ScoreOptions" } }, "additionalProperties": false, "description": "Score one beneficiary under one CMS model. The request carries no identifiers by design: age rather\r\nthan a birth date, an opaque reference rather than a member id, no dates of service, no free text." }, "ScoreResponse": { "required": [ "model", "beneficiary", "diagnoses", "hccs", "diagnosisCategories", "interactions", "paymentHccCount", "selection", "segments", "adjustments", "warnings" ], "type": "object", "properties": { "correlationId": { "type": "string", "nullable": true }, "model": { "$ref": "#/components/schemas/ModelInfo" }, "beneficiary": { "$ref": "#/components/schemas/BeneficiaryDerived" }, "diagnoses": { "type": "array", "items": { "$ref": "#/components/schemas/DiagnosisOutcome" }, "description": "One entry per submitted diagnosis, in submission order." }, "hccs": { "type": "array", "items": { "$ref": "#/components/schemas/HccOutcome" }, "description": "Every HCC touched by the submitted diagnoses, including the ones the hierarchy dropped." }, "diagnosisCategories": { "type": "array", "items": { "type": "string" }, "description": "Disease-group flags derived from the active HCCs (e.g. DIABETES_V28, HF_V28)." }, "interactions": { "type": "array", "items": { "type": "string" }, "description": "Interaction terms that fired (e.g. DIABETES_HF_V28)." }, "paymentHccCount": { "type": "integer", "description": "Number of active payment HCCs after hierarchies.", "format": "int32" }, "selection": { "$ref": "#/components/schemas/SegmentSelection" }, "score": { "oneOf": [ { "enum": [ null ], "nullable": true }, { "$ref": "#/components/schemas/SegmentScore" } ] }, "segments": { "type": "array", "items": { "$ref": "#/components/schemas/SegmentScore" }, "description": "The selected segment's score; every segment's when the caller set options.includeAllSegments or no segment could be selected." }, "adjustments": { "$ref": "#/components/schemas/PaymentAdjustments" }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/ScoringWarning" } }, "attribution": { "oneOf": [ { "enum": [ null ], "nullable": true }, { "$ref": "#/components/schemas/ScoreAttributionInfo" } ] }, "providerView": { "oneOf": [ { "enum": [ null ], "nullable": true }, { "$ref": "#/components/schemas/ProviderView" } ] } }, "additionalProperties": false, "description": "The full result of scoring one beneficiary. Every list has a fixed, typed shape; there are no\r\ndynamic property names and every number is a number." }, "ScoreSubtotals": { "required": [ "demographic", "hcc", "interaction", "hccCount" ], "type": "object", "properties": { "demographic": { "type": "number", "format": "double" }, "hcc": { "type": "number", "format": "double" }, "interaction": { "type": "number", "format": "double" }, "hccCount": { "type": "number", "format": "double" } }, "additionalProperties": false }, "ScoreTerm": { "required": [ "kind", "variable", "label", "coefficient" ], "type": "object", "properties": { "kind": { "$ref": "#/components/schemas/TermKind" }, "variable": { "type": "string", "description": "CMS variable name, e.g. F75_79, HCC37, DIABETES_HF_V28, D3." }, "label": { "type": "string" }, "coefficient": { "type": "number", "format": "double" } }, "additionalProperties": false }, "ScoreView": { "enum": [ "Plan", "Provider" ], "type": "string", "description": "Who the answer is being read by. The member's score is identical either way — the view adds sections and\r\nnever changes a number." }, "ScoringWarning": { "required": [ "code", "message" ], "type": "object", "properties": { "code": { "$ref": "#/components/schemas/WarningCode" }, "message": { "type": "string" }, "diagnosisCode": { "type": "string", "description": "The submitted diagnosis code the warning is about, when applicable.", "nullable": true } }, "additionalProperties": false }, "SegmentDescriptor": { "required": [ "segment", "cmsColumn", "population" ], "type": "object", "properties": { "segment": { "$ref": "#/components/schemas/RafSegment" }, "cmsColumn": { "type": "string" }, "population": { "$ref": "#/components/schemas/SegmentPopulation" } }, "additionalProperties": false }, "SegmentPopulation": { "enum": [ "ContinuingEnrollee", "NewEnrollee" ], "type": "string" }, "SegmentScore": { "required": [ "segment", "cmsColumn", "population", "rawScore", "normalizedScore", "paymentScore", "subtotals", "terms" ], "type": "object", "properties": { "segment": { "$ref": "#/components/schemas/RafSegment" }, "cmsColumn": { "type": "string", "description": "CMS's column name for the segment, e.g. COMMUNITY_NA, INSTITUTIONAL, NE_SNP." }, "population": { "$ref": "#/components/schemas/SegmentPopulation" }, "isSelected": { "type": "boolean", "description": "True when this is the segment selected for the beneficiary; null when selection was undetermined.", "nullable": true }, "isPossible": { "type": "boolean", "description": "Whether this member could be paid under this segment at all, given the enrollment facts supplied." }, "rawScore": { "type": "number", "description": "Sum of relative factors, exactly what CMS's model software emits.", "format": "double" }, "normalizedScore": { "type": "number", "description": "Raw score divided by the payment-year normalization factor, rounded to 3 decimals.", "format": "double" }, "paymentScore": { "type": "number", "description": "Normalized score after the MA coding-pattern adjustment, rounded to 3 decimals. This is the payment RAF.", "format": "double" }, "estimatedMonthlyPayment": { "type": "number", "description": "Payment score times the caller's monthly base rate, when one was supplied.", "format": "double", "nullable": true }, "subtotals": { "$ref": "#/components/schemas/ScoreSubtotals" }, "terms": { "type": "array", "items": { "$ref": "#/components/schemas/ScoreTerm" }, "description": "Every variable that contributed, with its coefficient. Empty when the caller turned terms off." } }, "additionalProperties": false }, "SegmentSelection": { "required": [ "status", "basis", "missingInputs", "assumptions" ], "type": "object", "properties": { "status": { "$ref": "#/components/schemas/SelectionStatus" }, "segment": { "oneOf": [ { "enum": [ null ], "nullable": true }, { "$ref": "#/components/schemas/RafSegment" } ] }, "basis": { "type": "array", "items": { "type": "string" }, "description": "The facts the selection rested on, in plain language." }, "missingInputs": { "type": "array", "items": { "type": "string" }, "description": "Enrollment inputs that were null and prevented a selection." }, "assumptions": { "type": "array", "items": { "type": "string" }, "description": "Defaults applied to null inputs during scoring." } }, "additionalProperties": false }, "SelectionStatus": { "enum": [ "Selected", "Undetermined" ], "type": "string" }, "SpecificityReference": { "required": [ "category", "documentedCodes", "moreSpecific", "source" ], "type": "object", "properties": { "category": { "type": "string", "description": "The condition documented, in the model's own vocabulary (`HCC18`, `HHS_HCC021`)." }, "categoryLabel": { "type": "string", "description": "CMS's own description of it, where the model publishes one.", "nullable": true }, "documentedCodes": { "type": "array", "items": { "type": "string" }, "description": "The submitted codes that reached it, normalized." }, "moreSpecific": { "type": "array", "items": { "$ref": "#/components/schemas/MoreSpecificCondition" }, "description": "The conditions the model ranks above it, in CMS's hierarchy-table order, which lists the most severe\r\nfirst. Never empty: a condition with nothing above it produces no entry at all rather than an entry with\r\nan empty list." }, "source": { "$ref": "#/components/schemas/PromptSource" } }, "additionalProperties": false, "description": "One condition this period documents, and the conditions the model ranks above it." }, "StateAveragesInput": { "required": [ "planLiabilityRiskScore", "actuarialValue", "allowableRatingFactor", "inducedDemandFactor", "geographicCostFactor", "sensitivityFraction" ], "type": "object", "properties": { "planLiabilityRiskScore": { "type": "number", "description": "The pool's average plan liability risk score.", "format": "double" }, "actuarialValue": { "type": "number", "description": "The pool's average actuarial value, as a fraction.", "format": "double" }, "allowableRatingFactor": { "type": "number", "description": "The pool's average allowable rating factor.", "format": "double" }, "inducedDemandFactor": { "type": "number", "description": "The pool's average induced-demand factor.", "format": "double" }, "geographicCostFactor": { "type": "number", "description": "The pool's average geographic cost factor.", "format": "double" }, "sensitivityFraction": { "type": "number", "description": "How far to move the average risk score for the reported range, as a fraction: 0.05 is five per cent\r\neither way.", "format": "double" } }, "additionalProperties": false, "description": "CMS's published state averages for one market risk pool, and how far to move them." }, "StatedDenominatorsInput": { "required": [ "risk", "premium" ], "type": "object", "properties": { "risk": { "type": "number", "description": "Sum over the pool of share × PLRS × IDF × GCF.", "format": "double" }, "premium": { "type": "number", "description": "Sum over the pool of share × AV × ARF × IDF × GCF.", "format": "double" } }, "additionalProperties": false, "description": "The two sums a transfer divides by, supplied outright." }, "StateTransferResult": { "required": [ "net", "isApproximation" ], "type": "object", "properties": { "plans": { "type": "array", "items": { "$ref": "#/components/schemas/PlanTransferResult" }, "description": "Each plan's transfer, in the order the plans were given." }, "net": { "type": "number", "description": "What the totals come to together, which means two different things depending on the source.", "format": "double" }, "maxResidual": { "type": "number", "description": "The largest decimal StateTransferResult.Net that rounding alone can account for, when the source is a complete pool.", "format": "double", "nullable": true }, "isApproximation": { "type": "boolean", "description": "True when either denominator stands in for something CMS has not published." } }, "additionalProperties": false, "description": "The state transfer: every plan's figure, and what they come to together." }, "TableCounts": { "required": [ "mappingRows", "distinctDiagnosisCodes", "paymentHccs", "hierarchyRules", "diagnosisCategories", "interactions" ], "type": "object", "properties": { "mappingRows": { "type": "integer", "format": "int32" }, "distinctDiagnosisCodes": { "type": "integer", "format": "int32" }, "paymentHccs": { "type": "integer", "format": "int32" }, "hierarchyRules": { "type": "integer", "format": "int32" }, "diagnosisCategories": { "type": "integer", "format": "int32" }, "interactions": { "type": "integer", "format": "int32" } }, "additionalProperties": false }, "TermKind": { "enum": [ "Demographic", "Hcc", "Interaction", "HccCount", "NewEnrolleeCell" ], "type": "string" }, "TransferEnrolleeInput": { "required": [ "csrAdjustedScore", "enrolledMonths", "billableMonths" ], "type": "object", "properties": { "csrAdjustedScore": { "type": "number", "description": "The enrollee's cost-sharing-adjusted risk score, from a Phase 1 ACA score.", "format": "double" }, "enrolledMonths": { "type": "number", "description": "Months the enrollee was enrolled, which is what their risk is weighted by.", "format": "double" }, "billableMonths": { "type": "number", "description": "Months the plan may bill for, which is what the weighted risk is divided by.", "format": "double" } }, "additionalProperties": false, "description": "One enrollee's contribution to a plan's liability risk score." }, "TransferEstimateRequest": { "required": [ "market" ], "type": "object", "properties": { "market": { "$ref": "#/components/schemas/TransferMarketInput" }, "plans": { "type": "array", "items": { "$ref": "#/components/schemas/TransferPlanInput" }, "description": "The plans to report on — every plan in the pool when the source says so, otherwise the caller's own." }, "highCostRiskPool": { "oneOf": [ { "enum": [ null ], "nullable": true }, { "$ref": "#/components/schemas/HighCostRiskPoolInput" } ] }, "inputsArePublished": { "type": "boolean", "description": "Whether every input CMS publishes after the benefit year is the published figure rather than an estimate." }, "correlationId": { "type": "string", "description": "An opaque token echoed back, for matching an answer to a request in your own logs.", "nullable": true } }, "additionalProperties": false, "description": "A request for an ACA risk adjustment transfer estimate." }, "TransferEstimateResponse": { "required": [ "stateTransfer", "isProjection" ], "type": "object", "properties": { "stateTransfer": { "$ref": "#/components/schemas/StateTransferResult" }, "highCostRiskPool": { "oneOf": [ { "enum": [ null ], "nullable": true }, { "$ref": "#/components/schemas/HighCostRiskPoolResult" } ] }, "excluded": { "type": "array", "items": { "$ref": "#/components/schemas/ExcludedFromTransferResult" }, "description": "What a CMS settlement includes that this estimate does not." }, "estimateBasis": { "type": "array", "items": { "type": "string" }, "description": "Every assumption the answer rests on, for the caller to publish alongside it." }, "isProjection": { "type": "boolean", "description": "True when any figure here rests on an input CMS has not published, or has not been said to have." }, "correlationId": { "type": "string", "description": "The token from the request, echoed back.", "nullable": true } }, "additionalProperties": false, "description": "An ACA risk adjustment transfer estimate." }, "TransferExclusion": { "enum": [ "RiskAdjustmentDataValidation", "DefaultCharge", "UserFees" ], "type": "string", "description": "Something CMS settles alongside a transfer that this estimate deliberately leaves out." }, "TransferMarketInput": { "required": [ "stateAveragePremium", "denominators" ], "type": "object", "properties": { "stateAveragePremium": { "type": "number", "description": "The statewide average premium, already reduced for administrative costs that do not vary with claims\r\n(14% since 2018).", "format": "double" }, "denominators": { "$ref": "#/components/schemas/DenominatorsInput" } }, "additionalProperties": false, "description": "The pool the plans sit in." }, "TransferPlanInput": { "required": [ "planId", "actuarialValue", "allowableRatingFactor", "inducedDemandFactor", "geographicCostFactor", "billableMemberMonths" ], "type": "object", "properties": { "planId": { "type": "string", "description": "The caller's own reference for the plan. Not read by the formula, only echoed back." }, "planLiabilityRiskScore": { "type": "number", "description": "PLRS: the plan's enrollment-weighted cost-sharing-adjusted risk score, if you have already computed it.", "format": "double", "nullable": true }, "enrollees": { "type": "array", "items": { "$ref": "#/components/schemas/TransferEnrolleeInput" }, "description": "The enrollees to compute the plan's liability risk score from." }, "actuarialValue": { "type": "number", "description": "AV: the metal level's actuarial value, as a fraction. Eighty per cent is 0.80, not 80.", "format": "double" }, "allowableRatingFactor": { "type": "number", "description": "ARF: the plan's allowable rating factor.", "format": "double" }, "inducedDemandFactor": { "type": "number", "description": "IDF: the metal level's induced-demand factor, from the benefit year's published table.", "format": "double" }, "geographicCostFactor": { "type": "number", "description": "GCF: the rating area's geographic cost factor, from CMS's appendix B.", "format": "double" }, "billableMemberMonths": { "type": "number", "description": "The months the plan may bill for, which is also its share weight in the pool.", "format": "double" } }, "additionalProperties": false, "description": "One plan in a state market risk pool, with everything the formula needs from it." }, "TransferRangeResult": { "required": [ "low", "high" ], "type": "object", "properties": { "low": { "type": "number", "description": "The lowest total across the band.", "format": "double" }, "high": { "type": "number", "description": "The highest total across the band.", "format": "double" } }, "additionalProperties": false, "description": "The lowest and highest total a plan lands on across the sensitivity that was asked for." }, "WarningCode": { "enum": [ "DiagnosisNotInModel", "DiagnosisExcludedByEdits", "DuplicateDiagnosis", "EnrollmentInputAssumed", "SegmentUndetermined", "AttributionLimited", "AttributionUnavailable", "ScoreIsOneBlendComponent", "IndexUnavailableForSinglePopulation" ], "type": "string" } }, "securitySchemes": { "ApiKey": { "type": "apiKey", "description": "Caller API key, sent in the X-Api-Key header", "name": "X-Api-Key", "in": "header" } } }, "security": [ { } ], "tags": [ { "name": "Scoring" }, { "name": "Models" }, { "name": "Scoring (ACA)" }, { "name": "Transfers (ACA)" }, { "name": "Medicaid" } ] }