Skip to content
Vitable Docs Vitable Docs Vitable Docs
Get started
API Reference
Employers
Employees

List employees

employers.employees.list(stremployer_id, EmployeeListParams**kwargs) -> EmployeeListResponse
get/v1/employers/{employer_id}/employees

Retrieves a paginated list of all employees for a specific employer. Use query parameters to filter by active status or employment classification. Results are paginated using page and limit parameters.

ParametersExpand Collapse
employer_id: str
active_in: Optional[bool]

Filter by active status

employee_class: Optional[EmployeeClass]

Filter by employment classification

Accepts one of the following:
"Full Time"
"Part Time"
"Temporary"
"Intern"
"Seasonal"
"Individual Contractor"
limit: Optional[int]

Items per page (default: 20, max: 100)

minimum1
maximum100
page: Optional[int]

Page number (default: 1)

minimum1
ReturnsExpand Collapse
EmployeeListResponse = List[Employee]
id: str

Unique employee identifier with 'empl_' prefix

active: bool

Whether the employee is currently active

created_at: datetime

Timestamp when the employee was created

formatdate-time
employer_id: str

ID of the employer this employee works for (empr_*)

member: Member

Nested member entity containing personal identity information.

Matches MemberEntity from account module domain.

id: str

Unique member identifier with 'mbr_' prefix

date_of_birth: date

Member's date of birth (YYYY-MM-DD)

formatdate
first_name: str

Member's legal first name

last_name: str

Member's legal last name

sex: Sex
  • Male - Male
  • Female - Female
  • Other - Other
  • Unknown - Unknown
Accepts one of the following:
"Male"
"Female"
"Other"
"Unknown"
email: Optional[str]

Email address for communications

formatemail
gender: Optional[str]

Gender identity, if provided

phone: Optional[str]

Phone number

suffix: Optional[str]

Name suffix (e.g., Jr., Sr., III)

start_date: date

Employee's start/hire date with the employer

formatdate
updated_at: datetime

Timestamp when the employee was last updated

formatdate-time
address: Optional[Address]

Nested address for employee.

city: str

City name

state: str

Two-letter state code

street_1: str

Primary street address

zip_code: str

ZIP code

country: Optional[str]

Country code

street_2: Optional[str]

Secondary street address

employee_class: Optional[EmployeeClass]
  • Full Time - Full Time
  • Part Time - Part Time
  • Temporary - Temporary
  • Intern - Intern
  • Seasonal - Seasonal
  • Individual Contractor - Individual Contractor
Accepts one of the following:
"Full Time"
"Part Time"
"Temporary"
"Intern"
"Seasonal"
"Individual Contractor"
termination_date: Optional[date]

Employee's termination date, if terminated

formatdate
List employees
from vitable_connect_api import VitableConnectAPI

client = VitableConnectAPI(
    api_key="My API Key",
)
employees = client.employers.employees.list(
    employer_id="empr_abc123def456",
)
print(employees)
[
  {
    "id": "id",
    "active": true,
    "created_at": "2019-12-27T18:11:19.117Z",
    "employer_id": "employer_id",
    "member": {
      "id": "id",
      "date_of_birth": "2019-12-27",
      "first_name": "first_name",
      "last_name": "last_name",
      "sex": "Male",
      "email": "dev@stainless.com",
      "gender": "gender",
      "phone": "phone",
      "suffix": "suffix"
    },
    "start_date": "2019-12-27",
    "updated_at": "2019-12-27T18:11:19.117Z",
    "address": {
      "city": "city",
      "state": "state",
      "street_1": "street_1",
      "zip_code": "zip_code",
      "country": "country",
      "street_2": "street_2"
    },
    "employee_class": "Full Time",
    "termination_date": "2019-12-27"
  }
]
Returns Examples
[
  {
    "id": "id",
    "active": true,
    "created_at": "2019-12-27T18:11:19.117Z",
    "employer_id": "employer_id",
    "member": {
      "id": "id",
      "date_of_birth": "2019-12-27",
      "first_name": "first_name",
      "last_name": "last_name",
      "sex": "Male",
      "email": "dev@stainless.com",
      "gender": "gender",
      "phone": "phone",
      "suffix": "suffix"
    },
    "start_date": "2019-12-27",
    "updated_at": "2019-12-27T18:11:19.117Z",
    "address": {
      "city": "city",
      "state": "state",
      "street_1": "street_1",
      "zip_code": "zip_code",
      "country": "country",
      "street_2": "street_2"
    },
    "employee_class": "Full Time",
    "termination_date": "2019-12-27"
  }
]