Pass a census, get a quote

curl --request POST \
  --url https://www.getprescience.com/api/partner/v1/quotes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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"
    }
  ]
}
'

import requests

url = "https://www.getprescience.com/api/partner/v1/quotes"

payload = {
    "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"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'
      }
    ]
  })
};

fetch('https://www.getprescience.com/api/partner/v1/quotes', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://www.getprescience.com/api/partner/v1/quotes",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://www.getprescience.com/api/partner/v1/quotes"

	payload := strings.NewReader("{\n  \"company\": {\n    \"name\": \"Northwind Dental\",\n    \"domain\": \"northwinddental.com\",\n    \"externalId\": \"crd_4821\",\n    \"zip\": \"94110\",\n    \"state\": \"CA\"\n  },\n  \"census\": [\n    {\n      \"externalId\": \"emp_0001\",\n      \"firstName\": \"Ada\",\n      \"lastName\": \"Reyes\",\n      \"email\": \"ada@northwinddental.com\",\n      \"dob\": \"1991-04-02\",\n      \"zip\": \"94110\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://www.getprescience.com/api/partner/v1/quotes")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"company\": {\n    \"name\": \"Northwind Dental\",\n    \"domain\": \"northwinddental.com\",\n    \"externalId\": \"crd_4821\",\n    \"zip\": \"94110\",\n    \"state\": \"CA\"\n  },\n  \"census\": [\n    {\n      \"externalId\": \"emp_0001\",\n      \"firstName\": \"Ada\",\n      \"lastName\": \"Reyes\",\n      \"email\": \"ada@northwinddental.com\",\n      \"dob\": \"1991-04-02\",\n      \"zip\": \"94110\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://www.getprescience.com/api/partner/v1/quotes")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"company\": {\n    \"name\": \"Northwind Dental\",\n    \"domain\": \"northwinddental.com\",\n    \"externalId\": \"crd_4821\",\n    \"zip\": \"94110\",\n    \"state\": \"CA\"\n  },\n  \"census\": [\n    {\n      \"externalId\": \"emp_0001\",\n      \"firstName\": \"Ada\",\n      \"lastName\": \"Reyes\",\n      \"email\": \"ada@northwinddental.com\",\n      \"dob\": \"1991-04-02\",\n      \"zip\": \"94110\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "id": "qt_5b9e2c7f10ad",
  "groupId": "grp_8c2f41d09a3e",
  "mode": "test",
  "status": "ready",
  "pricingBasis": "market_rates",
  "plan": {
    "id": "diamond",
    "name": "Prescience Diamond"
  },
  "planYearStartDate": "2026-09-01",
  "expiresAt": "2023-11-07T05:31:56Z",
  "census": {
    "employees": 12,
    "coveredLives": 19,
    "tiers": {
      "employeeOnly": 123,
      "employeeSpouse": 123,
      "employeeChildren": 123,
      "family": 123
    }
  },
  "monthly": {
    "totalCents": 816000,
    "pepmCents": 68000,
    "pmpmCents": 42947,
    "byTier": {
      "employeeOnly": {
        "count": 123,
        "avgCents": 123
      },
      "employeeSpouse": {
        "count": 123,
        "avgCents": 123
      },
      "employeeChildren": {
        "count": 123,
        "avgCents": 123
      },
      "family": {
        "count": 123,
        "avgCents": 123
      }
    }
  },
  "annual": {
    "totalCents": 9792000
  },
  "employeeContribution": {
    "premiumCents": null,
    "employerContributionRange": {
      "minPct": 50,
      "maxPct": 100
    }
  },
  "comparison": {
    "priorPepmCents": 0,
    "savingsMonthlyCents": 144000,
    "savingsAnnualCents": 1728000,
    "savingsPct": 15
  },
  "assumptions": [
    "<string>"
  ],
  "createdAt": "2023-11-07T05:31:56Z",
  "ignoredPlans": [
    {
      "index": 123,
      "reason": "metalTier: metalTier is required (for example Platinum, Gold, Silver, Bronze).",
      "carrier": "<string>",
      "planName": "<string>"
    }
  ],
  "usedPlans": {
    "sent": 123,
    "used": 123,
    "baseCandidates": 123,
    "benchmarkCandidates": 123
  },
  "pricedOn": "census_only",
  "plans": [
    {
      "id": "diamond",
      "name": "Prescience Diamond",
      "description": "<string>",
      "status": "ready",
      "pricing_method": "engine",
      "reason": "<string>",
      "monthly": {
        "totalCents": 123,
        "pepmCents": 123,
        "pmpmCents": 123
      },
      "annual": {
        "totalCents": 123
      },
      "pricedAgainst": {
        "carrier": "<string>",
        "planName": "<string>",
        "metalTier": "<string>",
        "source": "broker",
        "label": "<string>"
      },
      "benchmarkPlan": {
        "carrier": "<string>",
        "planName": "<string>",
        "metalTier": "<string>",
        "network": "<string>"
      },
      "underlyingPlan": {
        "carrier": "<string>",
        "planName": "<string>",
        "network": "<string>",
        "source": "broker",
        "fundingType": "<string>",
        "brokerPlan": {
          "carrier": "Example Carrier",
          "planName": "Gold PPO 1500",
          "planType": "PPO",
          "hsaEligible": true,
          "deductibleIndividualCents": 123,
          "deductibleFamilyCents": 123,
          "oopMaxIndividualCents": 123,
          "oopMaxFamilyCents": 123,
          "metalTier": "Gold",
          "network": "<string>",
          "fundingType": "fully_insured",
          "monthlyRatesCents": {
            "employeeOnly": 123,
            "employeeSpouse": 123,
            "employeeChildren": 123,
            "family": 123,
            "pmpmCents": 123,
            "memberRatesCents": [
              {
                "externalId": "<string>",
                "monthlyCents": 123
              }
            ],
            "carrierPlanId": "<string>",
            "effectiveDate": "2023-12-25",
            "ratingZip": "<string>",
            "embeddedDeductible": true,
            "coinsurancePct": 123,
            "copaysCents": {
              "primaryCare": 123,
              "specialist": 123,
              "urgentCare": 123,
              "emergencyRoom": 123,
              "rxGeneric": 123,
              "rxPreferred": 123,
              "rxSpecialty": 123
            },
            "rxDeductibleCents": 123,
            "referralRequired": true,
            "hsaDeductibleRequired": {},
            "sbcUrl": "<string>",
            "doctorSearchUrl": "<string>",
            "carrierLogoUrl": "<string>"
          },
          "pmpmCents": 123,
          "memberRatesCents": [
            {
              "externalId": "<string>",
              "monthlyCents": 123
            }
          ],
          "carrierPlanId": "<string>",
          "effectiveDate": "2023-12-25",
          "ratingZip": "<string>",
          "embeddedDeductible": true,
          "coinsurancePct": 50,
          "copaysCents": {
            "primaryCare": 123,
            "specialist": 123,
            "urgentCare": 123,
            "emergencyRoom": 123,
            "rxGeneric": 123,
            "rxPreferred": 123,
            "rxSpecialty": 123
          },
          "rxDeductibleCents": 123,
          "referralRequired": true,
          "hsaDeductibleRequired": {},
          "sbcUrl": "<string>",
          "doctorSearchUrl": "<string>",
          "carrierLogoUrl": "<string>"
        },
        "note": "<string>"
      },
      "benefits": {
        "oopMaxIndividualCents": 123,
        "oopMaxEmployeePlusOneCents": 123,
        "oopMaxFamilyCents": 123,
        "memberCoinsurancePct": 123,
        "hsaEligible": true,
        "network": "<string>",
        "features": [
          {
            "title": "<string>",
            "description": "<string>"
          }
        ]
      },
      "price_components": {
        "underlying_premium_monthly_cents": 123,
        "prescience_monthly_cents": 123,
        "total_monthly_cents": 123,
        "underlying_pmpm_cents": 123,
        "prescience_pmpm_cents": 123,
        "total_pmpm_cents": 123
      },
      "worst_year": {
        "modeled_extra_cents": 123,
        "modeled_total_cents": 123,
        "benchmark_premium_cents": 123,
        "headroom_cents": 123,
        "basis": "<string>",
        "contractual": null,
        "note": "<string>",
        "recompute": {
          "underlying_annual_premium_cents": 123,
          "theoretical_exposure_cents": 123,
          "member_oop_allowance_cents": 123
        }
      },
      "base_plan": {
        "carrier": "<string>",
        "plan_name": "<string>",
        "deductible_individual_cents": 123,
        "deductible_family_cents": 123,
        "label": "HSA-qualified base plan deductible"
      },
      "member_oop_max": {
        "individual_cents": 123,
        "family_cents": 123
      },
      "benchmark_rank": "<string>",
      "rate_basis": {
        "base_plan": "member_rates",
        "benchmark": "member_rates"
      },
      "monthly_rates_by_household": [
        {
          "label": "Employee + 1",
          "people": 123,
          "households": 123,
          "monthly_cents": 123
        }
      ],
      "new_member_rates_by_household": [
        {
          "label": "<string>",
          "people": 123,
          "monthly_cents": 123
        }
      ],
      "all_max_year": {
        "base_premium_cents": 123,
        "prescience_cents": 123,
        "modeled_extra_cents": 123,
        "employer_total_cents": 123,
        "members_pay_cents": 123
      },
      "median_year": {
        "employer_total_cents": 123,
        "pool_pays_cents": 123,
        "members_pay_cents": 123
      },
      "time_machine": {
        "simulated_plan_years": 123,
        "census_members": 123,
        "generated_at": "2023-11-07T05:31:56Z"
      },
      "hsa": {
        "eligible": true,
        "basis": "<string>"
      },
      "renewal": {
        "method": null,
        "note": "<string>"
      },
      "member_experience": {},
      "fit_flags": [
        "<string>"
      ],
      "comparison": {
        "benchmark": {
          "carrier": "<string>",
          "planName": "<string>",
          "metalTier": "<string>",
          "annualCents": 123,
          "deductibleIndividualCents": 123,
          "oopMaxIndividualCents": 123,
          "oopMaxFamilyCents": 123,
          "hsaEligible": true
        },
        "annualSavingsCents": 123,
        "savingsPct": 123,
        "worstYearUnderBenchmarkCents": 123,
        "oopMaxIndividualLowerByCents": 123,
        "oopMaxFamilyLowerByCents": 123,
        "hsaEligibleWhereBenchmarkIsNot": true
      },
      "broker_row": "<string>",
      "summary": "<string>"
    }
  ],
  "reserve": {
    "annualCents": 2639434
  },
  "benefits": {
    "deductibleIndividualCents": 0,
    "deductibleFamilyCents": 0,
    "oopMaxIndividualCents": 323942,
    "oopMaxEmployeePlusOneCents": 810823,
    "oopMaxFamilyCents": 810823,
    "memberCoinsurancePct": 0
  },
  "benchmarkPlan": {
    "carrier": "UnitedHealthcare",
    "planName": "EP2D/P56S",
    "metalTier": "platinum",
    "network": "SelectPlus PPO"
  },
  "pricing": {
    "source": "code_default",
    "updatedAt": "2023-11-07T05:31:56Z"
  }
}

{
  "groupId": "grp_8c2f41d09a3e",
  "status": "pricing",
  "retryAfterSeconds": 20,
  "sweep": {
    "step": "collect",
    "planCount": 42
  }
}

{
  "error": "invalid_request",
  "message": "Quote request failed validation.",
  "details": [
    {
      "field": "company.zip",
      "message": "company.zip must be a 5-digit ZIP."
    }
  ]
}

{
  "error": "unauthorized",
  "message": "Provide a valid partner API key as `Authorization: Bearer psk_...`."
}

{
  "error": "live_mode_disabled",
  "message": "Live mode is not enabled for this account yet. Complete the go-live checklist to enable live keys."
}

{
  "error": "conflict",
  "message": "This group is already enrolled; its census can't be replaced here."
}

{
  "error": "market_unavailable",
  "message": "Prescience couldn't price this group from its market. Prescience reviews it; retrying won't change the result."
}

{
  "error": "rate_limited",
  "message": "Too many requests. Please retry later."
}

Quotes

Pass a census, get a quote

Finds or creates the group for the company (by company.externalId, else company.domain), replaces its census, saves the plans the broker brings (basePlan, marketPlans), and quotes. Returns 201 with the quote and its Diamond rows when rates are ready, or 202 while the market comparison runs (with marketPlans the request waits for pricing, which takes seconds, so 201 is the usual answer): send the same body again, poll POST /groups/{groupId}/quotes, or wait for the group.market_rates_ready webhook. 422 market_unavailable means Prescience couldn’t price the group and retrying won’t change the result; its message gives the reason for each version, such as “No HSA-eligible PPO, EPO or POS plan in the plans sent.” or “No platinum PPO in the plans sent.” Plans we can’t build on are ignored and listed in ignoredPlans, never rejected. Needs the quote capability, which broker keys have by default; an HR-platform key returns 403 forbidden. Rate limit: 60 quote creates per hour.

POST

quotes

curl --request POST \
  --url https://www.getprescience.com/api/partner/v1/quotes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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"
    }
  ]
}
'

import requests

url = "https://www.getprescience.com/api/partner/v1/quotes"

payload = {
    "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"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'
      }
    ]
  })
};

fetch('https://www.getprescience.com/api/partner/v1/quotes', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://www.getprescience.com/api/partner/v1/quotes",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://www.getprescience.com/api/partner/v1/quotes"

	payload := strings.NewReader("{\n  \"company\": {\n    \"name\": \"Northwind Dental\",\n    \"domain\": \"northwinddental.com\",\n    \"externalId\": \"crd_4821\",\n    \"zip\": \"94110\",\n    \"state\": \"CA\"\n  },\n  \"census\": [\n    {\n      \"externalId\": \"emp_0001\",\n      \"firstName\": \"Ada\",\n      \"lastName\": \"Reyes\",\n      \"email\": \"ada@northwinddental.com\",\n      \"dob\": \"1991-04-02\",\n      \"zip\": \"94110\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://www.getprescience.com/api/partner/v1/quotes")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"company\": {\n    \"name\": \"Northwind Dental\",\n    \"domain\": \"northwinddental.com\",\n    \"externalId\": \"crd_4821\",\n    \"zip\": \"94110\",\n    \"state\": \"CA\"\n  },\n  \"census\": [\n    {\n      \"externalId\": \"emp_0001\",\n      \"firstName\": \"Ada\",\n      \"lastName\": \"Reyes\",\n      \"email\": \"ada@northwinddental.com\",\n      \"dob\": \"1991-04-02\",\n      \"zip\": \"94110\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://www.getprescience.com/api/partner/v1/quotes")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"company\": {\n    \"name\": \"Northwind Dental\",\n    \"domain\": \"northwinddental.com\",\n    \"externalId\": \"crd_4821\",\n    \"zip\": \"94110\",\n    \"state\": \"CA\"\n  },\n  \"census\": [\n    {\n      \"externalId\": \"emp_0001\",\n      \"firstName\": \"Ada\",\n      \"lastName\": \"Reyes\",\n      \"email\": \"ada@northwinddental.com\",\n      \"dob\": \"1991-04-02\",\n      \"zip\": \"94110\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "id": "qt_5b9e2c7f10ad",
  "groupId": "grp_8c2f41d09a3e",
  "mode": "test",
  "status": "ready",
  "pricingBasis": "market_rates",
  "plan": {
    "id": "diamond",
    "name": "Prescience Diamond"
  },
  "planYearStartDate": "2026-09-01",
  "expiresAt": "2023-11-07T05:31:56Z",
  "census": {
    "employees": 12,
    "coveredLives": 19,
    "tiers": {
      "employeeOnly": 123,
      "employeeSpouse": 123,
      "employeeChildren": 123,
      "family": 123
    }
  },
  "monthly": {
    "totalCents": 816000,
    "pepmCents": 68000,
    "pmpmCents": 42947,
    "byTier": {
      "employeeOnly": {
        "count": 123,
        "avgCents": 123
      },
      "employeeSpouse": {
        "count": 123,
        "avgCents": 123
      },
      "employeeChildren": {
        "count": 123,
        "avgCents": 123
      },
      "family": {
        "count": 123,
        "avgCents": 123
      }
    }
  },
  "annual": {
    "totalCents": 9792000
  },
  "employeeContribution": {
    "premiumCents": null,
    "employerContributionRange": {
      "minPct": 50,
      "maxPct": 100
    }
  },
  "comparison": {
    "priorPepmCents": 0,
    "savingsMonthlyCents": 144000,
    "savingsAnnualCents": 1728000,
    "savingsPct": 15
  },
  "assumptions": [
    "<string>"
  ],
  "createdAt": "2023-11-07T05:31:56Z",
  "ignoredPlans": [
    {
      "index": 123,
      "reason": "metalTier: metalTier is required (for example Platinum, Gold, Silver, Bronze).",
      "carrier": "<string>",
      "planName": "<string>"
    }
  ],
  "usedPlans": {
    "sent": 123,
    "used": 123,
    "baseCandidates": 123,
    "benchmarkCandidates": 123
  },
  "pricedOn": "census_only",
  "plans": [
    {
      "id": "diamond",
      "name": "Prescience Diamond",
      "description": "<string>",
      "status": "ready",
      "pricing_method": "engine",
      "reason": "<string>",
      "monthly": {
        "totalCents": 123,
        "pepmCents": 123,
        "pmpmCents": 123
      },
      "annual": {
        "totalCents": 123
      },
      "pricedAgainst": {
        "carrier": "<string>",
        "planName": "<string>",
        "metalTier": "<string>",
        "source": "broker",
        "label": "<string>"
      },
      "benchmarkPlan": {
        "carrier": "<string>",
        "planName": "<string>",
        "metalTier": "<string>",
        "network": "<string>"
      },
      "underlyingPlan": {
        "carrier": "<string>",
        "planName": "<string>",
        "network": "<string>",
        "source": "broker",
        "fundingType": "<string>",
        "brokerPlan": {
          "carrier": "Example Carrier",
          "planName": "Gold PPO 1500",
          "planType": "PPO",
          "hsaEligible": true,
          "deductibleIndividualCents": 123,
          "deductibleFamilyCents": 123,
          "oopMaxIndividualCents": 123,
          "oopMaxFamilyCents": 123,
          "metalTier": "Gold",
          "network": "<string>",
          "fundingType": "fully_insured",
          "monthlyRatesCents": {
            "employeeOnly": 123,
            "employeeSpouse": 123,
            "employeeChildren": 123,
            "family": 123,
            "pmpmCents": 123,
            "memberRatesCents": [
              {
                "externalId": "<string>",
                "monthlyCents": 123
              }
            ],
            "carrierPlanId": "<string>",
            "effectiveDate": "2023-12-25",
            "ratingZip": "<string>",
            "embeddedDeductible": true,
            "coinsurancePct": 123,
            "copaysCents": {
              "primaryCare": 123,
              "specialist": 123,
              "urgentCare": 123,
              "emergencyRoom": 123,
              "rxGeneric": 123,
              "rxPreferred": 123,
              "rxSpecialty": 123
            },
            "rxDeductibleCents": 123,
            "referralRequired": true,
            "hsaDeductibleRequired": {},
            "sbcUrl": "<string>",
            "doctorSearchUrl": "<string>",
            "carrierLogoUrl": "<string>"
          },
          "pmpmCents": 123,
          "memberRatesCents": [
            {
              "externalId": "<string>",
              "monthlyCents": 123
            }
          ],
          "carrierPlanId": "<string>",
          "effectiveDate": "2023-12-25",
          "ratingZip": "<string>",
          "embeddedDeductible": true,
          "coinsurancePct": 50,
          "copaysCents": {
            "primaryCare": 123,
            "specialist": 123,
            "urgentCare": 123,
            "emergencyRoom": 123,
            "rxGeneric": 123,
            "rxPreferred": 123,
            "rxSpecialty": 123
          },
          "rxDeductibleCents": 123,
          "referralRequired": true,
          "hsaDeductibleRequired": {},
          "sbcUrl": "<string>",
          "doctorSearchUrl": "<string>",
          "carrierLogoUrl": "<string>"
        },
        "note": "<string>"
      },
      "benefits": {
        "oopMaxIndividualCents": 123,
        "oopMaxEmployeePlusOneCents": 123,
        "oopMaxFamilyCents": 123,
        "memberCoinsurancePct": 123,
        "hsaEligible": true,
        "network": "<string>",
        "features": [
          {
            "title": "<string>",
            "description": "<string>"
          }
        ]
      },
      "price_components": {
        "underlying_premium_monthly_cents": 123,
        "prescience_monthly_cents": 123,
        "total_monthly_cents": 123,
        "underlying_pmpm_cents": 123,
        "prescience_pmpm_cents": 123,
        "total_pmpm_cents": 123
      },
      "worst_year": {
        "modeled_extra_cents": 123,
        "modeled_total_cents": 123,
        "benchmark_premium_cents": 123,
        "headroom_cents": 123,
        "basis": "<string>",
        "contractual": null,
        "note": "<string>",
        "recompute": {
          "underlying_annual_premium_cents": 123,
          "theoretical_exposure_cents": 123,
          "member_oop_allowance_cents": 123
        }
      },
      "base_plan": {
        "carrier": "<string>",
        "plan_name": "<string>",
        "deductible_individual_cents": 123,
        "deductible_family_cents": 123,
        "label": "HSA-qualified base plan deductible"
      },
      "member_oop_max": {
        "individual_cents": 123,
        "family_cents": 123
      },
      "benchmark_rank": "<string>",
      "rate_basis": {
        "base_plan": "member_rates",
        "benchmark": "member_rates"
      },
      "monthly_rates_by_household": [
        {
          "label": "Employee + 1",
          "people": 123,
          "households": 123,
          "monthly_cents": 123
        }
      ],
      "new_member_rates_by_household": [
        {
          "label": "<string>",
          "people": 123,
          "monthly_cents": 123
        }
      ],
      "all_max_year": {
        "base_premium_cents": 123,
        "prescience_cents": 123,
        "modeled_extra_cents": 123,
        "employer_total_cents": 123,
        "members_pay_cents": 123
      },
      "median_year": {
        "employer_total_cents": 123,
        "pool_pays_cents": 123,
        "members_pay_cents": 123
      },
      "time_machine": {
        "simulated_plan_years": 123,
        "census_members": 123,
        "generated_at": "2023-11-07T05:31:56Z"
      },
      "hsa": {
        "eligible": true,
        "basis": "<string>"
      },
      "renewal": {
        "method": null,
        "note": "<string>"
      },
      "member_experience": {},
      "fit_flags": [
        "<string>"
      ],
      "comparison": {
        "benchmark": {
          "carrier": "<string>",
          "planName": "<string>",
          "metalTier": "<string>",
          "annualCents": 123,
          "deductibleIndividualCents": 123,
          "oopMaxIndividualCents": 123,
          "oopMaxFamilyCents": 123,
          "hsaEligible": true
        },
        "annualSavingsCents": 123,
        "savingsPct": 123,
        "worstYearUnderBenchmarkCents": 123,
        "oopMaxIndividualLowerByCents": 123,
        "oopMaxFamilyLowerByCents": 123,
        "hsaEligibleWhereBenchmarkIsNot": true
      },
      "broker_row": "<string>",
      "summary": "<string>"
    }
  ],
  "reserve": {
    "annualCents": 2639434
  },
  "benefits": {
    "deductibleIndividualCents": 0,
    "deductibleFamilyCents": 0,
    "oopMaxIndividualCents": 323942,
    "oopMaxEmployeePlusOneCents": 810823,
    "oopMaxFamilyCents": 810823,
    "memberCoinsurancePct": 0
  },
  "benchmarkPlan": {
    "carrier": "UnitedHealthcare",
    "planName": "EP2D/P56S",
    "metalTier": "platinum",
    "network": "SelectPlus PPO"
  },
  "pricing": {
    "source": "code_default",
    "updatedAt": "2023-11-07T05:31:56Z"
  }
}

{
  "groupId": "grp_8c2f41d09a3e",
  "status": "pricing",
  "retryAfterSeconds": 20,
  "sweep": {
    "step": "collect",
    "planCount": 42
  }
}

{
  "error": "invalid_request",
  "message": "Quote request failed validation.",
  "details": [
    {
      "field": "company.zip",
      "message": "company.zip must be a 5-digit ZIP."
    }
  ]
}

{
  "error": "unauthorized",
  "message": "Provide a valid partner API key as `Authorization: Bearer psk_...`."
}

{
  "error": "live_mode_disabled",
  "message": "Live mode is not enabled for this account yet. Complete the go-live checklist to enable live keys."
}

{
  "error": "conflict",
  "message": "This group is already enrolled; its census can't be replaced here."
}

{
  "error": "market_unavailable",
  "message": "Prescience couldn't price this group from its market. Prescience reviews it; retrying won't change the result."
}

{
  "error": "rate_limited",
  "message": "Too many requests. Please retry later."
}

Authorizations

Authorization

string

header

required

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.

Headers

Idempotency-Key

string

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.

Body

application/json

company

object

required

Show child attributes

census

object[]

required

Members, as in PUT /groups/{groupId}/census.

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.

Option 1
Option 2

Show child attributes

planYearStartDate

string<date>

basePlan

object | null

The carrier plan Diamond sits on, for example a BCBS bronze HDHP or a level-funded catastrophic plan you placed. Prices are then set on it, which usually lowers the price. Without it a base plan is chosen from our market sweep. null clears it.

Show child attributes

marketPlans

object[] | null

Every plan you quoted for the census (all metals, any funding, any carrier; metalTier required). They replace our market sweep, so no marketplace is queried and pricing is fast: the request waits for it and returns 201 with the quote, or 202 if it takes longer. A plan missing a required field is dropped and reported in ignoredPlans. null clears the list.

Maximum array length: 500

Show child attributes

Response

The quote, with plans.

string

required

Example:

"qt_5b9e2c7f10ad"

groupId

string

required

Example:

"grp_8c2f41d09a3e"

mode

enum<string>

required

Available options:

test,

live

status

enum<string>

required

ready for most groups (synchronous). Groups above the in-review employee threshold (default 200) return in_review and are finalized by Prescience underwriting; listen for the quote.finalized webhook.

Available options:

ready,

in_review,

expired

pricingBasis

string

required

Current quotes use market_rates: priced once per census when the group's market comparison finishes, against the most expensive platinum PPO quoted for it (for a broker's group, a platinum PPO). Final pricing is confirmed during underwriting and onboarding.

Allowed value: "market_rates"

plan

object

required

Show child attributes

planYearStartDate

string<date>

required

Example:

"2026-09-01"

expiresAt

string<date-time>

required

Expiry is configuration-driven; the default window is 30 days after creation. Enrolling against an expired quote returns 410 quote_expired.

census

object

required

Show child attributes

monthly

object

required

Show child attributes

annual

object

required

Show child attributes

employeeContribution

object

required

What each employee pays depends on the share the employer chooses at setup, so a quote never states it.

Show child attributes

comparison

object

required

Show child attributes

assumptions

string[]

required

createdAt

string<date-time>

required

ignoredPlans

object[]

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.

Show child attributes

usedPlans

object

What was sent in marketPlans and what could be built on.

Show child attributes

pricedOn

enum<string>

What the quote was priced from: the census alone, your base plan (basePlan). market_plans means every plan you quoted (marketPlans) stood in for our market sweep.

Available options:

census_only,

base_plan,

market_plans

plans

object[]

The two computed versions of Prescience Diamond for this group, Diamond and Value. Absent on quotes created before plans existed.

Show child attributes

reserve

object

Disclosed, never included in the price: the most the employer could owe on top of the quote in a year where every member reaches the underlying plan's out-of-pocket maximum. Absent on quotes created before it.

Show child attributes

benefits

object

The group's Diamond design this price is for: what members pay. Use these, not /plans, for the group's deductible and out-of-pocket maximums. Absent on quotes created before it.

Show child attributes

benchmarkPlan

object | null

The plan the savings are measured against: the most expensive platinum PPO quoted for this census (for a broker's group, a platinum PPO). Absent on quotes created before it.

Show child attributes

pricing

object

Pricing metadata: which configuration layer produced this quote. Additive in v1.1; absent on quotes created before it. All other quote fields are unchanged.

Show child attributes

Overview

Endpoints

Pass a census, get a quote

Authorizations

Headers

Body

Response