Skip to navigation
API ReferenceEmployers

List

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.

Authentication

AuthorizationBearer

API Key or Access Token authentication using Bearer token in Authorization header. API keys use the vit_apk_ prefix, access tokens use the vit_at_ prefix.

Headers

X-Vitable-OrganizationstringOptional

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.

Query parameters

benefit_familylist of enumsOptionalDefaults to []
Filter to employers with at least one active benefit in these families.
benefit_lifecycle_stagelist of enumsOptionalDefaults to []

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

Allowed values:
hris_providerlist of stringsOptionalDefaults to []

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_statuslist of enumsOptionalDefaults to []
Filter to employers whose HRIS connection is in one of these statuses.
Allowed values:
include_cancelledbooleanOptionalDefaults to false

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

limitintegerOptional1-100Defaults to 20
Items per page.
pageintegerOptional>=1Defaults to 1
Page number.
searchstringOptional>=1 character

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.

Response headers

X-RateLimit-Limitinteger
Maximum number of requests allowed within the rate limit window
X-RateLimit-Remaininginteger
Number of requests remaining in the current rate limit window
X-RateLimit-Resetinteger

Unix timestamp (seconds) when the rate limit window resets

Response

datalist of objects
This page of employers in the organization.
paginationobject

Page metadata. Request the next page by incrementing page.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
429
Too Many Requests Error
500
Internal Server Error
502
Bad Gateway Error