Census

The census is the input to everything: quotes are rated from it, enrollments materialize it into the live plan, and ongoing syncs keep it true. It starts with your employee roster and may include the dependent elections your platform already has.

Send dependent elections when you have them. Submitted dependents drive covered lives and household tiers. If they are not available yet, Prescience uses a stable normalized small-group household mix and discloses that assumption in the preliminary quote. Final dependent eligibility is confirmed during onboarding.

PUT /groups/{groupId}/census replaces the whole census. Members are matched by externalId (your payroll’s employee ID) when present, otherwise by email, and matched members keep their memberId. An email that belongs to a member with a different externalId is a different person, so a new hire who reuses a former employee’s email never takes over their record. Re-pushing the same roster is safe and idempotent. Before enrollment, members you omit, or whose row is rejected, are removed from the census. After enrollment, leaving a member out never terminates them; send PATCH /members/{memberId} with status: "terminated" instead (see census sync). A census change that affects rating (ages, ZIPs, sex, households or waivers) starts a new market comparison. While it runs, POST /quotes returns 409 rates_pending. An unchanged census keeps its current price.

Member schema

{
  "externalId": "emp_0008",
  "firstName": "Grace",
  "lastName": "Okafor",
  "email": "grace@acme.com",
  "dob": "1990-07-03",
  "zip": "94110",
  "sexAtBirth": "female",
  "employmentType": "full_time",
  "hireDate": "2023-07-15",
  "status": "active",
  "dependents": [
    {
      "relationship": "spouse",
      "name": "Femi Okafor",
      "dob": "1989-08-12"
    }
  ]
}

Field	Type	Required	Notes
`externalId`	string	At enrollment	Your payroll’s employee ID (Check `Employee.id`). Primary upsert key: payroll results, terminations and HSA deposits find the employee by it.
`firstName`, `lastName`	string	At enrollment	Not needed to quote.
`email`	string	At enrollment	Upsert key when `externalId` is absent. Members are invited to the Prescience app via this address after launch.
`dob`	`YYYY-MM-DD`	One of `dob` \| `age`	Preferred; exact ages rate more accurately than integer ages. When both are sent, `dob` wins.
`age`	integer	One of `dob` \| `age`	Fallback when you don’t store DOB.
`zip`	string	Yes	5-digit home ZIP. Drives the geographic rating factor.
`sexAtBirth`	enum	No	`male` \| `female` \| `other`.
`employmentType`	enum	No	`full_time` \| `part_time` \| `contractor`.
`hireDate`	`YYYY-MM-DD`	No
`status`	enum	No	`active` (default) \| `terminated`. Terminated members are excluded from rating.
`dependents`	array	No	Household members already known to your platform. Each item accepts `relationship`, optional `name`, and optional `dob` (required for brokers).

Brokers: every employee and every dependent needs a dob. A member sent with only an age is rejected with an error naming its row (index), because small-group rates are age-rated from the date of birth. Limits: up to 10,000 employees per census and up to 6 dependents per employee.

Quoting vs enrollment requirements

To quote
To enroll

Per member: zip + one of dob | age. That’s it.This is deliberate: you can generate a quote from the minimal data every HR system has, before asking anyone for names or emails. Dependent dobs sharpen the rating (a spouse without one is placed within five years of the employee’s age; a child without one gets a stable age under 18), but they’re optional. The market comparison quotes these exact households, so the price covers the dependents you send.

Everything quoting needs, plus firstName, lastName, and email for every active member.This is enforced at enrollment time, not at census upload. POST /enrollments returns 400 invalid_request with one details entry per failing member:

{
  "error": "invalid_request",
  "message": "2 members are missing fields required for enrollment.",
  "details": [
    {
      "index": 3,
      "field": "email",
      "message": "email is required for enrollment"
    },
    {
      "index": 9,
      "field": "lastName",
      "message": "lastName is required for enrollment"
    }
  ]
}

Per-row errors: bad rows never block good ones

A census write is row-by-row. Valid rows are stored; invalid rows are rejected and reported with their index. A 142-row upload with one bad ZIP stores 141 members:

{
  "groupId": "grp_8c2f41d09a3e",
  "received": 142,
  "accepted": 141,
  "memberCount": 141,
  "errors": [
    { "index": 7, "field": "zip", "message": "zip must be a 5-digit ZIP code" }
  ],
  "warnings": ["3 members missing email (required before enrollment)"]
}

errors: rows that were rejected. Before enrollment, a rejected row’s member is not in the stored census. Fix and re-PUT the whole roster; matching makes re-sending the clean rows harmless.
warnings: non-blocking issues, today chiefly members missing email. They quote fine but will fail enrollment.

Treat accepted < received as a sync alert in your integration, not a hard failure. The group can still be quoted with the accepted members.

Reading the census back

GET /groups/{groupId}/census returns what’s stored, each member with a server-assigned memberId:

{
  "members": [
    {
      "memberId": "mem_c4a91f27e83d",
      "externalId": "emp_0001",
      "firstName": "Jordan",
      "lastName": "Reyes",
      "email": "jordan@acme.com",
      "dob": "1992-03-14",
      "zip": "94110",
      "employmentType": "full_time",
      "hireDate": "2024-03-01",
      "status": "active"
    }
  ],
  "count": 12
}

Keep memberId mapped to your employee record; it’s the handle for single-member updates (PATCH /members/{memberId}) in census sync.

Census intake is enrollment and eligibility data. Before live mode, a BAA and data processing agreement are executed covering exactly this data. See Compliance.

Get Started

Guides

Brokers

Resources

Member schema

Quoting vs enrollment requirements

Per-row errors: bad rows never block good ones

Reading the census back

​Member schema

​Quoting vs enrollment requirements

​Per-row errors: bad rows never block good ones

​Reading the census back

Member schema

Quoting vs enrollment requirements

Per-row errors: bad rows never block good ones

Reading the census back