v1

latestOpenAPI 3.1.02026-07-22191956.7 KB

Census

Replace the 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.

put/groups/{groupId}/census

Path parameters

groupIdstring required

Group ID, e.g. grp_8c2f41d09a3e.

Headers

Idempotency-Keystring

Any unique string (UUIDs work well). Replaying the same key within 24 hours returns the stored response instead of re-executing the request.

Request body

Example request

{
  "members": [
    {
      "externalId": "emp_0001",
      "firstName": "Jordan",
      "lastName": "Reyes",
      "email": "jordan@acme.com",
      "dob": "1992-03-14",
      "age": 34,
      "zip": "94110",
      "hireDate": "2024-03-01",
      "dependents": [
        {
          "dob": "2019-10-02",
          "name": "Mia Fischer"
        }
      ]
    }
  ]
}

Response

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

groupIdstring required

receivedinteger required

Rows in the request.

acceptedinteger required

Rows stored.

memberCountinteger required

Members on file after the replace.

warningsstring[] required

Non-blocking issues, e.g. members missing email (required before enrollment, not for quoting).

Example response

{
  "groupId": "grp_8c2f41d09a3e",
  "received": 12,
  "accepted": 12,
  "memberCount": 12,
  "errors": [
    {
      "index": 7,
      "field": "zip",
      "message": "zip must be a 5-digit ZIP code"
    }
  ]
}