API Documentation

The Risk Score Calculator Medicare API provides comprehensive Medicare Part C risk score calculations with the following capabilities:

• Asynchronous Processing: Handle large datasets with up to 10,000 members per request
• Intelligent Chunking: Automatic data partitioning while maintaining member-diagnosis integrity
• Enterprise Integration: Direct SQL Server stored procedure execution
• Usage Metering: Comprehensive tracking for billing and auditing
• Subscription Management: Real-time validation against subscription database

All API requests require authentication via request headers. The API validates subscription status in real-time.

Required Headers:

Header	Required	Description
subscriptionKey	Required	Your API subscription key
productKey	Required	Product GUID (matches "RA RiskScore Medicare" product)
productName	Optional	Product name for logging
userFirstName	Optional	User first name for audit logging
userLastName	Optional	User last name for audit logging
subscriptionStartDate	Optional	Subscription start timestamp in ISO format
subscriptionEndDate	Optional	Subscription end timestamp in ISO format

Method	Endpoint	Description
POST	/api/risk-assessment	Submit risk assessment request
GET	/api/orchestrators/{instanceId}	Check job status and retrieve results
GET	/health	Health check endpoint

Submit a risk assessment request for Medicare members and their diagnoses.

Request Body Schema:

{
  "payment_year": "2025",
    "memberships": [
    {
      "MemberID": "123",
      "DOB": "1980-05-10",
      "Gender": "M",
      "RAType": "TypeA",
      "Hospice": "N",
      "LTIMCAID": "Y",
      "NEMCAID": "N",
      "OREC": "1"
    }
  ],
    "diagnoses": [
    {
      "MemberID": "123",
      "FromDOS": "2024-01-01",
      "ThruDOS": "2024-01-10",
      "DxCode": "I10"
    }
  ]
}

Response (202 Accepted):

{
  "instanceId": "uuid-string",
    "statusQueryGetUri": "https:\\riskscore-medicare.healthtrixss.com/api/orchestrators/uuid-string?showInput=false"
}

Check the status of a risk assessment job and retrieve results when complete.

Query Parameters:

Parameter	Required	Description
showInput	Optional	Set to "false" for privacy (recommended)

Response - Running:

{
  "instanceId": "uuid-string",
  "runtimeStatus": "Running",
    "createdTime": "2026-05-26T10:00:00.000000",
    "lastUpdatedTime": "2026-05-26T10:01:00.000000"
}

Response - Completed:

{
  "instanceId": "uuid-string",
  "runtimeStatus": "Completed",
  "output": [
    {
      "Member_Id": "123",
      "Payment_Year": 2025,
      "BirthDate_Org": "1980-05-10",
      "Status": "Success",
      "Message": "Risk score calculated successfully",
            "RAF_Total": 1.25,
            "Model": "V28"
    }
  ],
    "createdTime": "2026-05-26T10:00:00.000000",
    "lastUpdatedTime": "2026-05-26T10:02:00.000000"
}

Member Schema:

Field	Type	Required	Description
MemberID	String	Yes	Unique member identifier
DOB	Date	Yes	Date of birth (YYYY-MM-DD)
Gender	String	Yes	M/F or Male/Female
RAType	String	Yes	Risk adjustment type
Hospice	String	Yes	Y/N or Yes/No
LTIMCAID	String	Yes	Long-term institutional Medicaid
NEMCAID	String	Yes	Non-institutional Medicaid
OREC	String	Yes	Original reason for entitlement code

Diagnosis Schema:

Field	Type	Required	Description
MemberID	String	Yes	Must match a member ID in memberships
FromDOS	Date	Yes	Service start date (YYYY-MM-DD)
ThruDOS	Date	Yes	Service end date (YYYY-MM-DD)
DxCode	String	Yes	ICD diagnosis code

cURL Example:

curl -X POST "https:\\riskscore-medicare.healthtrixss.com/api/risk-assessment" \
  -H "Content-Type: application/json" \
  -H "subscriptionKey: your-subscription-key" \
  -H "productKey: your-product-key" \
  -d '{
    "payment_year": "2025",
    "memberships": [
      {
        "MemberID": "123",
        "DOB": "1980-05-10",
        "Gender": "M",
        "RAType": "TypeA",
        "Hospice": "N",
        "LTIMCAID": "Y",
        "NEMCAID": "N",
        "OREC": "1"
      }
    ],
    "diagnoses": [
      {
        "MemberID": "123",
        "FromDOS": "2024-01-01",
        "ThruDOS": "2024-01-10",
        "DxCode": "I10"
      }
    ]
  }'

Python Example:

import requests
import time

# Submit request
response = requests.post(
    "https:\\riskscore-medicare.healthtrixss.com/api/risk-assessment",
    headers={
        "Content-Type": "application/json",
        "subscriptionKey": "your-subscription-key",
        "productKey": "your-product-key"
    },
    json={
        "payment_year": "2025",
        "memberships": [
            {
                "MemberID": "123",
                "DOB": "1980-05-10",
                "Gender": "M",
                "RAType": "TypeA",
                "Hospice": "N",
                "LTIMCAID": "Y",
                "NEMCAID": "N",
                "OREC": "1"
            }
        ],
        "diagnoses": [
            {
                "MemberID": "123",
                "FromDOS": "2024-01-01",
                "ThruDOS": "2024-01-10",
                "DxCode": "I10"
            }
        ]
    }
)

if response.status_code == 202:
    status_url = response.json()["statusQueryGetUri"]
    
    # Poll for results
    while True:
        status_response = requests.get(status_url)
        status_data = status_response.json()
        
        if status_data["runtimeStatus"] == "Completed":
            results = status_data["output"]
            print("Results:", results)
            break
        elif status_data["runtimeStatus"] == "Failed":
            print("Job failed:", status_data.get("error", status_data.get("customStatus", "Unknown error")))
            break
        else:
            time.sleep(5)  # Wait 5 seconds before polling again

HTTP Status Codes:

Code	Status	Description
200	OK	Status check successful
202	Accepted	Request accepted for processing
400	Bad Request	Invalid request data or headers
401	Unauthorized	Invalid or inactive subscription
404	Not Found	Endpoint or instance not found
500	Internal Server Error	Server processing error
503	Service Unavailable	Service health check failed

Error Response Format:

{
  "error": "Error type",
  "message": "Detailed error description",
  "details": {
    "field": ["Specific validation errors"]
  }
}