> ## 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. # Give one plan, get the joint plan and our layer price > Send a census and one plan you priced per covered person per month (`pmpmCents`); get Prescience Diamond and Prescience Value on top of it: the plan's price plus the Prescience layer, which is the joint price. Each has `basePmpmCents + prescienceLayerPmpmCents = totalPmpmCents`, the monthly and annual totals, the member out-of-pocket maximum, the modeled worst year, and `prescienceOnly`: what Prescience alone costs (the plan's own premium is paid to its carrier). Anything defaulted (family deductible and out-of-pocket at twice the individual one, ZIP, company) is listed in `assumptions`. The census is kept as a lead. The request waits for pricing: `201` is the usual answer, `202` if it takes longer. Rate limit: 60 per hour, shared with quote creates. ## OpenAPI ````yaml /api-reference/openapi.json post /price-on-plan openapi: 3.1.0 info: title: Prescience Partner API version: 1.1.0 description: >- Create employer groups, submit census records, generate preliminary market-rate quotes, create iframe sessions, create enrollments, and read aggregate account data. Money is always integer cents. Dates are `YYYY-MM-DD`; timestamps are ISO 8601 UTC. Final pricing, eligibility, network availability, and plan documents are confirmed during underwriting and onboarding. A BAA and data processing agreement are executed before live mode is enabled. contact: name: Prescience partner engineering email: partners@getprescience.com servers: - url: https://www.getprescience.com/api/partner/v1 description: >- Production. Test and live traffic share this host; mode comes from your API key. security: - bearerAuth: [] tags: - name: Health description: Connectivity and key checks. - name: Plans description: Static plan metadata. - name: Groups description: 'Employer groups: the root resource of every integration.' - name: Census description: Pre-enrollment census intake and ongoing member sync. - name: Quotes description: >- Preliminary quotes built from the stored census and current local market-plan snapshot. - name: Enrollments description: Plan selection and employer provisioning. - name: Account description: Aggregate, de-identified employer account data. - name: Brokers description: >- Quoting for brokers, the MCP server, and elections for partner-run enrollment. - name: Webhooks description: Signed event delivery (standard-webhooks scheme). paths: /price-on-plan: post: tags: - Quotes summary: Give one plan, get the joint plan and our layer price description: >- Send a census and one plan you priced per covered person per month (`pmpmCents`); get Prescience Diamond and Prescience Value on top of it: the plan's price plus the Prescience layer, which is the joint price. Each has `basePmpmCents + prescienceLayerPmpmCents = totalPmpmCents`, the monthly and annual totals, the member out-of-pocket maximum, the modeled worst year, and `prescienceOnly`: what Prescience alone costs (the plan's own premium is paid to its carrier). Anything defaulted (family deductible and out-of-pocket at twice the individual one, ZIP, company) is listed in `assumptions`. The census is kept as a lead. The request waits for pricing: `201` is the usual answer, `202` if it takes longer. Rate limit: 60 per hour, shared with quote creates. operationId: priceOnPlan parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PriceOnPlanRequest' example: 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 responses: '200': description: >- The plan can't be built on (an HMO, not HSA-eligible, incomplete): `status: unavailable` with the reason and `ignoredPlans`. content: application/json: schema: $ref: '#/components/schemas/PriceOnPlanResponse' '201': description: Both versions. content: application/json: schema: $ref: '#/components/schemas/PriceOnPlanResponse' '202': description: Still pricing; send the same body again. content: application/json: schema: $ref: '#/components/schemas/QuotePending' '400': description: >- The request failed validation (for example an HMO or a plan that is not HSA-eligible). content: application/json: schema: $ref: '#/components/schemas/Error' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '422': description: Prescience couldn't price this plan. content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Too many requests. content: application/json: schema: $ref: '#/components/schemas/Error' components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false description: >- Any non-empty string; deterministic keys from your own IDs work best. Repeating the same key with the same body on the same endpoint and mode within 24 hours returns the stored successful response (with `Idempotent-Replay: true`) instead of re-executing. Error responses are not stored. schema: type: string example: 9f3b2c61-4a8d-4e2f-b1c7-d5a90e8f1a23 schemas: PriceOnPlanRequest: type: object required: - census - plan properties: census: type: array description: >- Members, as in `PUT /groups/{groupId}/census`. Time Machine needs it. items: $ref: '#/components/schemas/CensusMemberInput' plan: type: object description: >- The one plan to price Prescience on. It must be HSA-eligible and a PPO, EPO or POS plan; an HMO is rejected. Money is integer cents. required: - planType - hsaEligible - deductibleIndividualCents - oopMaxIndividualCents properties: carrier: type: string planName: type: string planType: type: string enum: - PPO - EPO - POS network: type: string hsaEligible: type: boolean description: Must be true. deductibleIndividualCents: type: integer deductibleFamilyCents: type: integer description: Twice the individual deductible when omitted. oopMaxIndividualCents: type: integer oopMaxFamilyCents: type: integer description: Twice the individual out-of-pocket maximum when omitted. pmpmCents: type: integer description: >- The plan's monthly price per covered person. A household costs this times the people on it. Required unless `monthlyRatesCents` is sent. monthlyRatesCents: type: object description: >- Monthly premium for one household of each shape, used only when neither `memberRatesCents` nor `pmpmCents` is sent. properties: employeeOnly: type: integer employeeSpouse: type: integer employeeChildren: type: integer family: type: integer memberRatesCents: type: array maxItems: 10000 description: >- Exact monthly rate for each employee's household (the employee and covered dependents), by the employee's census `externalId`. Small-group rates are age-rated, so this is the preferred basis. Employees missing from it fall back to `pmpmCents` or `monthlyRatesCents`. items: type: object required: - externalId - monthlyCents properties: externalId: type: string monthlyCents: type: integer company: type: object description: Optional. Without it the census is kept under a generated company. properties: name: type: string domain: type: string externalId: type: string zip: type: string description: 5 digits; the first census ZIP when omitted. state: type: string marketPlans: type: array maxItems: 500 items: $ref: '#/components/schemas/BrokerPlan' description: >- Optional: every plan you quoted. With a platinum PPO among them, `pricingMethod` is `engine`. PriceOnPlanResponse: type: object description: >- Both versions, or `status: unavailable` with a `reason` when the plan can't be built on (a `200`, not an error). properties: ignoredPlans: type: array description: >- Plans we skipped because we can't build on them, never an error: a plan missing a required field is dropped, and a `basePlan` that is an HMO, not HSA-eligible or incomplete is ignored (the price then comes from `marketPlans` or the sweep). Each has its `index` (or `basePlan` / `plan`), carrier, plan name and the reason. items: $ref: '#/components/schemas/IgnoredPlan' usedPlans: $ref: '#/components/schemas/UsedPlans' status: type: string enum: - unavailable reason: type: string groupId: type: string quoteId: type: string pricingMethod: type: string enum: - cost_plus - engine versions: type: array description: >- `diamond` and `value`, in the shape of a quote's `plans`, with `joint` and `prescienceOnly` added. A version that can't be priced has status `unavailable` and a reason. items: allOf: - $ref: '#/components/schemas/QuotePlan' - type: object properties: joint: type: object description: >- The plan you sent plus the Prescience layer. All money is cents; `basePmpmCents + prescienceLayerPmpmCents = totalPmpmCents`. properties: name: type: string example: Prescience Diamond option: type: string basePmpmCents: type: integer prescienceLayerPmpmCents: type: integer totalPmpmCents: type: integer totalPepmCents: type: integer monthlyCents: type: integer annualCents: type: integer description: Exactly 12 times `monthlyCents`. baseDeductibleIndividualCents: type: - integer - 'null' description: The HSA-qualified base plan's own deductible. memberOopMaxIndividualCents: type: - integer - 'null' memberOopMaxFamilyCents: type: - integer - 'null' modeledWorstYearCents: type: - integer - 'null' summary: type: string prescienceOnly: type: object description: What Prescience alone costs. properties: pmpmCents: type: integer pepmCents: type: integer monthlyCents: type: integer annualCents: type: integer note: type: string time_machine: type: - object - 'null' assumptions: type: array description: Everything defaulted or assumed, in words. items: type: string QuotePending: type: object required: - groupId - status - retryAfterSeconds properties: baseFromMarket: type: boolean description: >- True when nothing in `marketPlans` can be a base plan (an HSA-eligible PPO, EPO or POS), so Prescience fetches a base plan from the market sweep (minutes) while the benchmark stays the platinum PPO in your list. note: type: string ignoredPlans: type: array description: >- Plans we skipped because we can't build on them, never an error: a plan missing a required field is dropped, and a `basePlan` that is an HMO, not HSA-eligible or incomplete is ignored (the price then comes from `marketPlans` or the sweep). Each has its `index` (or `basePlan` / `plan`), carrier, plan name and the reason. items: $ref: '#/components/schemas/IgnoredPlan' usedPlans: $ref: '#/components/schemas/UsedPlans' groupId: type: string status: type: string const: pricing estimatedReadyAt: type: string format: date-time retryAfterSeconds: type: integer waitingOn: type: string const: cron description: >- Present when the sweep has not started and only Prescience's scheduled run (about every five minutes) will pick it up; retryAfterSeconds is then 300. waitingOnNote: type: string sweep: type: object properties: step: type: string planCount: type: integer Error: type: object required: - error - message properties: error: type: string enum: - invalid_request - unauthorized - live_mode_disabled - forbidden - not_found - conflict - rates_pending - quote_expired - market_unavailable - census_required - rate_limited - server_error - not_configured - email_not_allowed - verification_failed description: >- Stable machine-readable error code. `email_not_allowed` and `verification_failed` come only from the iframe's own endpoints, which partners do not call. message: type: string description: >- Human-readable explanation. Wording may change; branch on `error`, not `message`. details: type: array description: Present on `invalid_request`. One entry per failed field. items: type: object required: - field - message properties: field: type: string example: zip message: type: string example: zip must be a 5-digit ZIP code index: type: integer description: >- For array payloads (census rows), the zero-based index of the failing row. example: 7 CensusMemberInput: type: object required: - zip anyOf: - required: - dob - required: - age description: >- One employee record. Include dependent elections when your platform has them; submitted dependents drive covered lives and household tiers. When they are unavailable, Prescience uses a disclosed normalized small-group household mix for the preliminary model. properties: externalId: type: string description: >- Your payroll's employee ID (Check `Employee.id`). Required at enrollment; the upsert key, and how payroll results find the employee. example: emp_0001 firstName: type: string example: Jordan lastName: type: string example: Reyes email: type: string format: email description: Upsert key when present. example: jordan@acme.com dob: type: string format: date example: '1992-03-14' age: type: integer description: Alternative to `dob`. One of the two is required. example: 34 zip: type: string pattern: ^[0-9]{5}$ description: 5-digit home ZIP. Drives local market selection and rating. example: '94110' sexAtBirth: type: string enum: - male - female - other employmentType: type: string enum: - full_time - part_time - contractor hireDate: type: string format: date example: '2024-03-01' status: type: string enum: - active - terminated default: active dependents: type: array maxItems: 6 description: Optional household members already known to your platform. items: type: object required: - relationship properties: relationship: type: string enum: - spouse - domestic_partner - child - other name: type: string maxLength: 120 dob: type: string format: date BrokerPlan: type: object description: >- A carrier plan a broker brings. Money is integer cents. Send one rate basis: `memberRatesCents` (exact, preferred; wins over the others), `pmpmCents`, or `monthlyRatesCents` per household shape. A plan we can't build on is ignored and reported in `ignoredPlans`, never rejected; an optional field that is invalid is left out. required: - carrier - planName - planType - hsaEligible - deductibleIndividualCents - deductibleFamilyCents - oopMaxIndividualCents - oopMaxFamilyCents properties: carrier: type: string example: Example Carrier planName: type: string example: Gold PPO 1500 planType: type: string enum: - PPO - EPO - POS - HMO metalTier: type: string example: Gold network: type: string fundingType: type: string enum: - fully_insured - level_funded hsaEligible: type: boolean deductibleIndividualCents: type: integer deductibleFamilyCents: type: integer oopMaxIndividualCents: type: integer oopMaxFamilyCents: type: integer monthlyRatesCents: type: object description: >- Monthly premium for one household of each shape (all four, above 0). Used when neither `memberRatesCents` nor `pmpmCents` is sent. required: - employeeOnly - employeeSpouse - employeeChildren - family properties: pmpmCents: type: integer description: >- The plan's monthly price per covered person, cents. A household costs this times the people on it. A rate basis: send `memberRatesCents`, `pmpmCents` or `monthlyRatesCents`; the quote says which was used in `rate_basis`. memberRatesCents: type: array maxItems: 10000 description: >- Exact monthly rate for each employee's household (employee and covered dependents), by the employee's `externalId` in the census. Preferred, because small-group rates are age-rated. Wins over `pmpmCents` and `monthlyRatesCents`; an employee missing from it takes the average of their household type. items: type: object required: - externalId - monthlyCents properties: externalId: type: string monthlyCents: type: integer carrierPlanId: type: string effectiveDate: type: string format: date description: When the rates take effect. ratingZip: type: string description: The ZIP (rating area) the rates were quoted for. embeddedDeductible: type: boolean description: True when the family deductible embeds an individual one. coinsurancePct: type: number description: Member coinsurance after the deductible, 0 to 100. copaysCents: type: object description: Copays in cents; any may be left out. properties: primaryCare: type: integer specialist: type: integer urgentCare: type: integer emergencyRoom: type: integer rxGeneric: type: integer rxPreferred: type: integer rxSpecialty: type: integer rxDeductibleCents: type: integer referralRequired: type: boolean hsaDeductibleRequired: type: object description: >- Which benefits require the deductible, so the HSA check can verify the plan as it does a swept one: `pcp_visit`, `specialist_visit`, `hospitalization`, `emergency_room`, `urgent_care`, `labs`, `mri`, `surgery`, `mental_health` and `drug_tier:`, each true, false or null. Without it the HSA check uses the deductible and out-of-pocket limits and your `hsaEligible` flag. additionalProperties: type: - boolean - 'null' sbcUrl: type: string description: https URL. doctorSearchUrl: type: string description: https URL. carrierLogoUrl: type: string description: https URL. employeeOnly: type: integer employeeSpouse: type: integer employeeChildren: type: integer family: type: integer pmpmCents: type: integer description: >- Monthly price per covered person. A household costs this times the people on it. Wins over `monthlyRatesCents`. memberRatesCents: type: array maxItems: 10000 description: >- Exact monthly rate for each employee's household (the employee and covered dependents), by the employee's census `externalId`. Small-group rates are age-rated, so this is the preferred basis. Employees missing from it fall back to `pmpmCents` or `monthlyRatesCents`. items: type: object required: - externalId - monthlyCents properties: externalId: type: string monthlyCents: type: integer carrierPlanId: type: string effectiveDate: type: string format: date description: The date the rates are effective. ratingZip: type: string description: The ZIP (rating area) the rates were quoted for, 5 digits. embeddedDeductible: type: boolean description: True when the family deductible embeds an individual one. coinsurancePct: type: number minimum: 0 maximum: 100 description: Member coinsurance after the deductible. copaysCents: type: object description: Copays in cents. properties: primaryCare: type: integer specialist: type: integer urgentCare: type: integer emergencyRoom: type: integer rxGeneric: type: integer rxPreferred: type: integer rxSpecialty: type: integer rxDeductibleCents: type: integer referralRequired: type: boolean hsaDeductibleRequired: type: object description: >- Which benefits require the deductible, so the HSA check can verify the plan. Keys: `pcp_visit`, `specialist_visit`, `hospitalization`, `emergency_room`, `urgent_care`, `labs`, `mri`, `surgery`, `mental_health` and `drug_tier:`. additionalProperties: type: - boolean - 'null' sbcUrl: type: string description: An https URL. doctorSearchUrl: type: string description: An https URL. carrierLogoUrl: type: string description: An https URL. IgnoredPlan: type: object required: - index - reason properties: index: description: Position in `marketPlans`, or `basePlan` or `plan`. oneOf: - type: integer - type: string enum: - basePlan - plan carrier: type: string planName: type: string reason: type: string example: >- metalTier: metalTier is required (for example Platinum, Gold, Silver, Bronze). UsedPlans: type: object description: What was sent in `marketPlans` and what could be built on. properties: sent: type: integer used: type: integer baseCandidates: type: integer description: 'HSA-eligible PPO, EPO or POS plans: what Diamond can sit on.' benchmarkCandidates: type: integer description: 'Platinum PPOs: what Diamond is priced against.' QuotePlan: type: object description: >- One computed version of Prescience Diamond, the one plan Prescience offers. Both versions share the name; `option` tells them apart. `annual.totalCents` is exactly 12 times `monthly.totalCents`. required: - id - name - description - status properties: id: type: string enum: - diamond - value description: >- Two plans. `diamond` (Prescience Diamond) is the richest coverage, with the lowest member out-of-pocket. `value` (Prescience Value) is a lower price with a higher member out-of-pocket maximum. A plan is `unavailable` with a reason when it can't be offered for this group. name: type: string example: Prescience Diamond description: type: string description: One plain line on what the plan is. pricing_method: type: string enum: - engine - cost_plus description: How the price was built; informational. status: type: string enum: - ready - in_review - unavailable reason: type: string description: Why the version is `unavailable`. monthly: type: object properties: totalCents: type: integer pepmCents: type: integer pmpmCents: type: integer annual: type: object properties: totalCents: type: integer pricedAgainst: type: - object - 'null' properties: carrier: type: string planName: type: string metalTier: type: string source: type: string enum: - broker - market label: type: string benchmarkPlan: type: - object - 'null' properties: carrier: type: string planName: type: string metalTier: type: string network: type: - string - 'null' underlyingPlan: type: - object - 'null' properties: carrier: type: string planName: type: string network: type: string source: type: string enum: - broker - market fundingType: type: string brokerPlan: $ref: '#/components/schemas/BrokerPlan' note: type: string description: >- Present when `source` is `broker`: enrollment needs member IDs and eligibility from that plan's carrier. benefits: type: object properties: oopMaxIndividualCents: type: integer oopMaxEmployeePlusOneCents: type: integer oopMaxFamilyCents: type: integer memberCoinsurancePct: type: number hsaEligible: type: boolean network: type: string features: type: array items: type: object properties: title: type: string description: type: string price_components: type: object properties: underlying_premium_monthly_cents: type: integer description: What the base plan costs a month for these households. prescience_monthly_cents: type: integer description: 'What Prescience adds a month: total minus the base plan.' total_monthly_cents: type: integer underlying_pmpm_cents: type: integer description: The base plan's price per covered person per month. prescience_pmpm_cents: type: integer description: >- The Prescience layer per covered person per month: total minus the base plan. total_pmpm_cents: type: integer description: >- Base plan plus the Prescience layer, per covered person per month. worst_year: type: object description: >- A modeled scenario from the Time Machine claims simulation, never a contractual cap or guarantee. properties: modeled_extra_cents: type: integer modeled_total_cents: type: integer benchmark_premium_cents: type: - integer - 'null' description: >- The annual premium of the plan this was compared with, when there is one. headroom_cents: type: - integer - 'null' basis: type: string contractual: type: 'null' note: type: string recompute: type: object description: The inputs the modeled worst year can be checked with. properties: underlying_annual_premium_cents: type: integer theoretical_exposure_cents: type: integer description: >- The base plan's out-of-pocket caps summed across the households. member_oop_allowance_cents: type: integer description: The individual member OOP this version assumes. base_plan: type: object description: >- The HSA-qualified base plan Diamond sits on and its own deductible. There is no Diamond deductible to quote: members' cost is capped by `member_oop_max`. properties: carrier: type: string plan_name: type: string deductible_individual_cents: type: - integer - 'null' deductible_family_cents: type: - integer - 'null' label: type: string example: HSA-qualified base plan deductible member_oop_max: type: object description: The most a member pays in a year. properties: individual_cents: type: integer family_cents: type: integer benchmark_rank: type: - string - 'null' description: >- Informational: which plan in your list the comparison was made against. rate_basis: type: object description: >- Where the rates behind this price came from, for the base plan and the benchmark: `member_rates`, `pmpm`, `household_shape` or `swept` (our market sweep). properties: base_plan: type: string enum: - member_rates - pmpm - household_shape - swept benchmark: type: - string - 'null' enum: - member_rates - pmpm - household_shape - swept - null monthly_rates_by_household: type: array description: >- The joint plan's monthly rate for each kind of household in this census: the price per covered person times the people in it. Rate times households, added up, is the group's monthly total (to the cent per household). items: type: object properties: label: type: string example: Employee + 1 people: type: integer households: type: integer description: How many households in the census are this size. monthly_cents: type: integer new_member_rates_by_household: type: array description: >- What a household added after enrollment pays; not part of this census's total. items: type: object properties: label: type: string people: type: integer monthly_cents: type: integer all_max_year: type: object description: >- The employer's year when every member reaches their out-of-pocket maximum: base premium + Prescience price + the modeled extra = `employer_total_cents`, and what members pay in it (their caps added up). A modeled scenario, not a guarantee. properties: base_premium_cents: type: integer prescience_cents: type: integer modeled_extra_cents: type: integer employer_total_cents: type: integer members_pay_cents: type: integer median_year: type: object description: >- A median modeled year: the employer pays the price (no extra), the claims pool pays `pool_pays_cents`, and members pay the rest. properties: employer_total_cents: type: integer pool_pays_cents: type: integer members_pay_cents: type: integer time_machine: type: object properties: simulated_plan_years: type: - integer - 'null' census_members: type: integer generated_at: type: - string - 'null' format: date-time hsa: type: object properties: eligible: type: boolean basis: type: - string - 'null' renewal: type: object properties: method: type: 'null' note: type: string member_experience: type: object additionalProperties: type: - string - 'null' fit_flags: type: array items: type: string comparison: type: object description: >- How this version compares with the plan it was priced against. Positive numbers favor this version; null where the benchmark's value wasn't reported. properties: benchmark: type: object properties: carrier: type: string planName: type: string metalTier: type: string annualCents: type: integer deductibleIndividualCents: type: - integer - 'null' oopMaxIndividualCents: type: integer oopMaxFamilyCents: type: integer hsaEligible: type: - boolean - 'null' annualSavingsCents: type: integer savingsPct: type: number worstYearUnderBenchmarkCents: type: integer oopMaxIndividualLowerByCents: type: integer oopMaxFamilyLowerByCents: type: integer hsaEligibleWhereBenchmarkIsNot: type: - boolean - 'null' broker_row: type: string description: One markdown table row. summary: type: string description: One sentence, numbers only. responses: Unauthorized: description: Missing, malformed, or revoked API key. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: unauthorized message: >- Provide a valid partner API key as `Authorization: Bearer psk_...`. Forbidden: description: >- Key is live-mode but live mode is not enabled for this account, or the key may not access this resource. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: live_mode_disabled message: >- Live mode is not enabled for this account yet. Complete the go-live checklist to enable live keys. securitySchemes: bearerAuth: type: http scheme: bearer description: >- Partner API key. `psk_test_<32 hex>` for test mode, `psk_live_<32 hex>` for live mode. Store them in your secrets manager on issue. Live keys are shown once; the scoped partner portal can show an active sandbox key again. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.