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

# Quotes

> Learn how quotes are priced and how to read every field of the Quote object.

`POST /groups/{groupId}/quotes` rates the stored census and returns the complete quote in the same response. No polling and no callback; most groups price in under a second.

## Create a quote

```bash theme={null}
curl -X POST https://www.getprescience.com/api/partner/v1/groups/grp_8c2f41d09a3e/quotes \
  -H "Authorization: Bearer $PRESCIENCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "planYearStartDate": "2026-09-01", "priorPepmCents": 80000 }'
```

Both fields are optional:

| Field               | Type                | Default                                 | Use                                                |
| ------------------- | ------------------- | --------------------------------------- | -------------------------------------------------- |
| `planYearStartDate` | date (`YYYY-MM-DD`) | First of the month at least 60 days out | Align to the employer's current renewal date.      |
| `priorPepmCents`    | integer (cents)     | `group.currentCoverage.pepmCents`       | Override the savings baseline for this quote only. |

Requires a quotable census (every member with `zip` plus `dob` | `age`), otherwise `422 census_required`. Rate limit: 60 quote creates per hour.

## The Quote object

The [quickstart quote](/quickstart#create-the-quote) for Acme Inc (12 employees, 19 covered lives, San Francisco), section by section:

<AccordionGroup>
  <Accordion title="status + pricingBasis: what this quote is" defaultOpen>
    ```json theme={null}
    { "status": "ready", "pricingBasis": "indicative" }
    ```

    `pricingBasis` is always `indicative`: **rates are indicative pending underwriting confirmation** and bind only at enrollment plus underwriting sign-off. Display this framing wherever you show the numbers; "indicative pricing" or the quote's own `assumptions` strings work.

    `status` is `ready` for nearly all groups. See [large groups](#large-groups-in_review) below for `in_review`.
  </Accordion>

  <Accordion title="census + monthly: the price">
    ```json theme={null}
    {
      "census": { "employees": 12, "coveredLives": 19,
                  "tiers": { "employeeOnly": 7, "employeeSpouse": 2, "employeeChildren": 1, "family": 2 } },
      "monthly": { "totalCents": 660096, "pepmCents": 55008,
                   "byTier": { "employeeOnly": { "count": 7, "avgCents": 34047 },
                               "employeeSpouse": { "count": 2, "avgCents": 89166 },
                               "employeeChildren": { "count": 1, "avgCents": 53987 },
                               "family": { "count": 2, "avgCents": 94724 } } },
      "annual": { "totalCents": 7921152 }
    }
    ```

    `monthly.totalCents` is the employer's all-in monthly cost: \$6,600.96 here. `pepmCents` is total ÷ active employees (\$550.08). `byTier` gives average member cost per coverage tier for display; tiers classify members by whether they cover a spouse and/or children.
  </Accordion>

  <Accordion title="employeeContribution: always zero">
    ```json theme={null}
    { "employeeContribution": { "premiumCents": 0 } }
    ```

    Employee premium contribution for this plan. Values are integer cents.
  </Accordion>

  <Accordion title="comparison: prior-cost comparison">
    ```json theme={null}
    {
      "comparison": { "priorPepmCents": 80000, "savingsMonthlyCents": 299904,
                      "savingsAnnualCents": 3598848, "savingsPct": 31 }
    }
    ```

    Computed against `priorPepmCents`, which comes from the quote request override or `group.currentCoverage.pepmCents`. If no prior PEPM was provided, the savings fields are zero. `savingsPct` is rounded to the nearest whole percent.
  </Accordion>

  <Accordion title="fundingBreakdown: where the premium-equivalent goes">
    ```json theme={null}
    {
      "fundingBreakdown": { "expectedClaimsPct": 78, "stopLossPct": 12,
                            "careNavigationPct": 10, "adminFeesPct": 0,
                            "note": "Illustrative split of the premium-equivalent." }
    }
    ```

    Illustrative allocation of the quoted monthly amount. The [account data guide](/guides/benefits-tab) covers in-force funding and spend fields after enrollment.
  </Accordion>

  <Accordion title="expiresAt + assumptions: the fine print">
    ```json theme={null}
    {
      "expiresAt": "2026-07-10T17:22:05Z",
      "assumptions": [ "Rates are indicative pending underwriting confirmation.",
                       "Census accepted as submitted; material changes re-rate." ]
    }
    ```

    Quote expiry is configuration-driven; the default window is 30 days after creation. Enrolling against an expired quote returns `410 quote_expired`; create a fresh one. An unchanged census re-prices identically. Preserve the `assumptions` strings anywhere quote terms are displayed.
  </Accordion>

  <Accordion title="pricing: rate card metadata">
    ```json theme={null}
    { "pricing": { "source": "code_default" } }
    ```

    Names the pricing-rules layer that produced this quote. Additive in v1.1; absent on quotes created before it, and every other quote field is unchanged.

    | Field       | Type                                           | Description                                                                                                                                  |
    | ----------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
    | `source`    | enum: `code_default` \| `default` \| `partner` | `partner`: integration-specific pricing configuration. `default`: platform default pricing configuration. `code_default`: built-in defaults. |
    | `updatedAt` | timestamp                                      | When the applied rate card was last updated. Absent for `code_default`.                                                                      |

    The quote expiry window and the in-review employee threshold are also set by pricing configuration; the defaults are 30 days and 200 employees. Quotes created before a configuration change are not re-priced.
  </Accordion>
</AccordionGroup>

## How the engine prices a census

Deterministic and pure: the same census, start date, and pricing configuration always produce the same cents. The API returns the computed result; integrations should store the returned quote rather than reimplementing rating logic.

At a high level, the rating engine uses:

1. Active employee and dependent census records.
2. Member age at `planYearStartDate`, computed from `dob` or the submitted `age`.
3. Home ZIP code for geographic rating.
4. Coverage tier classification from covered dependents.
5. The applied pricing configuration named by `pricing.source`.

Terminated members are excluded. PEPM is the rounded total over active employees.

<Note>
  You never need to reimplement any of this. It's documented so the numbers aren't a black box, and so your team can verify a quote by hand if they want to.
</Note>

## Large groups: `in_review`

Groups above the configured in-review employee threshold (**default 200 employees**) return `status: "in_review"` instead of `ready`. The monthly figures are present but held for Prescience underwriting review. When underwriting finalizes, the quote flips to `ready` and the [`quote.finalized` webhook](/guides/webhooks#event-catalog) fires. Re-fetch with `GET /groups/{groupId}/quotes/{quoteId}`.

Show these groups a "pricing in final review" state rather than the held numbers.

## Listing and re-fetching

* `GET /groups/{groupId}/quotes`: all quotes for a group, newest first, paginated with `limit`/`cursor`.
* `GET /groups/{groupId}/quotes/{quoteId}`: one quote, e.g. after `quote.finalized`.

Old quotes are never mutated (beyond `in_review → ready` and expiry); each re-quote is a new record, so you keep a full pricing history per employer.