List employers

client.employers.list(?, ?): 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

query: EmployerListParams { active_in, limit, name, page }

active_in?: boolean

Filter by active status

limit?: number

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

minimum1

maximum100

name?: string

Filter by employer name (partial match)

page?: number

Page number (default: 1)

minimum1

ReturnsExpand Collapse

EmployerListResponse = Array<Employer { id, active, created_at, 7 more } >

id: string

Unique employer identifier with 'empr_' prefix

active: boolean

Whether the employer is currently active in the system

created_at: string

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

Timestamp when the employer was last updated

formatdate-time

address?: Address | null

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 | null

Secondary street address (apt, suite, etc.)

ein?: string | null

Employer Identification Number (masked in responses)

eligibility_policy_id?: string | null

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

List employers

import VitableConnectAPI from 'vitable-connect-api';

const client = new VitableConnectAPI({
  apiKey: 'My API Key',
});

const employers = await client.employers.list();

console.log(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"
  }
]