List employers

employers.list(**kwargs) -> EmployerListResponse { id, active, created_at, 7 more }

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: bool

Filter by active status

limit: Integer

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

minimum1

maximum100

name: String

Filter by employer name (partial match)

page: Integer

Page number (default: 1)

minimum1

ReturnsExpand Collapse

Array[Employer { id, active, created_at, 7 more } ]

id: String

Unique employer identifier with 'empr_' prefix

active: bool

Whether the employer is currently active in the system

created_at: Time

Timestamp when the employer was created

formatdate-time

legal_name: String

Legal business name for compliance and tax purposes

name: String

Display name of the employer

organization_id: String

ID of the parent organization (org_*)

updated_at: Time

Timestamp when the employer was last updated

formatdate-time

address: { city, state, street_1, 3 more}

Nested address within EmployerSerializer.

city: String

City name

state: String

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

street_1: String

Primary street address

zip_code: String

ZIP code (5 or 9 digit)

country: String

Country code (default: US)

street_2: String

Secondary street address (apt, suite, etc.)

ein: String

Employer Identification Number (masked in responses)

eligibility_policy_id: String

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

List employers

require "vitable_connect_api"

vitable_connect_api = VitableConnectAPI::Client.new(
  api_key: "My API Key",
  environment: "environment_1" # defaults to "production"
)

employers = vitable_connect_api.employers.list

puts(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"
  }
]