Employee Census

Benbase requires employee census data to ensure accurate benefits administration. When a census is needed, Benbase will send a webhook notification through Svix, and you'll need to respond with the current employee data.

How It Works

Webhook Notification: Benbase sends a webhook when census data is needed
Upload Census Data: You respond with the complete employee census via API
Sync Completion: Benbase sends a confirmation webhook when processing is complete

Step 1: Sync Request Webhook Notification

When Benbase requires employee census data, you'll receive a webhook with the following event:

Event Type: employee-census.sync-request

Webhook Payload

{
  "data": {
    "employer_id": "emp_123456789"
  },
  "event_type": "employee-census.sync-request",
  "id": "wh_tqYaajv7yzbKX6m5Bf80P"
}

For information on setting up webhooks and managing them through the Svix portal, see the Webhooks documentation.

Step 2: Upload Census Data

After receiving the webhook, you must upload your complete employee census data using the API endpoint.

POST {{API_BASE_URL}}/employer/{id}/census

Request Payload

{
  "organization": {
    "legal_business_name": "Acme Corporation",
    "fein": "12-3456789",
    "entity_type": "C-Corp",
    "contact": {
      "first_name": "John",
      "last_name": "Smith",
      "email": "john.smith@acme.com"
    },
    "address": {
      "line1": "123 Business Street",
      "line2": "Suite 100",
      "city": "Austin",
      "state": "TX",
      "zip_code": "73301"
    }
  },
  "employees": [
    {
      "employee_id": "emp_LRgFZ2uXBSVsR6Q0g9Q54",
      "first_name": "John",
      "last_name": "Doe",
      "dob": "1990-01-15",
      "address": {
        "line1": "123 Main Street",
        "line2": "Apt 4B",
        "city": "New York",
        "state": "NY",
        "zip_code": "10001"
      },
      "hire_date": "2024-01-15",
      "email": "john.doe@example.com",
      "phone_number": "5551234567",
      "biological_sex": "male",
      "hours_worked": "40",
      "pay_frequency": "biweekly",
      "pay_rate": [
        {
          "amount": "25.50",
          "period": "hourly",
          "effective_start": "2024-01-15"
        }
      ],
      "employment_status": "full_time",
      "job_title": "Software Engineer"
    },
    {
      "employee_id": "emp_987654321",
      "first_name": "Jane",
      "last_name": "Smith",
      "dob": "1985-05-20",
      "address": {
        "line1": "456 Oak Avenue",
        "city": "Los Angeles",
        "state": "CA",
        "zip_code": "90210"
      },
      "hire_date": "2023-06-01",
      "email": "jane.smith@example.com",
      "hours_worked": "40",
      "pay_frequency": "monthly",
      "pay_rate": [
        {
          "amount": "75000.00",
          "period": "annually",
          "effective_start": "2023-06-01"
        }
      ],
      "employment_status": "full_time"
    }
  ]
}

Required Fields

Field	Type	Description	Validation
`organization`	object	Organization information	Required, see Organization fields below
`employees`	array	Array of employee objects	Required, minimum 1 employee

Organization Fields

Field	Type	Required	Description	Validation
`legal_business_name`	string	Yes	Legal business name of the organization	Required
`fein`	string	Yes	Federal Employer Identification Number	Required
`entity_type`	string	No	Type of business entity	Optional, see Entity Types below
`contact`	object	Yes	Contact person information	Required, see Contact fields below
`address`	object	Yes	Organization address	Required, see Address fields below

Entity Types

Entity Type	Description
`C-Corp`	C Corporation
`S-Corp`	S Corporation
`B-Corp`	Benefit Corporation
`LLC`	Limited Liability Company
`Non-profit`	Non-profit Organization
`Sole Proprietor`	Sole Proprietorship

Contact Fields

Field	Type	Required	Description	Validation
`first_name`	string	Yes	Contact person's first name	Required
`last_name`	string	Yes	Contact person's last name	Required
`email`	string	Yes	Contact person's email address	Required, valid email format

Employee Object Fields

Required Fields

Field	Type	Description	Validation
`employee_id`	string	Unique identifier for the employee	Required, min 1 character
`first_name`	string	Employee's first name	Required, max 255 characters
`last_name`	string	Employee's last name	Required, max 255 characters
`dob`	string	Date of birth	Required, YYYY-MM-DD format
`address`	object	Employee's address	Required, see Address fields below
`hire_date`	string	Employee's hire date	Required, YYYY-MM-DD format
`email`	string	Employee's email address	Required, valid email format, max 254 characters
`hours_worked`	string	Hours worked per week	Required
`pay_rate`	array	Employee's pay rate information	Required, array of pay rate objects
`employment_status`	string	Employment status	Required, `full_time` or `part_time`

For the pay rate you can specify the last applied pay rate or the whole history of pay rates.

Optional Fields

SSN syncing is optional. We will never expose the SSN in its entirety.
Whenever requested, only the last 4 digits are displayed. SSN data is safely stored and encrypted.

Field	Type	Description	Validation
`ssn`	string	Social Security Number	Optional
`phone_number`	string	Employee's phone number	Optional, max 10 characters
`termination_date`	string	Employee's termination date	Optional, YYYY-MM-DD format
`biological_sex`	string	Employee's biological sex	Optional, `male` or `female`
`pay_frequency`	string	Pay frequency	Optional, `weekly`, `biweekly`, `semimonthly`, or `monthly`
`job_title`	string	Employee's job title	Optional, max 255 characters

Address Fields

Field	Type	Required	Description
`line1`	string	Yes	Primary address line
`line2`	string	No	Secondary address line (apartment, suite, etc.)
`city`	string	Yes	City name
`state`	string	Yes	State code: `AL` `AK` `AZ` `AR` `CA` `CO` `CT` `DE` `DC` `FL` `GA` `HI` `ID` `IL` `IN` `IA` `KS` `KY` `LA` `ME` `MD` `MA` `MI` `MN` `MS` `MO` `MT` `NE` `NV` `NH` `NJ` `NM` `NY` `NC` `ND` `OH` `OK` `OR` `PA` `RI` `SC` `SD` `TN` `TX` `UT` `VT` `VA` `WA` `WV` `WI` `WY`
`zip_code`	string	Yes	ZIP code

Pay Rate Fields

Field	Type	Required	Description	Validation
`amount`	string	Yes	Pay rate amount	Required, must be 0 or more, rounded to 2 decimal places (e.g., 2.55)
`period`	string	Yes	Pay rate period	Required, see Period options below
`effective_start`	string	Yes	When the pay rate becomes effective	Required, YYYY-MM-DD format

Period Options

Period	Description
`hourly`	Hourly rate
`annually`	Annual rate

The employee data structure is the same as the new hire endpoint, but without the employer_id field since it's provided in the URL. The census endpoint also requires organization information.

If you have a personal email address, use that one as benefits could continue after unemployment. If not, use work email instead.

Sample Request

curl -X POST {{API_BASE_URL}}/employer/emp_123456789/census \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "organization": {
      "legal_business_name": "Acme Corporation",
      "fein": "12-3456789",
      "entity_type": "C-Corp",
      "contact": {
        "first_name": "John",
        "last_name": "Smith",
        "email": "john.smith@acme.com"
      },
      "address": {
        "line1": "123 Business Street",
        "line2": "Suite 100",
        "city": "Austin",
        "state": "TX",
        "zip_code": "73301"
      }
    },
    "employees": [
      {
        "employee_id": "emp_LRgFZ2uXBSVsR6Q0g9Q54",
        "first_name": "John",
        "last_name": "Doe",
        "dob": "1990-01-15",
        "address": {
          "line1": "123 Main Street",
          "city": "New York",
          "state": "NY",
          "zip_code": "10001"
        },
        "hire_date": "2024-01-15",
        "email": "john.doe@example.com",
        "hours_worked": "40",
        "pay_frequency": "biweekly",
        "pay_rate": [
          {
            "amount": "25.50",
            "period": "hourly",
            "effective_start": "2024-01-15"
          }
        ],
        "employment_status": "full_time"
      }
    ]
  }'

Step 3: Sync Completion Notification

After the census data is processed, Benbase will send a webhook notification confirming the sync is complete.

Event Type: employee-census.sync-complete

Webhook Payload

{
  "data": {
    "employer_id": "emp_123456789"
  },
  "event_type": "employee-census.sync-complete",
  "id": "wh_tqYaajv7yzbKX6m5Bf80P"
}

This webhook confirms that your census data has been successfully processed by Benbase

Best Practices

Include all active employees in your census response, not just new hires

Ensure all required fields are provided for each employee to avoid processing delays

Respond to the census request within a reasonable timeframe to maintain accurate benefits administration