List employers

employers.list() -> 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

EmployerListResponse = 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

legal_name: str

Legal business name for compliance and tax purposes

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

from vitable_connect_api import VitableConnectAPI

client = VitableConnectAPI(
    api_key="My API Key",
)
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"
  }
]