Broker quickstart

Brokers send a client’s census to POST /quotes and get a quote back. Prescience has two plans, Prescience Diamond and Prescience Value, each priced from the plans you sent or from the group’s market. Brokers use the same API keys as every partner. Prescience sets up your brokerage and invites your admins; sign in to the partner portal to create keys. Sandbox keys work first, then production.

Send a census and the plans you quoted

You already quote every plan for the client. Send them with the census and Prescience prices Diamond from them, with no marketplace query, so the answer usually comes back in the same request:

curl -X POST https://www.getprescience.com/api/partner/v1/quotes \
  -H "Authorization: Bearer $PRESCIENCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "company": {
      "name": "Northwind Dental",
      "domain": "northwinddental.com",
      "externalId": "crd_4821",
      "zip": "94110",
      "state": "CA"
    },
    "census": [
      {
        "externalId": "emp_0001",
        "firstName": "Ada",
        "lastName": "Reyes",
        "email": "ada@northwinddental.com",
        "dob": "1991-04-02",
        "zip": "94110"
      }
    ],
    "marketPlans": [
      {
        "carrier": "Blue Shield of California",
        "planName": "Platinum 90 PPO",
        "planType": "PPO",
        "metalTier": "Platinum",
        "hsaEligible": false,
        "deductibleIndividualCents": 0,
        "deductibleFamilyCents": 0,
        "oopMaxIndividualCents": 300000,
        "oopMaxFamilyCents": 600000,
        "monthlyRatesCents": {
          "employeeOnly": 96200,
          "employeeSpouse": 202000,
          "employeeChildren": 185000,
          "family": 278000
        }
      },
      {
        "carrier": "Cigna",
        "planName": "Bronze HSA PPO",
        "planType": "PPO",
        "metalTier": "Bronze",
        "hsaEligible": true,
        "deductibleIndividualCents": 640000,
        "deductibleFamilyCents": 1280000,
        "oopMaxIndividualCents": 750000,
        "oopMaxFamilyCents": 1500000,
        "monthlyRatesCents": {
          "employeeOnly": 39800,
          "employeeSpouse": 83600,
          "employeeChildren": 76500,
          "family": 119000
        }
      }
    ]
  }'

marketPlans takes up to 500 plans of any metal, funding type or carrier. Each plan needs its carrier, name, planType, metalTier, hsaEligible, deductibles, out-of-pocket maximums and a rate (see Send your own plans). From the list:

The plan Diamond sits on is the best HSA-eligible PPO, EPO or POS plan, unless you send a basePlan.
Prices are set against a platinum PPO in the list.
A plan Prescience can’t build on (an HMO, a plan missing a required field) is ignored, never rejected, and the response lists it in ignoredPlans with the reason, plus usedPlans (sent, used, baseCandidates, benchmarkCandidates). A 400 is only for broken JSON, a missing or invalid census, more than 500 plans, or a list with no usable plan.
With no HSA-eligible PPO, EPO or POS plan in the list, or no platinum PPO, the response is 422 market_unavailable, and its message gives the reasons (“No HSA-eligible PPO, EPO or POS plan in the plans sent.”, “No platinum PPO was quoted to compare with.”), one per plan as “Diamond: … Value: …”. When the list has a platinum PPO but no HSA base plan, the 202 has baseFromMarket: true: Prescience fetches a base plan from the market sweep (minutes) while the benchmark stays your platinum PPO.

The group is found by company.externalId, else company.domain, else created. Its census and plans are replaced by the ones you send, so sending the same company again re-quotes it. domain is required. company.ratingZip is the ZIP of the market to price when it differs from the headquarters ZIP. Households are priced from the dependents you send. When no employee in the census has a dependent listed, Prescience models a typical mix instead of assuming none (10% of employees with one dependent, 25% with a family), so the quote’s census.coveredLives is higher than the number of employees. Send dependents for every employee who has them; census.tiers shows what was priced. Without marketPlans, Prescience sweeps the group’s market through SimplyInsured instead, which takes minutes (see below).

When pricing takes longer

With marketPlans the request waits for pricing, which takes seconds. Without them, rates for a new census are fetched from the market first, which takes minutes. Until rates are ready the response is 202:

Response (202)

{
  "groupId": "grp_8c2f41d09a3e",
  "status": "pricing",
  "retryAfterSeconds": 20,
  "estimatedReadyAt": "2026-10-02T17:21:40.000Z",
  "sweep": { "step": "collecting_plans", "planCount": 42 }
}

Send the same request again after retryAfterSeconds: the same group is matched and, once rates are ready, you get 201 with the quote. You can also call POST /groups/{groupId}/quotes, or wait for the group.market_rates_ready webhook. A 202 is never stored under an Idempotency-Key, so repeating the request keeps working. 422 market_unavailable means Prescience can’t price the group from its market. Retrying does not help; a census or plan change starts a new comparison.

Reading a quote

plans has exactly two rows: Prescience Diamond (id: "diamond") and Prescience Value (id: "value"). Each has a one-line description.

Plan	What it is for a client
Prescience Diamond	The richest coverage, with the lowest member out-of-pocket costs.
Prescience Value	A lower price, with a higher member out-of-pocket maximum.

When a plan can’t be priced for a group, its row has status: "unavailable" and a reason, with no prices; the other plan still returns. A plan marked in_review is subject to Prescience underwriting review before it is final. Every version carries these fields, so an agent never has to recompute them. All money is integer cents.

Field	What it is
`id`, `name`, `description`	`diamond` or `value`, “Prescience Diamond” or “Prescience Value”, and a plain line on what it is.
`status`	`ready`, `in_review` (subject to underwriting review) or `unavailable`.
`monthly`	`pmpmCents` (base plan plus Prescience, all in, per covered person per month) and `totalCents` (the group’s monthly total). `pepmCents` is also returned.
`annual`	`totalCents`, exactly 12 times `monthly.totalCents`.
`price_components`	The all-in price split: `underlying_premium_monthly_cents` + `prescience_monthly_cents` = `total_monthly_cents`, and the same per covered person as `underlying_pmpm_cents`, `prescience_pmpm_cents` and `total_pmpm_cents`.
`monthly_rates_by_household`	The joint plan’s monthly rate for each kind of household in this census: `label` (for example “Employee + 1”), `people`, `households` (how many households in the census are this size) and `monthly_cents` (the price per covered person times the people in it). Rate times households, added up, is the group’s monthly total.
`new_member_rates_by_household`	What a household added after enrollment pays, by `label`, `people` and `monthly_cents`. It is not part of this census’s total.
`benchmark_rank`	Informational: which platinum PPO the plan was compared with, such as “platinum PPO 2 of 7”.
`rate_basis`	Where the rates came from, for `base_plan` and `benchmark`: `member_rates`, `pmpm`, `household_shape` or `swept` (our market sweep).
`base_plan`	The HSA-qualified base plan the plan sits on (`carrier`, `plan_name`) and its own deductible (`deductible_individual_cents`, `deductible_family_cents`). There is no Prescience deductible to quote: members’ cost is capped by `member_oop_max`.
`member_oop_max`	The most a member pays in a year: `individual_cents` and `family_cents`.
`benefits`	Out-of-pocket maximums (individual, employee plus one, family), `memberCoinsurancePct` (0), `hsaEligible`, `network` and the `features` list.
`all_max_year`	The employer’s year when every member reaches their out-of-pocket maximum: `base_premium_cents` + `prescience_cents` + `modeled_extra_cents` = `employer_total_cents`, and `members_pay_cents`, what members pay that year (their caps added up).
`median_year`	A median modeled year: `employer_total_cents` (the price, no extra), `pool_pays_cents` and `members_pay_cents`.
`worst_year`	The same all-max year as the employer’s modeled worst case: `modeled_extra_cents`, `modeled_total_cents` (equal to `all_max_year.employer_total_cents`), `benchmark_premium_cents`, `headroom_cents`, `basis`, `contractual: null` and a `note`. It is a modeled scenario from the Time Machine claims simulation for this census, not a contractual cap or guarantee; contract terms: confirm with Prescience. `recompute` gives the inputs to check it: the base plan’s annual premium, its out-of-pocket caps summed across the households, and the member out-of-pocket allowance assumed.
`hsa`	`eligible` and the `basis`: members enroll in an HSA-qualified high-deductible plan (the base plan, named), and Prescience coverage on top keeps them HSA-eligible.
`time_machine`	Where the numbers come from: `simulated_plan_years`, `census_members` and `generated_at`.
`renewal`	`method: null` and a note: contact Prescience for renewal terms.
`member_experience`	What members get: GLP-1s, blood and genetic testing, the wearable, the 24/7 care companion, preventive programs and managed setup.
`pricedAgainst`, `benchmarkPlan`	The platinum PPO the plan is compared with, and whether it is yours (`source: "broker"`) or one from the market.
`underlyingPlan`	The base plan. When it is yours, `source: "broker"`, your plan is echoed as `brokerPlan`, and a `note` says enrollment needs member IDs and eligibility from its carrier.
`comparison`	Against the benchmark: `annualSavingsCents`, `savingsPct`, `worstYearUnderBenchmarkCents`, and how the deductible, out-of-pocket maximums and HSA eligibility differ. Values the benchmark doesn’t report are `null`.
`fit_flags`	See Fit guidelines.
`broker_row`	One markdown table row to paste into a proposal.
`summary`	One sentence of numbers only.
`pricing_method`	Informational: `engine` or `cost_plus`.

The quote also has pricedOn (census_only, base_plan or market_plans), the census counts and ignoredPlans / usedPlans when you sent plans. See the Quote schema for every field.

Send your own plans

Prices depend on what you send. basePlan and each marketPlans item use the same shape:

You send	Priced
`marketPlans`	From every plan you quoted for the census (up to 500: all metals, any funding, any carrier), in place of our market sweep. The base is the best HSA-eligible PPO, EPO or POS in the list unless you send a `basePlan`. No marketplace is queried, so it is faster. With no HSA-eligible PPO, EPO or POS plan, or no platinum PPO, the plans can’t be priced.
Census only	On the best HSA-eligible PPO, EPO or POS swept for the group (minutes)
`basePlan`	On the carrier plan Diamond sits on, such as a BCBS bronze HDHP or a level-funded catastrophic plan you placed. This usually lowers the price.

Money is integer cents. Give each plan one rate basis:

memberRatesCents: the exact monthly rate for each employee’s household, as { "externalId", "monthlyCents" } by the census externalId. Preferred, because small-group rates are age-rated. It wins over the others; employees missing from it fall back to them.
pmpmCents: the price per covered person. A household costs this times its people.
monthlyRatesCents: the monthly premium for one household of each shape.

For example, by household shape:

{
  "carrier": "Example Carrier",
  "planName": "Level-funded catastrophic",
  "planType": "PPO",
  "fundingType": "level_funded",
  "hsaEligible": true,
  "deductibleIndividualCents": 750000,
  "deductibleFamilyCents": 1500000,
  "oopMaxIndividualCents": 750000,
  "oopMaxFamilyCents": 1500000,
  "monthlyRatesCents": {
    "employeeOnly": 33000,
    "employeeSpouse": 70000,
    "employeeChildren": 64000,
    "family": 100000
  }
}

Optional plan fields (carrierPlanId, network, fundingType, effectiveDate, ratingZip, embeddedDeductible, coinsurancePct, copaysCents, rxDeductibleCents, referralRequired, hsaDeductibleRequired, sbcUrl, doctorSearchUrl, carrierLogoUrl) are kept when valid and left out, with a note, when not; they never fail a plan. See the API reference for each. pricedOn on the quote says which mode was used. When the base plan is yours, plans[].underlyingPlan has source: "broker", repeats your plan, and notes that enrollment needs member IDs and eligibility from that plan’s carrier. Send null to clear a plan from the group.

Price Prescience on one plan

If you already know the plan the client will be on, send the census and that one plan to POST /price-on-plan instead.

Change a plan later

Send the same company again (same externalId, else the same domain) with changed basePlan or marketPlans. They are saved on the group and the group is priced again; send null to clear one. A basePlan that is an HMO or not HSA-eligible is ignored and reported in ignoredPlans, and the price comes from marketPlans or the sweep; plans in marketPlans can be any plan.

Which clients fit

Quote Prescience when the client is quoting gold or platinum, or wants rich benefits, in California (strong) or New Jersey (workable), with 5 to 50 employees, on a group plan. See the Fit guidelines for every criterion and what fit_check returns. Final pricing, eligibility and network are confirmed during underwriting and onboarding.

Get Started

Guides

Brokers

Resources

Send a census and the plans you quoted

When pricing takes longer

Reading a quote

Send your own plans

Price Prescience on one plan

Change a plan later

Which clients fit

​Send a census and the plans you quoted

​When pricing takes longer

​Reading a quote

​Send your own plans

​Price Prescience on one plan

​Change a plan later

​Which clients fit

Send a census and the plans you quoted

When pricing takes longer

Reading a quote

Send your own plans

Price Prescience on one plan

Change a plan later

Which clients fit