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 group’s market, which Prescience finds itself from the census. Requests and answers use snake_case field names, on REST and on MCP. camelCase requests are still accepted. 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

Send the company and its census. Prescience finds the plans in the group’s market itself and prices Diamond and Value against them. If you know what the client pays for its current plan, send it as current_coverage: the quote then shows how each version compares with it.

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",
      "external_id": "crd_4821",
      "zip": "94110"
    },
    "census": [
      {
        "external_id": "emp_0001",
        "first_name": "Ada",
        "last_name": "Reyes",
        "email": "ada@northwinddental.com",
        "dob": "1991-04-02",
        "zip": "94110"
      }
    ],
    "current_coverage": {
      "carrier": "Blue Shield of California",
      "pepm_cents": 96200,
      "renewal_date": "2027-01-01"
    }
  }'

current_coverage is optional: the carrier, pepm_cents (what the current plan costs per employee per month, its renewal price if you have one) and renewal_date. Each version in the quote then has vs_current_plan: the current plan’s annual cost (pepm_cents times the employees quoted) and how much less or more the version costs. The price is still set against the market, because a current plan’s cost may cover other people than this census. Don’t send the plans you quoted. market_plans is no longer used: a request that has it is priced the same way, and each plan in it is listed in ignored_plans. The group is your group in the same mode (sandbox or live) with this company.external_id, else with this company.domain; an enrolled group is never matched. If there is none, a group is created. Its census and plans are replaced by the one you send. Asking again for the same group, census and pricing run returns the quote already made; a changed census or a new pricing run makes a new quote. domain is required. company.zip is the headquarters ZIP, and the group is quoted from it. If half or more of the employees live in one other ZIP, that ZIP is quoted too, and a group with fewer than 5 employees is quoted in every ZIP its employees live in. company.rating_zip replaces zip as the headquarters ZIP when you send it. There is no state input: Prescience takes the state from the ZIP, and address.state in responses is that value. 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.covered_lives is higher than the number of employees. Send dependents for every employee who has them; census.tiers shows what was priced. Pricing a new census takes a few minutes (see below).

When pricing takes longer

Pricing a new census takes a few minutes. Until it is ready the response is 202:

Response (202)

{
  "status": "pricing",
  "group_id": "grp_8c2f41d09a3e",
  "retry_after_seconds": 20,
  "message": "Pricing takes a few minutes. Try again in 20 seconds with the same request."
}

Send the same request again after retry_after_seconds (the Retry-After header says the same): the same group is matched and, once pricing is done, you get 201 with the quote, and the same quote on every call after that. 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. Retrying does not help; a census change starts a new comparison.

Reading a quote

plans has exactly two rows: Prescience Diamond (id: "diamond") and Prescience Value (id: "value").

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 deductible equal to its 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. A quote returns plan numbers and material links by default. All money is integer cents, so an agent never has to recompute it.

Field	What it is
`quote_id`, `status`, `group_id`, `expires_at`	The quote, whether it is `ready`, its group and when it expires. `plan_year_start_date` and `census` (`employees`, `covered_lives`) say what it was priced for.
`plans[].id`, `plan_name`, `status`	`diamond` or `value`, “Prescience Diamond” or “Prescience Value”, and `ready`, `in_review` or `unavailable`.
`plans[].monthly_premium_cents`	The group’s monthly price.
`plans[].pmpm_cents`	The price per covered person per month.
`plans[].rates_by_household`	The monthly rate of each kind of household in this census: `label` (for example “Employee + 1”), `households` (how many) and `monthly_cents`. Rate times households, added up, is the monthly price.
`plans[].deductible_cents`	The member’s deductible. $0 for Diamond; Value’s equals its out-of-pocket maximum.
`plans[].oop_max_cents`	The most a member pays in a year.
`plans[].max_extra_cents`	The most extra the company pays if every employee reaches that maximum. 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.
`materials`	Interactive pages and PDFs for employees and employers; see Share quote materials.
`ignored_plans`	Plans you sent that were skipped, and why. Only when there are some.

Every current quote includes materials: five designed documents for the quoted group. Each row has kind, title, page_url and pdf_url.

`kind`	Title	Who it is for
`benefits-packet`	Employee benefits packet	The employer and its employees
`health-benefits-guide`	Employee health benefits guide	The employer and its employees
`network`	Network explorer	The employer: in-network providers near each home ZIP, a doctor search, and a search by employee, ZIP or city
`platform`	About Prescience	The employer
`playbook`	Presenting Prescience	You and your team only: talk track, comparison and objection handling

How to use the links

To view a material yourself, open page_url. It is the interactive page, in the browser, with no sign-in.
To send a material to the employer, send its page_url, attach the PDF from pdf_url, or both. Do not send the Presenting Prescience playbook.
To show the links in your own tool, put a View button (page_url) and a PDF button (pdf_url) beside each title.

Slack, email, the broker portal and MCP return the same links. Emails we send you. When a quote is priced, your team’s listed addresses get two emails:

The quote email, written for the employer: the benefits packet, health benefits guide, network explorer and About Prescience, each with its PDF attached. You can forward it as it is.
“For you”: the plan prices, the group link, a client email draft, and all five materials with their PDFs attached.

To turn both off for a group, send "send_emails": false with the quote request. Send true to turn them back on.

{
  "materials": [
    {
      "kind": "benefits-packet",
      "title": "Employee benefits packet",
      "page_url": "https://www.getprescience.com/broker-materials/EXAMPLE_TOKEN/benefits-packet",
      "pdf_url": "https://www.getprescience.com/broker-materials/EXAMPLE_TOKEN/benefits-packet/pdf"
    }
  ]
}

This is an illustrative URL, not a working share link. Use the exact URLs in your response. Display both View and PDF beside each title. Recipients can switch Diamond and Value on the page, open the other materials, and forward the link to employees without an account. Append ?plan=diamond or ?plan=value to either URL to select an available quoted plan; the download follows that plan. The page and PDF use the stored quote inputs. No employer logo is needed; missing display names use a fixed fallback. Missing plan facts stay unconfirmed. Employee contributions are chosen during enrollment; group premiums are not an employee payroll deduction. The network page labels directory samples and unavailable data explicitly. The network explorer lists covered people by name under their home ZIP, so you can search the team by name, ZIP or city; no material shows dates of birth. Links in a 202 response are tied to the original rating inputs and test/live mode. They show a preparation page until that quote is ready. A changed census or plan input requires a new quote; old material links show a refresh message and PDF requests return 409. Quote-specific links retain the quoted plan. Links have no scheduled expiry, but suspension of the partner, disabling live access for live groups, removal of the quote or group, changed rating inputs, or a signing-key change can revoke access. The quote’s validity date remains visible: a shareable link does not extend pricing validity or approve enrollment. materials is included in both view=numbers and view=full. fields=materials keeps just the links and required identifiers; exclude=materials omits them. Older quotes without a saved census fingerprint may have no materials. The API reference documents the schema; MCP returns the same snake_case keys.

Only Prescience’s plans come back

A quote returns Prescience Diamond and Prescience Value and nothing about other carriers’ plans, or about how the plans are found. Compare against the quotes you already have from your carriers.

Choose how much comes back

view picks how much of the quote you get. It works as a query parameter or in the body of POST /quotes and POST /groups/{groupId}/quotes, as a query parameter on the quote GETs, and as view on the MCP tools quote_group and get_quote.

`view`	Returns
`numbers` (the default)	The fields above and nothing else.
`full`	The numbers, and what each plan is: `description`, `annual_premium_cents`, `member_coinsurance_pct`, `hsa_eligible`, `oop_max_family_cents`, `features`, `median_year`, `fit_flags` and `logos`. Each fact appears once.

fields and exclude work on top of either view: fields returns only those fields, for example fields=plans.pmpm_cents; exclude leaves some out, for example exclude=plans.logos. Send them as a comma-separated query parameter or as a list in the body. quote_id, group_id and status always come back. What each plan is (its description, benefits, member terms and logos) does not change per group: get it once from the plan details and cache it. view=numbers, the default:

{
  "quote_id": "qt_5b9e2c7f10ad",
  "status": "ready",
  "group_id": "grp_8c2f41d09a3e",
  "expires_at": "2026-11-01T17:22:05Z",
  "plan_year_start_date": "2026-11-01",
  "census": {
    "employees": 3,
    "covered_lives": 4
  },
  "plans": [
    {
      "id": "diamond",
      "plan_name": "Prescience Diamond",
      "status": "ready",
      "monthly_premium_cents": 200000,
      "pmpm_cents": 50000,
      "rates_by_household": [
        {
          "label": "Employee only",
          "households": 2,
          "monthly_cents": 50000
        },
        {
          "label": "Employee + 1",
          "households": 1,
          "monthly_cents": 100000
        }
      ],
      "deductible_cents": 0,
      "oop_max_cents": 150000,
      "max_extra_cents": 600000
    },
    {
      "id": "value",
      "plan_name": "Prescience Value",
      "status": "ready",
      "monthly_premium_cents": 160000,
      "pmpm_cents": 40000,
      "rates_by_household": [
        {
          "label": "Employee only",
          "households": 2,
          "monthly_cents": 40000
        },
        {
          "label": "Employee + 1",
          "households": 1,
          "monthly_cents": 80000
        }
      ],
      "deductible_cents": 300000,
      "oop_max_cents": 300000,
      "max_extra_cents": 700000
    }
  ]
}

view=full:

{
  "quote_id": "qt_5b9e2c7f10ad",
  "status": "ready",
  "group_id": "grp_8c2f41d09a3e",
  "expires_at": "2026-11-01T17:22:05Z",
  "plan_year_start_date": "2026-11-01",
  "census": {
    "employees": 3,
    "covered_lives": 4
  },
  "plans": [
    {
      "id": "diamond",
      "plan_name": "Prescience Diamond",
      "status": "ready",
      "monthly_premium_cents": 200000,
      "pmpm_cents": 50000,
      "rates_by_household": [
        {
          "label": "Employee only",
          "households": 2,
          "monthly_cents": 50000
        },
        {
          "label": "Employee + 1",
          "households": 1,
          "monthly_cents": 100000
        }
      ],
      "deductible_cents": 0,
      "oop_max_cents": 150000,
      "max_extra_cents": 600000,
      "description": "The richest coverage, with the lowest member out-of-pocket costs.",
      "annual_premium_cents": 2400000,
      "member_coinsurance_pct": 0,
      "hsa_eligible": true,
      "oop_max_family_cents": 300000,
      "features": [
        {
          "title": "GLP-1s for all indications",
          "description": "Covered for every indication, not only diabetes."
        },
        {
          "title": "HSA-eligible",
          "description": "Pairs with a health savings account for pre-tax saving on care."
        }
      ],
      "logos": {
        "plan": "https://www.getprescience.com/img/prescience-mark.png",
        "wordmark": "https://www.getprescience.com/img/prescience-wordmark.svg"
      }
    },
    {
      "id": "value",
      "plan_name": "Prescience Value",
      "status": "ready",
      "monthly_premium_cents": 160000,
      "pmpm_cents": 40000,
      "rates_by_household": [
        {
          "label": "Employee only",
          "households": 2,
          "monthly_cents": 40000
        },
        {
          "label": "Employee + 1",
          "households": 1,
          "monthly_cents": 80000
        }
      ],
      "deductible_cents": 300000,
      "oop_max_cents": 300000,
      "max_extra_cents": 700000,
      "description": "A lower price, with a deductible equal to the member out-of-pocket maximum.",
      "annual_premium_cents": 1920000,
      "member_coinsurance_pct": 0,
      "hsa_eligible": true,
      "oop_max_family_cents": 600000,
      "features": [
        {
          "title": "GLP-1s for all indications",
          "description": "Covered for every indication, not only diabetes."
        },
        {
          "title": "HSA-eligible",
          "description": "Pairs with a health savings account for pre-tax saving on care."
        }
      ],
      "logos": {
        "plan": "https://www.getprescience.com/img/prescience-mark.png",
        "wordmark": "https://www.getprescience.com/img/prescience-wordmark.svg"
      }
    }
  ]
}

Plan details

GET /api/partner/v1/plans returns your two plans, and GET /api/partner/v1/plans/{planId} one of them (diamond or value), in snake_case: name, description, benefits (coinsurance, HSA eligibility and the feature list), member_terms, the employer contribution range, logos, a selling_guide link and disclaimers. They are the same for every group, so fetch them once and cache them (Cache-Control: private, max-age=3600). The MCP tool get_plan_details returns the same: with plan_id the plan itself, as GET /plans/{planId} does, and without it { "plans": [...] }. GET /plans/diamond:

{
  "id": "diamond",
  "name": "Prescience Diamond",
  "description": "The richest coverage, with the lowest member out-of-pocket costs.",
  "benefits": {
    "member_coinsurance_pct": 0,
    "hsa_eligible": true,
    "features": [
      {
        "title": "Advanced blood testing",
        "description": "Included through Prescience Foresight, with clinician-guided follow-up."
      },
      {
        "title": "Genetic testing",
        "description": "Included when clinically appropriate, with results translated into a personal care plan."
      },
      {
        "title": "24/7 care companion",
        "description": "Crystal helps members find care, understand costs, and get answers before a bill arrives."
      },
      {
        "title": "Preventive health programs",
        "description": "Access to Prescience Foresight programs, including metabolic health and connected-device support, subject to eligibility."
      },
      {
        "title": "GLP-1s for all indications",
        "description": "Covered for every indication, not only diabetes."
      },
      {
        "title": "HSA-eligible",
        "description": "Pairs with a health savings account for pre-tax saving on care."
      },
      {
        "title": "Wearable included",
        "description": "Every member gets a wearable at no extra cost."
      },
      {
        "title": "Fully managed setup",
        "description": "Prescience runs plan setup, enrollment and payroll syncing."
      }
    ]
  },
  "member_terms": "The lowest member out-of-pocket costs. Deductible and out-of-pocket maximums are set per group: a quote has them as deductible_cents and oop_max_cents.",
  "employer_contribution": {
    "min_pct": 50,
    "max_pct": 100
  },
  "logos": {
    "plan": "https://www.getprescience.com/img/prescience-mark.png",
    "wordmark": "https://www.getprescience.com/img/prescience-wordmark.svg"
  },
  "selling_guide": {
    "url": "https://www.getprescience.com/api/partner/v1/mcp/skill",
    "markdown_url": "https://www.getprescience.com/api/partner/v1/mcp/skill?format=md"
  },
  "disclaimers": [
    "Final plan documents govern. Benefit details are confirmed during onboarding."
  ]
}

Plan design and moving forward

Carriers ask for a few plan terms before they quote. Set them on the group with POST /groups, PATCH /groups/{groupId} or a plan_design object in POST /quotes, which also takes the group’s current_coverage (carrier, pepm_cents for the renewal price, renewal_date); all are optional, and a field sent as null is cleared. They come back on GET /groups/{groupId} as plan_design.

Field
`plan_design.waiting_period`	How long a new hire waits for coverage, in your words (up to 120 characters).
`plan_design.rehire_policy`	What happens to coverage on a rehire or a leave, in your words (up to 300 characters).
`plan_design.employer_contribution`	`employee_pct` and `dependent_pct`: the share of the premium the employer pays, 0 to 100.

curl -X PATCH https://www.getprescience.com/api/partner/v1/groups/grp_8c2f41d09a3e \
  -H "Authorization: Bearer $PRESCIENCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "plan_design": { "waiting_period": "First of the month after 30 days", "employer_contribution": { "employee_pct": 80, "dependent_pct": 50 } } }'

When the client wants to move forward, tell Prescience with POST /groups/{groupId}/move-forward. It records the request on the group as move_forward (status: "requested", requested_at and requested_by) and Prescience sets up enrollment. The body is optional: requested_by names the person on your side (it defaults to your partner name) and note adds a line. A second request changes nothing and returns the first one. Until the group has a quote for its current census (before the first quote, or while an edited census is being repriced) it returns 409 quote_not_ready: wait for the quote (a 202 from POST /quotes says how long), then call it again. From then on GET /groups/{groupId} also returns enrollment: the carrier and plan_name to submit for enrollment, and its status (setting_up, then enrolled).

Edit the census

PUT /groups/{groupId}/census/members adds, updates and removes members without sending the whole census:

{
  "members": [
    { "external_id": "emp_0012", "email": "sam@acme.com", "dob": "1988-11-20", "zip": "94110" }
  ],
  "remove": [{ "external_id": "emp_0003" }]
}

members match like a census PUT (external_id, else email): a match is updated, anything else is added. remove names members by member_id, external_id or email; when an entry gives more than one, they must all name the same member. The answer gives accepted, removed, member_count, not_found (positions in remove that matched nobody) and errors by index; valid rows are applied. Quotes you already have are kept but no longer match the census, so quote again to price the new one. An enrolled group answers 409.

Reading a group

GET /groups/{groupId} and GET /groups (MCP get_group and list_groups) return the same group:

{
  "id": "grp_8c2f41d09a3e",
  "mode": "test",
  "status": "quoted",
  "company_name": "Northwind Dental",
  "legal_entity_name": null,
  "domain": "northwinddental.com",
  "external_id": "crd_4821",
  "address": { "zip": "94110", "state": "CA" },
  "contact": null,
  "current_coverage": null,
  "census_member_count": 3,
  "company_state": null,
  "created_at": "2026-10-01T17:04:11Z",
  "updated_at": "2026-10-01T17:22:05Z",
  "market_plans": 2,
  "rating_zip": "94110",
  "pricing": "done",
  "enrolled": false,
  "benefits_admin": "prescience",
  "latest_quote": {
    "quote_id": "qt_5b9e2c7f10ad",
    "status": "ready",
    "created_at": "2026-10-01T17:22:05Z",
    "quote_pepm_cents": 50000,
    "quote_annual_cents": 2400000,
    "plans_available": ["diamond", "value"]
  }
}

plan_design, move_forward and enrollment appear once they are set. market_plans is always 0: plans you send are no longer used. pricing is where pricing stands and latest_quote the group’s newest quote in a line. GET /groups returns { "groups": [...], "count": 1, "next_cursor": null }; pass limit and cursor to page.

What the portal does, in the API and MCP

Everything you can do in the portal has a route and an MCP tool:

Portal	REST	MCP tool
Create a group	`POST /groups`	`create_group`
See a group (where pricing stands, its latest quote and any move-forward request), list groups	`GET /groups/{groupId}`, `GET /groups`	`get_group`, `list_groups`
Edit a group’s details and plan design	`PATCH /groups/{groupId}`	`update_group`
New quote from a census (also saves a one-off quote to a group, found or created from the company)	`POST /quotes`	`quote_group`
Quote a group again or for the first time	`POST /groups/{groupId}/quotes`	`get_quote`
See a group’s quotes	`GET /groups/{groupId}/quotes`, `GET /groups/{groupId}/quotes/{quoteId}`	`list_quotes`, `get_quote` (with `quote_id` for one)
View a group’s census	`GET /groups/{groupId}/census`	`get_census`
Edit the census	`PUT /groups/{groupId}/census/members`, `PUT /groups/{groupId}/census`	`edit_census`
Client wants to move forward	`POST /groups/{groupId}/move-forward`	`move_forward`
Plan descriptions and benefits	`GET /plans`, `GET /plans/{planId}`	`get_plan_details`

The client proposal is a PDF and an Excel file. The Excel file has one tab, Comparison.

Quote in Slack

Company ZIPs may use five digits or ZIP+4; we use the first five digits for rating. If Prescience has linked a Slack channel to your account, drop a census CSV in it to quote without the API or the portal. Mentioning @Prescience is optional. Export Excel or Google Sheets as CSV first (maximum 5 MB); spreadsheet files, images and PDF censuses are not parsed. Company details can be on one line. The CSV still needs one person per row, with each employee followed by their dependents. Common census layouts work: column names like first_name, zip or postal_code, gender and dob, dates like 6/19/01, and relationship words like domestic_partner. If a row can’t be read, the bot lists what to fix. You don’t need a special format for the company details. Add the company name, domain and HQ ZIP anywhere in the message, in any form, for example Acme Co, acme.com, 94110, or leave them out. The bot works out what it can:

the domain from the file name, for example acme.com-census.csv
the company name from the domain
the ZIP as the most common employee ZIP in the census

It says what it assumed, and asks in the thread only for what it can’t work out. You can also add the current carrier and renewal price per employee per month, for example carrier Aetna, renewal $850. The bot replies in the thread. It says it is pricing, then posts Prescience Diamond and Prescience Value (monthly price, price per person per month, deductible, out-of-pocket max, and what your company pays if every employee gets reaches the quoted out-of-pocket maximum, a modeled scenario), attaches the proposal as Excel (one tab, Comparison) and PDF, and links the group in the portal. It also includes all five shareable materials, with interactive pages and PDFs that employers and employees can open without signing in. Pricing can take minutes; the quote is posted when it is ready. Reply in the thread with:

Reply	What happens
`requote`	Prices the group again. Put `requote` on the first line and changes below it, for example `renewal: $900`.
`move forward`	Tells Prescience your client wants to move forward, as `POST /groups/{groupId}/move-forward` does. Prescience then sets up enrollment by hand. This command does not enroll anyone.
`email`	Drafts a client email in the thread, including material links. This command does not send email.
`playbook`	Posts the talk track, with a link to the full sales playbook.
`help`	Shows supported input formats, examples and commands.

The group is matched as POST /quotes matches it, by domain since the message has no external ID, and an enrolled group is never matched. Asking again for the same group, census and pricing run returns the quote already made. Quotes from Slack are made in production when your account has production access, and in the sandbox otherwise.

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

When pricing takes longer

Reading a quote

Only Prescience’s plans come back

Choose how much comes back

Plan details

Plan design and moving forward

Edit the census

Reading a group

What the portal does, in the API and MCP

Quote in Slack

Which clients fit

​Send a census

​When pricing takes longer

​Reading a quote

​Share quote materials

​Only Prescience’s plans come back

​Choose how much comes back

​Plan details

​Plan design and moving forward

​Edit the census

​Reading a group

​What the portal does, in the API and MCP

​Quote in Slack

​Which clients fit

Send a census

When pricing takes longer

Reading a quote

Share quote materials

Only Prescience’s plans come back

Choose how much comes back

Plan details

Plan design and moving forward

Edit the census

Reading a group

What the portal does, in the API and MCP

Quote in Slack

Which clients fit