API ReferenceEmployers

Create

Creates a new employer for the authenticated organization. Requires employer name, legal name, EIN, email, and address information. Returns the created employer with its assigned ID.

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`.

Request

This endpoint expects an object.
namestringRequired1-255 characters
Employer display name
legal_namestringRequired1-255 characters
Legal business name
einstringRequired=10 characters

Employer Identification Number (format: XX-XXXXXXX)

emailstringRequiredformat: "email"
Email address for billing and communications
addressobjectRequired
Employer address
phone_numberstring or nullOptional

Employer phone number (10-digit US format, e.g. 5551234567)

reference_idstring or nullOptional<=255 characters
External reference ID for this employer

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

dataobject
The employer record.

Errors

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