Skip to main content

Rate Schedule API Endpoints

These endpoints manage Rate Schedule configuration within the Contract Builder. All endpoints require authentication and operate on a specific Contract Builder instance.

SSP Catalog​

GET /api/v1/ssp/catalog/​

Returns all active ENCOUNTER-level SSPs available for rate schedule configuration. Supports pagination and search.

Query Parameters:

ParameterTypeDescription
searchstringFilter by SSP name or code
pageintegerPage number (default: 1)
page_sizeintegerResults per page (default: 20, max: 200)

Response:

{
  "count": 10,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "a1b2c3d4-...",
      "code": "GI001",
      "name": "Colonoscopy",
      "level": "ENCOUNTER",
      "medicare_rate": 1500.00,
      "base_weight": 1.0,
      "primary_cpt_code": "45378",
      "requires_anesthesia": true
    }
  ]
}

Initialize Rate Schedule​

POST /api/v1/computable-contracts/builder/{instance_id}/rate-schedule/init/​

Creates a new Rate Schedule for the Contract Builder instance, or returns the existing one if already initialized.

Request Body:

{
  "ssp_reference_type": "INDIVIDUAL",
  "scope_of_care": "FACILITY_AND_PROFESSIONAL",
  "service_logic": "ELECTIVE_ONLY",
  "elective_advance_hours": 72,
  "non_elective_fallback": "PERCENT_MEDICARE",
  "non_elective_fallback_percent": 1.25,
  "default_rate_type": "PERCENT_MEDICARE",
  "default_rate_value": 1.45
}

Response (200):

{
  "rate_schedule_id": "e5f6g7h8-...",
  "message": "Rate schedule initialized"
}

Get Rate Schedule Detail​

GET /api/v1/computable-contracts/builder/{instance_id}/rate-schedule/​

Returns the full Rate Schedule configuration and all SSP rate items for the instance.

Response:

{
  "rate_schedule": {
    "id": "e5f6g7h8-...",
    "ssp_reference_type": "INDIVIDUAL",
    "scope_of_care": "FACILITY_AND_PROFESSIONAL",
    "service_logic": "ELECTIVE_ONLY",
    "elective_advance_hours": 72,
    "non_elective_fallback": "PERCENT_MEDICARE",
    "non_elective_fallback_percent": 1.25,
    "default_rate_type": "PERCENT_MEDICARE",
    "default_rate_value": 1.45,
    "items": [
      {
        "id": "i9j0k1l2-...",
        "ssp_id": "a1b2c3d4-...",
        "ssp_code": "GI001",
        "ssp_name": "Colonoscopy",
        "rate_type": "CASE_RATE",
        "rate_value": 2650.00,
        "is_bundle_eligible": true,
        "bundle_type": "CONVENED",
        "notes": "",
        "sort_order": 0
      }
    ]
  }
}

Update Rate Schedule Configuration​

PATCH /api/v1/computable-contracts/builder/{instance_id}/rate-schedule/config/​

Updates schedule-level configuration (does not modify individual SSP items).

Request Body (all fields optional):

{
  "scope_of_care": "FACILITY_ONLY",
  "elective_advance_hours": 48,
  "non_elective_fallback": "WRAP_NETWORK"
}

Response (200):

{
  "message": "Rate schedule configuration updated"
}

Add or Update SSP in Rate Schedule​

PUT /api/v1/computable-contracts/builder/{instance_id}/rate-schedule/add-ssp/​

Adds a new SSP to the rate schedule, or updates its configuration if already present (upsert by SSP ID).

Request Body:

{
  "ssp_id": "a1b2c3d4-...",
  "rate_type": "CASE_RATE",
  "rate_value": 2650.00,
  "is_bundle_eligible": true,
  "bundle_type": "CONVENED",
  "notes": "Includes facility, surgeon, anesthesia, pathology"
}

Response (200):

{
  "rate_schedule_item_id": "i9j0k1l2-...",
  "ssp_id": "a1b2c3d4-...",
  "message": "SSP added/updated in rate schedule"
}

Error (400):

{
  "error": "Invalid SSP ID format: demo-1. Must be a valid UUID."
}

Remove SSP from Rate Schedule​

DELETE /api/v1/computable-contracts/builder/{instance_id}/rate-schedule/remove-ssp/​

Removes an SSP from the rate schedule.

Request Body:

{
  "ssp_id": "a1b2c3d4-..."
}

Response (200):

{
  "message": "SSP removed from rate schedule"
}

Load SSP Catalog Version​

POST /api/v1/computable-contracts/builder/{instance_id}/rate-schedule/load-catalog/​

Populates the rate schedule with all active ENCOUNTER-level SSPs from a specific catalog version. Uses the schedule's default rate type and value for each SSP.

Request Body:

{
  "version": "v1.0"
}

Response (200):

{
  "message": "Loaded N SSPs from catalog version v1.0",
  "count": 10
}

Preview Pricing​

GET /api/v1/computable-contracts/builder/{instance_id}/rate-schedule/preview/​

Returns calculated allowed amounts for all SSPs in the rate schedule without persisting anything. Useful for reviewing pricing before finalization.

Response:

{
  "items": [
    {
      "ssp_code": "GI001",
      "ssp_name": "Colonoscopy",
      "rate_type": "CASE_RATE",
      "rate_value": 2650.00,
      "calculated_allowed_amount": 2650.00,
      "medicare_rate": 1500.00,
      "bundle_type": "CONVENED"
    },
    {
      "ssp_code": "ORTHO001",
      "ssp_name": "Total Knee Replacement",
      "rate_type": "PERCENT_MEDICARE",
      "rate_value": 1.45,
      "calculated_allowed_amount": 17400.00,
      "medicare_rate": 12000.00,
      "bundle_type": "PROVIDER_ONLY"
    }
  ]
}

Finalization​

When the Contract Builder is finalized (via the existing POST /api/v1/computable-contracts/builder/{instance_id}/finalize endpoint), the Rate Schedule is automatically converted into ContractRate records on the Direct Contract. Schedule-level elective and fallback settings are copied to the DirectContract model. This is handled by the RateConfigurationService.finalize_rates_to_contract() method.

Next Steps​