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. You already have all of this data; it’s your employee roster plus dependents. PUT /groups/{groupId}/census replaces the full census. Members are upserted by email when present, otherwise by externalId, so re-pushing your roster is always safe and idempotent.

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", "dob": "1989-08-12", "name": "Femi Okafor" }
  ]
}

Field	Type	Required	Notes
`externalId`	string	No	Your employee ID. Upsert key when `email` is absent.
`firstName`, `lastName`	string	At enrollment	Not needed to quote.
`email`	string	At enrollment	Primary upsert key. 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.
`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	Max 6 per member. Each: `relationship` (required: `spouse` \| `domestic_partner` \| `child` \| `other`), optional `dob`, `name`.

Limits: up to 10,000 members per census, 6 dependents per member.

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 rated at the employee’s age; a child without one is rated as a 10-year-old), but they’re optional.

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. Fix and re-PUT; upserts make 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

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