---
title: "Replace the census"
method: PUT
path: "/groups/{groupId}/census"
tags: ["Census"]
---

# Replace the census

`PUT /groups/{groupId}/census`

Full census replace. Rows are upserted by `email` when present, else by `externalId`. To quote, each member needs `zip` plus one of `dob` | `age`. Valid rows are stored even when other rows fail; check `errors` for per-row rejections. Rate limit: 20 census writes per minute.

## Path parameters

- `groupId` string, required

## Headers

- `Idempotency-Key` string

## Request body

- CensusReplaceRequest
  - `members` CensusMemberInput[], required — The full active census. Upsert key is `email` when present, else `externalId`. Max 10,000 members, 6 dependents each.
    - union — One employee. `zip` plus one of `dob` | `age` is enough to quote. `firstName`, `lastName`, and `email` are additionally required (per active member) at enrollment time.
      - object
        - `externalId` string — Your employee ID. Used as the upsert key when `email` is absent.
        - `firstName` string
        - `lastName` string
        - `email` string, email — Upsert key when present.
        - `dob` string, date, required
        - `age` integer — Alternative to `dob`. One of the two is required.
        - `zip` string, required — 5-digit home ZIP. Drives the area factor in rating.
        - `sexAtBirth` 'male' | 'female' | 'other'
        - `employmentType` 'full_time' | 'part_time' | 'contractor'
        - `hireDate` string, date
        - `status` 'active' | 'terminated'
        - `dependents` Dependent[]
          - `relationship` 'spouse' | 'domestic_partner' | 'child' | 'other', required
          - `dob` string, date
          - `name` string
      - object
        - `externalId` string — Your employee ID. Used as the upsert key when `email` is absent.
        - `firstName` string
        - `lastName` string
        - `email` string, email — Upsert key when present.
        - `dob` string, date
        - `age` integer, required — Alternative to `dob`. One of the two is required.
        - `zip` string, required — 5-digit home ZIP. Drives the area factor in rating.
        - `sexAtBirth` 'male' | 'female' | 'other'
        - `employmentType` 'full_time' | 'part_time' | 'contractor'
        - `hireDate` string, date
        - `status` 'active' | 'terminated'
        - `dependents` Dependent[]
          - `relationship` 'spouse' | 'domestic_partner' | 'child' | 'other', required
          - `dob` string, date
          - `name` string

## Response `200`

Census processed. `accepted` rows are stored; `errors` lists rejected rows by index.

- CensusReplaceResult
  - `groupId` string, required
  - `received` integer, required — Rows in the request.
  - `accepted` integer, required — Rows stored.
  - `memberCount` integer, required — Members on file after the replace.
  - `errors` object[], required — Per-row rejections. The row at `index` was not stored; everything else was.
    - `index` integer, required
    - `field` string, required
    - `message` string, required
  - `warnings` string[], required — Non-blocking issues, e.g. members missing email (required before enrollment, not for quoting).

## Other responses

- `400` — The payload itself is malformed (not a per-row failure).
- `401` — Missing, malformed, or revoked API key.
- `404` — No such resource in this mode. Test keys only see test resources; live keys only see live resources.
- `429` — Rate limit exceeded. Honor `Retry-After`.
- `500` — Something failed on our side. Safe to retry with the same `Idempotency-Key`.

---

[API](https://skmtc.dev/getprescience/apis/prescience-partner-api.md) · [All operations](https://skmtc.dev/getprescience/apis/prescience-partner-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/getprescience/prescience-partner-api/revisions/eb1f377f8139/schema)