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

List employers

employers.list(EmployerListParams**kwargs) -> EmployerListResponse
get/v1/employers

Retrieves a paginated list of all employers that the authenticated organization has access to. Use query parameters to filter by name or active status. Results are paginated using page and limit parameters.

ParametersExpand Collapse
active_in: Optional[bool]

Filter by active status

limit: Optional[int]

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

minimum1
maximum100
name: Optional[str]

Filter by employer name (partial match)

page: Optional[int]

Page number (default: 1)

minimum1
ReturnsExpand Collapse
List[Employer]
id: str

Unique employer identifier with 'empr_' prefix

active: bool

Whether the employer is currently active in the system

created_at: datetime

Timestamp when the employer was created

formatdate-time
name: str

Display name of the employer

organization_id: str

ID of the parent organization (org_*)

updated_at: datetime

Timestamp when the employer was last updated

formatdate-time
address: Optional[Address]

Nested address within EmployerSerializer.

city: str

City name

state: str

Two-letter state code (e.g., CA, NY)

street_1: str

Primary street address

zip_code: str

ZIP code (5 or 9 digit)

country: Optional[str]

Country code (default: US)

street_2: Optional[str]

Secondary street address (apt, suite, etc.)

ein: Optional[str]

Employer Identification Number (masked in responses)

eligibility_policy_id: Optional[str]

ID of the benefit eligibility policy (epol_*), if assigned

List employers
import os
from vitable_connect_api import VitableConnectAPI

client = VitableConnectAPI(
    api_key=os.environ.get("VITABLE_connect_API_API_KEY"),  # This is the default and can be omitted
)
employers = client.employers.list()
print(employers)
[
  {
    "id": "id",
    "active": true,
    "created_at": "2019-12-27T18:11:19.117Z",
    "legal_name": "legal_name",
    "name": "name",
    "organization_id": "organization_id",
    "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"
    },
    "ein": "ein",
    "eligibility_policy_id": "eligibility_policy_id"
  }
]
Returns Examples
[
  {
    "id": "id",
    "active": true,
    "created_at": "2019-12-27T18:11:19.117Z",
    "legal_name": "legal_name",
    "name": "name",
    "organization_id": "organization_id",
    "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"
    },
    "ein": "ein",
    "eligibility_policy_id": "eligibility_policy_id"
  }
]