---
title: "Get employee census data"
method: GET
path: "/payroll/hub/us/employees"
tags: ["Employees"]
---

# Get employee census data

`GET /payroll/hub/us/employees`

## Request

- Base URL: `https://api.hibob.com/v1`
- URL: `https://api.hibob.com/v1/payroll/hub/us/employees`
- Auth: HTTP bearer

**Beta.** Returns payroll-relevant employee profile fields (census data) for the
requested Bob employee IDs. Pass IDs as a comma-separated value on the
`employeeIds` query parameter (maximum 25 IDs per request). Employees outside
the caller's authorized scope are silently filtered out, not returned as errors.

**Rate limit:** 5 requests per minute per authenticated caller.

## Query parameters

- `employeeIds` string, required

## Response `200`

Success

- GetEmployeesOutput
  - `items` EmployeeCensus[], required: Employee census records, in the order the IDs were authorized. Items for employees the caller is not authorized to see are omitted from the response.
    - `employeeId` string, required: Unique Bob employee identifier (a numeric ID returned as a string to avoid loss of precision in JSON clients).
    - `ssn` string, nullable: Social Security Number, formatted `NNN-NN-NNNN`. Present only when the caller is authorized to view sensitive employee data.
    - `department` string, nullable: Employee department name. Valid values come from the **departments** system list (GET /metadata/lists/departments).
    - `employmentType` string, nullable: Employment type label (e.g. `"Permanent"`, `"Contractor"`). Valid values come from the **employmentTypes** system list (GET /metadata/lists/employmentTypes).
    - `employmentContract` string, nullable: Employment contract type label (e.g. `"Full time"`, `"Part time"`). Valid values come from the **employmentContracts** system list (GET /metadata/lists/employmentContracts).
    - `flsaCode` string, nullable: FLSA classification code (e.g. `"Exempt"`, `"Non-Exempt"`). Valid values come from the **flsaCode** system list (GET /v1/company/named-lists/flsaCode).
    - `gender` string, nullable: Reported gender label (free-text, varies by company configuration). Valid values come from the **genders** system list (GET /metadata/lists/genders).
    - `firstName` string, nullable: First (given) name.
    - `lastName` string, nullable: Last (family) name.
    - `middleName` string, nullable: Middle name when set in the employee record.
    - `addressLine1` string, nullable: First line of the residential street address.
    - `addressLine2` string, nullable: Second line of the residential street address (apartment, suite, etc.).
    - `city` string, nullable: City of residence.
    - `zip` string, nullable: ZIP or postal code.
    - `state` string, nullable: US state code (two-letter, e.g. `"NY"`) or region name.
    - `country` string, nullable: Country of residence (display name, e.g. `"United States"`).
    - `email` string, nullable: Work email address.
    - `personalEmail` string, nullable: Personal email address.
    - `workPhone` string, nullable: Work phone number.
    - `workMobile` string, nullable: Work mobile phone number.
    - `personalPhone` string, nullable: Personal phone number.
    - `personalMobile` string, nullable: Personal mobile phone number.
    - `dateOfBirth` string, nullable: Date of birth in ISO 8601 calendar date form (`YYYY-MM-DD`).
    - `startDate` string, nullable: Employment start date in ISO 8601 calendar date form.
    - `originalStartDate` string, nullable: Original employment start date in ISO 8601 calendar date form. May differ from `startDate` when the employee was rehired or had a break in service.
    - `site` string, nullable: Site identifier for the employee's work location. Valid values come from the **site** system list (GET /v1/company/named-lists/site).
    - `lifecycleStatus` string, nullable: Employee lifecycle status (e.g. `"Active"`, `"Inactive"`). Valid values come from the **lifecycleStatus** system list (GET /v1/company/named-lists/lifecycleStatus).
    - `terminationDate` string, nullable: Termination date in ISO 8601 calendar date form. Absent for active employees.
    - `terminationReason` string, nullable: Free-text termination reason. Absent for active employees.
    - `positionOpeningId` string, nullable: Position opening identifier linked to the employee's hire. Retrieve position opening details for this ID via `POST /v1/positions/position-openings/search`.
    - `recentLeaveStartDate` string, nullable: Start date of the employee's most recent leave in ISO 8601 calendar date form (`YYYY-MM-DD`).
    - `recentLeaveEndDate` string, nullable: End date of the employee's most recent leave in ISO 8601 calendar date form (`YYYY-MM-DD`).
    - `leaveType` string, nullable: Leave type label (e.g. `"Parental"`). Present only when the employee is currently on leave.
    - `maritalStatus` string, nullable: Marital status label (e.g. `"Single"`, `"Married"`).
    - `baseSalary` string, nullable: Base salary as a decimal string in the employee's pay currency (e.g. `"40000"`). String to preserve precision.
    - `salaryPayFrequency` string, nullable: Salary pay frequency label (e.g. `"Every two weeks"`, `"Monthly"`).
    - `salaryPayPeriod` string, nullable: Salary pay period label (e.g. `"Annual"`, `"Hourly"`).
  - `responseMetadata` ResponseMetadata, required: Pagination metadata returned with every list response. Use `nextCursor` to fetch the next page; `null` indicates there are no more results.
    - `nextCursor` string, nullable: Opaque cursor identifying the start of the next page of results. Pass this value back as the `cursor` query parameter on the next request to continue paging. `null` (or absent) when the current page is the last one.

## Other responses

- `400`: Bad request — invalid request body, validation error, or deduction rejected by US Payroll.
- `401`: Unauthorized — the OAuth 2.0 access token is missing, invalid, or expired.
- `403`: Forbidden — the authenticated caller does not have permission to perform this operation on the requested company, employer, or employee.
- `429`: Too many requests — rate limit exceeded. Read the limit per operation (most reads are 5/minute, mutations 200/minute) and retry after the indicated delay.
- `500`: Internal server error — an unexpected error occurred. Retry with exponential backoff; if the error persists, contact HiBob support with the `requestId` from the response body.

---

[API](https://skmtc.dev/hibob/apis/retirement-partners-api.md) - [All operations](https://skmtc.dev/hibob/apis/retirement-partners-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hibob/apis/retirement-partners-api/revisions/5ebd2ae67958?raw)