> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getprescience.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Price on a plan

> Give Prescience one plan and a census, and get the joint plan and the Prescience layer price.

Use `POST /price-on-plan` when you have one plan priced and want to know what
Prescience adds on top of it. You send a census and the plan with its
price per covered person per month. The response is the two plans,
Prescience Diamond and Prescience Value, each as the joint plan (your plan plus Prescience) and as
the Prescience layer alone. The MCP tool `price_on_plan` takes the same input.

Unlike [`POST /quotes`](/guides/brokers), you don't send a company or every plan
you quoted. A key needs the `price_on_plan` capability, which broker keys have
by default; see [Broker account setup](/guides/partner-setup).

## Send a census and one plan

```bash theme={null}
curl -X POST https://www.getprescience.com/api/partner/v1/price-on-plan \
  -H "Authorization: Bearer $PRESCIENCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "census": [
      {
        "firstName": "Ada",
        "lastName": "Reyes",
        "dob": "1991-04-02",
        "zip": "94110"
      }
    ],
    "plan": {
      "carrier": "Example Carrier",
      "planName": "Catastrophic HDHP",
      "planType": "PPO",
      "hsaEligible": true,
      "deductibleIndividualCents": 700000,
      "oopMaxIndividualCents": 900000,
      "pmpmCents": 42000
    }
  }'
```

### The plan

Money is integer cents.

| Field | |
| - | - |
| `planType` | Required. `PPO`, `EPO` or `POS`. |
| `hsaEligible` | Required, and must be `true`. |
| `deductibleIndividualCents` | Required. |
| `oopMaxIndividualCents` | Required, above 0. |
| `pmpmCents` | The plan's monthly price per covered person. A household costs this times the people on it. |
| `memberRatesCents` | The exact monthly rate for each employee's household, as `{ "externalId", "monthlyCents" }` by census `externalId`. Preferred when you have it; it wins over the others. |
| `monthlyRatesCents` | The monthly premium for one household of each shape (`employeeOnly`, `employeeSpouse`, `employeeChildren`, `family`), used when you send neither of the above. |
| `deductibleFamilyCents`, `oopMaxFamilyCents` | Optional. Twice the individual amount when omitted. |
| `carrier`, `planName`, `network` | Optional. Without a carrier or name the plan is shown as "Your carrier" and "Your plan". |

Send one of `pmpmCents`, `memberRatesCents` or `monthlyRatesCents`.

### The rest of the request

| Field | |
| - | - |
| `census` | Required. Members as in [`PUT /groups/{groupId}/census`](/guides/census). Each needs `zip` and one of `dob` or `age`. |
| `company` | Optional: `name`, `domain`, `externalId`, `zip`, `state`. Without it the census is stored under a generated company. `zip` defaults to the first census ZIP. |
| `marketPlans` | Optional: every plan you quoted, in the [`POST /quotes`](/guides/brokers#send-your-own-plans) shape. See below. |

Prescience stores the census as a group in your account. Sending the same company (or, with no company, the same census) again prices
the same group again. A price-on-plan group is separate from the
groups your `POST /quotes` calls create.

## The response

`201` returns both versions. A plan Prescience can't build on (an HMO, a plan
that isn't HSA-eligible, or one with a missing or unusable field) is not a
`400`: the response is `200` with `status: "unavailable"`, a `reason`,
`ignoredPlans` and `assumptions`. A `400` is only for broken JSON, a missing or
invalid census, or a missing plan. When pricing takes longer than the request waits,
the response is `202` with `retryAfterSeconds` (the same body as a quote's
`202`): send the same body again.

```json theme={null}
{
  "groupId": "grp_8c2f41d09a3e",
  "quoteId": "qt_5b9e2c7f10ad",
  "pricingMethod": "cost_plus",
  "versions": [ ... ],
  "time_machine": { "simulated_plan_years": 1000, "census_members": 1, "generated_at": "2026-10-02T17:21:40.000Z" },
  "assumptions": [ "No company was sent, so the census is kept under a generated company." ]
}
```

Each item in `versions` is a plan in the shape of a
quote's `plans` (see [Reading a quote](/guides/brokers#reading-a-quote), including
`all_max_year`, `median_year` and `monthly_rates_by_household`), with two objects
added:

| Field | Meaning |
| - | - |
| `joint` | Your plan plus the Prescience layer. `basePmpmCents + prescienceLayerPmpmCents = totalPmpmCents`, with `monthlyCents`, `annualCents` (exactly 12 times monthly), `deductibleIndividualCents`, `memberOopMaxIndividualCents`, `memberOopMaxFamilyCents`, `modeledWorstYearCents` and a one-line `summary`. |
| `prescienceOnly` | What Prescience alone costs: `pmpmCents`, `monthlyCents` and `annualCents`. Your plan's own premium is paid to its carrier. |

`ignoredPlans` and `usedPlans` appear when you sent `marketPlans`, as in a
[quote](/guides/brokers). `assumptions` lists everything defaulted or assumed, in words: a missing
company or ZIP, a family deductible or out-of-pocket maximum set to twice the
individual one, and how the price was set.

A version that can't be priced has `status: "unavailable"` and a `reason`, as
in a quote.

## Pricing method

`pricingMethod` is informational: `engine` when you send `marketPlans` that include a
platinum PPO, and `cost_plus` when you send only the census and one plan (each
version then has `pricing_method: "cost_plus"`, no `comparison`, and
`worst_year.benchmark_premium_cents` and `headroom_cents` of `null`).
`joint.deductibleIndividualCents` is the plan's own deductible. The worst year is a
modeled scenario from Time Machine for this census, not a contractual cap or
guarantee.

Without `marketPlans` no marketplace is queried, so the answer usually comes
back in the same request.

## Errors

| Status | Meaning |
| - | - |
| `400 invalid_request` | Broken JSON, a missing or invalid census, or a missing plan; `details` names each field. |
| `403 forbidden` | The key can't call this endpoint. |
| `422` | Prescience couldn't price this plan. |
| `429 rate_limited` | Price-on-plan shares the 60-an-hour quote limit with `POST /quotes`. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.