# Orita Ranking Policies

Tested with: Orita API v2
Last verified: 2026-07-31

Ranking policies control how Orita scores and orders eligible provider-time options.
Hard constraints always run first. Preferences affect score only — never exclude providers.

## Create a policy

POST /api/v2/ranking-policies

```json
{
  "name": "Behavioral health default",
  "weights": {
    "preferredLanguage":  20,
    "preferredDayPart":   15,
    "earliestAvailable":  30,
    "providerContinuity": 20,
    "workloadBalance":    10,
    "preferredLocation":   5
  },
  "tieBreakers": ["earliest_start", "provider_id"]
}
```

New policies start in draft status.

## Simulate before activating

POST /api/v2/ranking-policies/:id/simulate

```json
{
  "candidates": [
    { "providerId": "pro_1", "displayName": "Dr. A", "languageCodes": ["es"], "slotStart": "2026-08-05T15:00:00Z" },
    { "providerId": "pro_2", "displayName": "Dr. B", "languageCodes": ["en"], "slotStart": "2026-08-05T09:00:00Z" }
  ],
  "preferences": { "languageCodes": ["es"], "dayParts": ["afternoon"] }
}
```

See how the policy would rank candidates before committing.

## Activate

POST /api/v2/ranking-policies/:id/activate

Creates an immutable version snapshot. Every resolution records the policy ID and version used.
Existing resolutions are not affected when a new policy activates.

## Rollback

Activate a previous version by calling activate on the policy after updating weights back.
Version history is stored in ranking_policy_versions.

## Rules

- Hard constraints (license, insurance, service, etc.) are never configurable as weights
- Tie-breaking is deterministic: earliest_start → lowest_workload → provider_id
- Every resolution records: policyId, policyVersion, providerGraphVersion
- Simulating before activating is strongly recommended

## Continuity bonus

Orita automatically boosts providers with an existing patient relationship.
Record relationships: POST /api/v2/continuity

## Machine-readable

- Capabilities: /capabilities.json
- OpenAPI: /openapi.json
- Full reference: /developers/reference