Custom Providers API¶

Manage custom provider data overrides and specific configurations.

Overview¶

The Custom Providers API allows you to create, update, and manage custom provider records. These records can override or supplement the standard CMS provider data (IPSF/OPSF).

Base Path: /api/v1/custom-providers

Authentication: Required for all endpoints (Bearer token)

Endpoints¶

List Custom Providers¶

Retrieve a list of custom providers with optional filtering.

Endpoint: GET /custom-providers/

Query Parameters:

Response:

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "provider_id": "123456",
      "contract_id": "contract-001",
      "effective_date": "2024-01-01",
      "label": "Custom Hospital A",
      "version": 1,
      "is_active": true
    }
  ],
  "count": 1
}

Get Custom Provider¶

Retrieve a specific custom provider record by its unique ID.

Endpoint: GET /custom-providers/{custom_provider_id}

Path Parameters:

Response:

Returns the full resolved custom provider object.

Resolve Active Provider¶

Resolve the active custom provider configuration for a specific date.

Endpoint: GET /custom-providers/active/resolve

Query Parameters:

Response:

Returns the resolved custom provider object active on the specified date.

Create Custom Provider¶

Create a new custom provider record.

Endpoint: POST /custom-providers/

Request Body:

{
  "provider_id": "123456",
  "contract_id": "contract-001",
  "effective_date": "2024-01-01",
  "termination_date": "2024-12-31",
  "label": "Custom Hospital A",
  "notes": "Initial configuration",
  "data": {
    "base_rate": 1000.00
  }
}

Response:

Returns the created custom provider object.

Update Custom Provider¶

Update an existing custom provider. This creates a new version of the provider record.

Endpoint: PATCH /custom-providers/{custom_provider_id}

Path Parameters:

Request Body:

Fields to update (e.g., label, notes, data). Note that effective_date and termination_date are immutable for existing versions.

Response:

Returns the updated (new version) custom provider object.

Activate Version¶

Activate a specific version of a custom provider, making it the current active version.

Endpoint: POST /custom-providers/{custom_provider_id}/activate

Path Parameters:

Response:

Returns the activated custom provider object.

Get Version History¶

Retrieve the version history for a custom provider.

Endpoint: GET /custom-providers/{custom_provider_id}/versions

Path Parameters:

Response:

List of version history objects.

Delete Custom Provider¶

Delete a custom provider record.

Endpoint: DELETE /custom-providers/{custom_provider_id}

Path Parameters:

Response:

204 No Content on success.

Preview Custom Provider¶

Preview what a custom provider record would look like without saving it.

Endpoint: POST /custom-providers/preview

Request Body:

Same as Create Custom Provider.

Response:

Returns the previewed custom provider object.

Audit Logs¶

Get Audit Log Diff¶

Get a formatted diff for a specific audit log entry, showing what changed.

Endpoint: GET /audit-log/{log_id}/diff

Path Parameters:

Response:

Returns a list of field changes.

[
  {
    "field": "data.base_rate",
    "old_value": "1000.0",
    "new_value": "1200.0"
  }
]

Get Provider History¶

Retrieve the full change history for a specific custom provider record.

Endpoint: GET /custom-provider-history

Query Parameters:

Response:

Returns a list of audit log entries, ordered by change date (newest first).

[
  {
    "id": "log_123",
    "provider_id": "123456",
    "contract_id": "contract-001",
    "changed_at": "2024-03-15T10:30:00Z",
    "action": "update",
    "changed_by_email": "[email protected]"
  }
]