Quickstart

This walkthrough takes a test key from first ping to an enrolled employer: ping → create group → upload census → quote → enroll → read the account. Every request is copy-pasteable. Response examples show the stable shape; market prices and plan identifiers vary by census, location, and sweep date.

You need a test API key (psk_test_...). Ask your Prescience partner engineer to invite you to the Partner API key portal at internal.getprescience.com, then mint a sandbox key there and open Step 2 · Test integration. Sandbox keys remain viewable and copyable in the scoped portal. Email partners@getprescience.com if you need help getting access.

Check your key

Export your key and hit /ping. It confirms the key is valid and tells you which mode you’re in.

export PRESCIENCE_API_KEY="psk_test_..."

curl https://www.getprescience.com/api/partner/v1/ping \
  -H "Authorization: Bearer $PRESCIENCE_API_KEY"

const BASE = "https://www.getprescience.com/api/partner/v1";
const headers = {
  Authorization: `Bearer ${process.env.PRESCIENCE_API_KEY}`,
  "Content-Type": "application/json",
};

const ping = await fetch(`${BASE}/ping`, { headers }).then((r) => r.json());
console.log(ping);

import os
import requests

BASE = "https://www.getprescience.com/api/partner/v1"
session = requests.Session()
session.headers.update({
    "Authorization": f"Bearer {os.environ['PRESCIENCE_API_KEY']}",
    "Content-Type": "application/json",
})

print(session.get(f"{BASE}/ping").json())

Response

{
  "ok": true,
  "partner": { "id": "prt_7f3e9a2c54d1", "name": "Example HR" },
  "mode": "test"
}

Create a group

A group is one employer. Creating it requires exactly four values: companyName, domain, contact.name, and contact.email. A first-time employer does not need prior coverage or prior PEPM data.

curl -X POST https://www.getprescience.com/api/partner/v1/groups \
  -H "Authorization: Bearer $PRESCIENCE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-acme-group-1" \
  -d '{
    "companyName": "Acme Inc",
    "domain": "acme.com",
    "contact": { "name": "Dana Park", "email": "dana@acme.com" }
  }'

const group = await fetch(`${BASE}/groups`, {
  method: "POST",
  headers: { ...headers, "Idempotency-Key": "create-acme-group-1" },
  body: JSON.stringify({
    companyName: "Acme Inc",
    domain: "acme.com",
    contact: { name: "Dana Park", email: "dana@acme.com" },
  }),
}).then((r) => r.json());

console.log(group.id); // grp_8c2f41d09a3e

group = session.post(
    f"{BASE}/groups",
    headers={"Idempotency-Key": "create-acme-group-1"},
    json={
        "companyName": "Acme Inc",
        "domain": "acme.com",
        "contact": {"name": "Dana Park", "email": "dana@acme.com"},
    },
).json()

print(group["id"])  # grp_8c2f41d09a3e

Response (201)

{
  "id": "grp_8c2f41d09a3e",
  "mode": "test",
  "status": "created",
  "companyName": "Acme Inc",
  "domain": "acme.com",
  "contact": { "name": "Dana Park", "email": "dana@acme.com" },
  "censusMemberCount": 0,
  "companyState": null,
  "createdAt": "2026-06-10T17:04:11Z",
  "updatedAt": "2026-06-10T17:04:11Z"
}

Upload the census

PUT /census replaces the full census. To quote, each member only needs a zip and one of dob | age. You almost certainly have both already. Names and emails are required later, at enrollment.This is Acme’s real census: 12 employees, 19 covered lives.

curl -X PUT https://www.getprescience.com/api/partner/v1/groups/grp_8c2f41d09a3e/census \
  -H "Authorization: Bearer $PRESCIENCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "members": [
      { "externalId": "emp_0001", "firstName": "Jordan", "lastName": "Reyes", "email": "jordan@acme.com", "dob": "1992-03-14", "zip": "94110", "employmentType": "full_time", "hireDate": "2024-03-01" },
      { "externalId": "emp_0002", "firstName": "Priya", "lastName": "Natarajan", "email": "priya@acme.com", "dob": "1997-06-21", "zip": "94110", "employmentType": "full_time", "hireDate": "2025-01-20" },
      { "externalId": "emp_0003", "firstName": "Sam", "lastName": "Whitfield", "email": "sam@acme.com", "dob": "1985-01-30", "zip": "94110", "employmentType": "full_time", "hireDate": "2022-08-15" },
      { "externalId": "emp_0004", "firstName": "Elena", "lastName": "Sokolov", "email": "elena@acme.com", "dob": "1998-11-08", "zip": "94110", "employmentType": "full_time", "hireDate": "2025-06-02" },
      { "externalId": "emp_0005", "firstName": "Marcus", "lastName": "Tran", "email": "marcus@acme.com", "dob": "1988-05-17", "zip": "94110", "employmentType": "full_time", "hireDate": "2023-02-27" },
      { "externalId": "emp_0006", "firstName": "Aiko", "lastName": "Tanaka", "email": "aiko@acme.com", "dob": "2001-02-09", "zip": "94110", "employmentType": "full_time", "hireDate": "2025-09-08" },
      { "externalId": "emp_0007", "firstName": "Dev", "lastName": "Sharma", "email": "dev@acme.com", "dob": "1995-04-26", "zip": "94110", "employmentType": "full_time", "hireDate": "2024-11-11" },
      { "externalId": "emp_0008", "firstName": "Grace", "lastName": "Okafor", "email": "grace@acme.com", "dob": "1990-07-03", "zip": "94110", "employmentType": "full_time", "hireDate": "2023-07-15",
        "dependents": [ { "relationship": "spouse", "dob": "1989-08-12", "name": "Femi Okafor" } ] },
      { "externalId": "emp_0009", "firstName": "Tom", "lastName": "Becker", "email": "tom@acme.com", "dob": "1974-02-27", "zip": "94110", "employmentType": "full_time", "hireDate": "2022-01-10",
        "dependents": [ { "relationship": "spouse", "dob": "1976-05-19", "name": "Anja Becker" } ] },
      { "externalId": "emp_0010", "firstName": "Lena", "lastName": "Fischer", "email": "lena@acme.com", "dob": "1993-01-15", "zip": "94110", "employmentType": "full_time", "hireDate": "2024-09-30",
        "dependents": [ { "relationship": "child", "dob": "2019-10-02", "name": "Mia Fischer" } ] },
      { "externalId": "emp_0011", "firstName": "Noah", "lastName": "Kim", "email": "noah@acme.com", "dob": "1982-06-30", "zip": "94110", "employmentType": "full_time", "hireDate": "2022-05-23",
        "dependents": [ { "relationship": "spouse", "dob": "1983-04-11", "name": "Sarah Kim" }, { "relationship": "child", "dob": "2015-09-21", "name": "Eli Kim" } ] },
      { "externalId": "emp_0012", "firstName": "Rachel", "lastName": "Adler", "email": "rachel@acme.com", "dob": "1987-03-08", "zip": "94110", "employmentType": "full_time", "hireDate": "2023-10-02",
        "dependents": [ { "relationship": "spouse", "dob": "1986-07-22", "name": "Ben Adler" }, { "relationship": "child", "dob": "2018-12-05", "name": "Maya Adler" } ] }
    ]
  }'

// Map straight from the employee records you already store.
const members = [/* the same 12 members as the curl tab */];

const census = await fetch(`${BASE}/groups/${group.id}/census`, {
  method: "PUT",
  headers,
  body: JSON.stringify({ members }),
}).then((r) => r.json());

console.log(census); // { received: 12, accepted: 12, ... }

# Map straight from the employee records you already store.
members = [...]  # the same 12 members as the curl tab

census = session.put(f"{BASE}/groups/{group['id']}/census", json={"members": members}).json()
print(census)  # { "received": 12, "accepted": 12, ... }

Response (200)

{
  "groupId": "grp_8c2f41d09a3e",
  "received": 12,
  "accepted": 12,
  "memberCount": 12,
  "errors": [],
  "warnings": []
}

Bad rows never block good ones: they come back in errors with the row index while everything else is stored. Details in the census guide.

Create the quote

One POST with an empty body returns the full quote after Prescience has the group’s market-rate snapshot. The plan year start defaults to the first of the month at least 60 days out.Immediately after a census update, this request can return 409 rates_pending while Prescience compares local plans. Retry with backoff, or use the Bolto iframe. In that flow, Bolto makes a separate POST /groups/{groupId}/embed-sessions call when the employer opens the offer; the iframe shows real progress and creates its plan model when the sweep completes.

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 '{}'

const quote = await fetch(`${BASE}/groups/${group.id}/quotes`, {
  method: "POST",
  headers,
  body: JSON.stringify({}),
}).then((r) => r.json());

console.log(quote.monthly.totalCents);

quote = session.post(f"{BASE}/groups/{group['id']}/quotes", json={}).json()
print(quote["monthly"]["totalCents"])

Response (201)

{
  "id": "qt_5b9e2c7f10ad",
  "groupId": "grp_8c2f41d09a3e",
  "mode": "test",
  "status": "ready",
  "pricingBasis": "market_rates",
  "plan": { "id": "diamond", "name": "Prescience Diamond" },
  "planYearStartDate": "2026-09-01",
  "expiresAt": "2026-07-10T17:22:05Z",
  "census": {
    "employees": 12,
    "coveredLives": 19,
    "tiers": {
      "employeeOnly": 7,
      "employeeSpouse": 2,
      "employeeChildren": 1,
      "family": 2
    }
  },
  "monthly": {
    "totalCents": 660096,
    "pepmCents": 55008,
    "byTier": {
      "employeeOnly": { "count": 7, "avgCents": 0 },
      "employeeSpouse": { "count": 2, "avgCents": 0 },
      "employeeChildren": { "count": 1, "avgCents": 0 },
      "family": { "count": 2, "avgCents": 0 }
    }
  },
  "annual": { "totalCents": 7921152 },
  "employeeContribution": { "premiumCents": 0 },
  "comparison": {
    "priorPepmCents": 0,
    "savingsMonthlyCents": 299904,
    "savingsAnnualCents": 3598848,
    "savingsPct": 31
  },
  "fundingBreakdown": {
    "expectedClaimsPct": 78,
    "stopLossPct": 12,
    "careNavigationPct": 10,
    "adminFeesPct": 0,
    "note": "Illustrative split of the premium-equivalent."
  },
  "assumptions": [
    "Dependent elections were not supplied, so this preliminary model uses a normalized small-group household mix."
  ],
  "pricing": { "source": "code_default" },
  "createdAt": "2026-06-10T17:22:05Z"
}

Read it like this: monthly.totalCents is the modeled all-in monthly amount, monthly.pepmCents is the per-covered-life monthly amount, and comparison measures Prescience against the selected platinum market benchmark. Field-by-field details are in the quotes guide.

Quotes are preliminary. Final pricing, eligibility, and plan documents are confirmed during underwriting and onboarding. Say so wherever you display them.

Enroll the employer

When the employer accepts the quote, create the enrollment. The signatory is the employer admin who made the selection; Prescience provisions them as the company’s admin in the Prescience employer portal and runs onboarding there (the default onboardingMode: "hosted"; see the enrollment guide).

curl -X POST https://www.getprescience.com/api/partner/v1/groups/grp_8c2f41d09a3e/enrollments \
  -H "Authorization: Bearer $PRESCIENCE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: enroll-acme-1" \
  -d '{
    "quoteId": "qt_5b9e2c7f10ad",
    "signatory": { "name": "Dana Park", "email": "dana@acme.com", "title": "Head of People" }
  }'

const enrollment = await fetch(`${BASE}/groups/${group.id}/enrollments`, {
  method: "POST",
  headers: { ...headers, "Idempotency-Key": "enroll-acme-1" },
  body: JSON.stringify({
    quoteId: quote.id,
    signatory: {
      name: "Dana Park",
      email: "dana@acme.com",
      title: "Head of People",
    },
  }),
}).then((r) => r.json());

console.log(enrollment.status); // "onboarding"

enrollment = session.post(
    f"{BASE}/groups/{group['id']}/enrollments",
    headers={"Idempotency-Key": "enroll-acme-1"},
    json={
        "quoteId": quote["id"],
        "signatory": {"name": "Dana Park", "email": "dana@acme.com", "title": "Head of People"},
    },
).json()
print(enrollment["status"])  # "onboarding"

Response (201)

{
  "id": "enr_3f7a92c81b40",
  "groupId": "grp_8c2f41d09a3e",
  "mode": "test",
  "status": "onboarding",
  "quoteId": "qt_5b9e2c7f10ad",
  "startDate": "2026-09-01",
  "companyDomain": "acme.com",
  "companyState": "sandbox",
  "onboardingMode": "hosted",
  "employerPortal": {
    "provisioned": true,
    "signinUrl": "https://www.getprescience.com/signin",
    "inviteSuppressed": true
  },
  "onboarding": { "percentComplete": 0, "blockingRemaining": 0 },
  "nextSteps": [
    "Prescience onboarding call scheduled with the employer",
    "Employer completes KYB + plan setup in the Prescience portal",
    "Prescience activates the group (state → prod)"
  ],
  "createdAt": "2026-06-12T09:14:32Z"
}

From here, Prescience runs onboarding, KYB, banking, and plan setup with the employer directly in the Prescience employer portal, then activation (sandbox → prod). No code on your side; poll GET /enrollments/{enrollmentId} or listen for webhooks. employerPortal confirms the signatory’s portal account: this is a test-mode key, so the normal portal and member invitations are suppressed. The iframe’s employer verification code is the only sandbox email. The sandbox company is fully functional but flagged test: true and never activated; no money moves.

Read the account

Once enrolled, GET /account returns funding, premium-equivalent totals, spend by category, and savings, all aggregate and de-identified.

curl https://www.getprescience.com/api/partner/v1/groups/grp_8c2f41d09a3e/account \
  -H "Authorization: Bearer $PRESCIENCE_API_KEY"

const account = await fetch(`${BASE}/groups/${group.id}/account`, {
  headers,
}).then((r) => r.json());
console.log(account.company.state); // "sandbox" now, "prod" after activation

account = session.get(f"{BASE}/groups/{group['id']}/account").json()
print(account["company"]["state"])  # "sandbox" now, "prod" after activation

The benefits tab guide maps every field to a UI element, with the full in-force payload for this group.

Where to next

Read plan metadata

Static plan fields plus group-specific quote pricing.

Set up webhooks

Signed events for enrollment, activation, and finalized quotes.

Sync your census

New hires, terminations, and COBRA: one call each.

Go live

BAA, data handling, and what changes between test and live.

Get Started

Guides

Resources

Where to next

Read plan metadata

Set up webhooks

Sync your census

Go live

​Where to next

Read plan metadata

Set up webhooks

Sync your census

Go live

Where to next