Contract Hub API¶

Manage contracts and their temporal configuration entries, which link to customizations like fee schedules and DRG tables.

Overview¶

The Contract Hub API provides a centralized way to manage payer contracts. A Contract is a high-level container (e.g., "Aetna Commercial") that contains multiple Temporal Configurations. Each configuration is valid for a specific date range and defines which specific pricing rules (Fee Schedules, Custom DRG Tables, etc.) apply during that period.

Base Path: /api/v1/contracts

Authentication: Required for all endpoints (Bearer token)

Contract Management¶

Create Contract¶

Create a new contract container.

Endpoint: POST /contracts

Request Body:

{
  "contract_id": "COMMERCIAL-A",
  "name": "Commercial Plan A",
  "description": "Standard commercial contract",
  "payer_id": "PAYER-001"
}

Response:

{
  "contract_id": "COMMERCIAL-A",
  "name": "Commercial Plan A",
  "description": "Standard commercial contract",
  "payer_id": "PAYER-001",
  "is_active": true,
  "created_at": "2024-01-01T12:00:00Z",
  "updated_at": "2024-01-01T12:00:00Z"
}

List Contracts¶

List all contracts for the organization.

Endpoint: GET /contracts

Query Parameters:

Response:

{
  "data": [
    {
      "contract_id": "COMMERCIAL-A",
      "name": "Commercial Plan A",
      "is_active": true,
      "config_count": 2
    }
  ],
  "count": 1
}

Get Contract Detail¶

Get detailed information about a contract, including its provider count and other metadata.

Endpoint: GET /contracts/{contract_id}

Path Parameters:

Response:

{
  "contract_id": "COMMERCIAL-A",
  "name": "Commercial Plan A",
  "description": "Standard commercial contract",
  "is_active": true,
  "provider_count": 15,
  "configs": []
}

Update Contract¶

Update contract metadata (name, description, status).

Endpoint: PUT /contracts/{contract_id}

Path Parameters:

Request Body:

{
  "name": "Commercial Plan A - Updated",
  "description": "Updated description",
  "is_active": false
}

Response:

Returns updated contract object.

Delete Contract¶

Delete or deactivate a contract.

Endpoint: DELETE /contracts/{contract_id}

Path Parameters:

Query Parameters:

Response:

Returns deleted/deactivated contract object.

Contract Configurations¶

Manage temporal configuration entries that define pricing logic for specific time periods.

Create Config Entry¶

Create a new time-bound configuration entry for a contract.

Endpoint: POST /contracts/{contract_id}/configs

Request Body:

{
  "effective_date": "2024-01-01",
  "termination_date": "2024-12-31",
  "custom_fee_schedule_id": "uuid-string",
  "custom_drg_table_id": "my-custom-drg-2024",
  "ioce_config_id": "uuid-string",
  "notes": "2024 Rates"
}

Response:

{
  "id": "config-uuid",
  "contract_id": "COMMERCIAL-A",
  "effective_date": "2024-01-01",
  "termination_date": "2024-12-31",
  "custom_fee_schedule_id": "uuid-string",
  "custom_drg_table_id": "my-custom-drg-2024"
}

[!IMPORTANT] The date range must not overlap with any other active configuration entry for the same contract.

List Config Entries¶

List all configuration entries for a contract.

Endpoint: GET /contracts/{contract_id}/configs

Response:

Returns list of configuration objects.

Update Config Entry¶

Update a specific configuration entry. Updating dates will trigger collision detection with other entries.

Endpoint: PUT /contracts/{contract_id}/configs/{config_id}

Path Parameters:

Request Body:

Same as Create Config Entry. Omit fields you don't want to change.

Delete Config Entry¶

Delete a configuration entry.

Endpoint: DELETE /contracts/{contract_id}/configs/{config_id}

Response:

204 No Content

Audit¶

Get Audit History¶

Get the audit log for a specific contract.

Endpoint: GET /contracts/{contract_id}/audit

Query Parameters:

Response:

{
  "data": [
    {
      "id": "audit-uuid",
      "entity_type": "contract",
      "action": "update",
      "field_name": "name",
      "old_value": "Old Name",
      "new_value": "New Name",
      "changed_by": "user-uuid",
      "changed_at": "2024-01-02T10:00:00Z"
    }
  ],
  "count": 1
}

Claims Processing Integration¶

The Contract Hub is deeply integrated into the claims processing engine (Myelin). When a claim is processed, the system dynamically resolves pricing rules based on the provider's assigned contract.

Workflow¶

1. Provider Lookup: The system identifies the billing provider associated with the claim.
2. Contract Resolution:
   • If the provider has a specific contract_id associated with the claim's organization, the system looks up the corresponding Contract.
   • If contract_id is "0" or null, standard CMS Medicare logic is applied.
3. Temporal Configuration:
   • The system queries for a Contract Config entry that is effective on the claim's date (from_date for Outpatient/OPSF, thru_date for Inpatient/IPSF).
   • If a matching configuration is found, its settings are injected into the pricing context.

Impact on Pricing¶

The resolved Contract Config directly modifies how the claim is priced by injecting specific overrides:

• Custom Fee Schedules: If custom_fee_schedule_id is present, the pricer uses this schedule for HCPCS/CPT line-item pricing, overriding standard CMS fee schedules.
• Custom DRG Tables: If custom_drg_table_id is present, the pricer uses these custom weights and lengths of stay for DRG assignment and reimbursement calculations.
• IOCE Bypass: If ioce_config_id is present, specific edits in the Integrated Outpatient Code Editor (IOCE) can be bypassed or modified.

Provider Data & Fallbacks¶

The contract also determines the source of provider-specific data (like CCRs, wage indexes, etc.):

• Custom Provider Data: The system first attempts to load a CustomProvider record specific to the contract. This allows for contract-specific overrides of provider data.
• Medicare Base Fallback:
  • If use_medicare_base is true (set at the Contract level) and no custom provider data is found, the system automatically falls back to standard CMS provider data.
  • If use_medicare_base is false, the processing will fail if no custom provider record exists, ensuring strictly controlled environments.