Employers

List employers

Returns the caller's employer book — every employer with its computed columns (enrollment-rate summary, benefit-family tags, HRIS connection, benefit-lifecycle stage) merged with the employer's flat CRM fields (legal name, EIN, contact, address, timestamps). The book is derived from the authenticated principal: one organization's employers, or every organization's for a caller whose reach is not a single organization. Supports search by display name, legal name, or exact EIN, employer id or contact email, benefit-family/lifecycle/HRIS filters, and page/limit pagination.

get/v1/employers

Request

  • Base URL: https://api.vitablehealth.com
  • URL: https://api.vitablehealth.com/v1/employers
  • Auth: HTTP bearer

Query parameters

benefit_familyBenefitFamilyParamItems[]

Filter to employers with at least one active benefit in these families.

benefit_lifecycle_stageBenefitLifecycleStageItems[]

Filter to employers in one of these computed benefit-lifecycle stages.

hris_providerstring[]

Filter to employers whose HRIS connection is with one of these payroll providers (e.g. ADP RUN). Matched case-insensitively; free text, so read the available values from the HRIS-providers endpoint rather than assuming a fixed set.

hris_statusHrisStatusItems[]

Filter to employers whose HRIS connection is in one of these statuses.

include_cancelledboolean

Include cancelled employers (hidden by default unless their stage is explicitly requested).

limitinteger

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

Items per page.

pageinteger

Page number (default: 1)

Page number.

searchstring

Employer filter. Matches the display name or the legal name case-insensitively as a substring, or one of these exactly: the EIN (with or without its dash), the employer id, or the contact email of one of the employer's non-disabled admins.

Headers

X-Vitable-Organizationstring

Organization to act as for this request (e.g. org_SGVsbG8gV29ybGQ). Optional when your credentials reach a single organization. Required when they reach several — omitting it then returns 400 organization_required. A malformed value returns 400 invalid_organization_header, and naming an organization you do not have access to returns 403 organization_access_denied.

Response

Changes

No recorded changes to this operation across all 1 revision of this API.