API ReferenceEmployers

Submit Payroll Access Setup

Submit the employer's payroll access setup answers.

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.

Path parameters

employer_idstringRequired

Unique employer identifier (empr_*)

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

Attestation that all benefit-eligible employees appear in the payroll system.

payroll_data_impacts_eligibility_acknowledgedbooleanRequired
Attestation that changes to payroll data affect benefit eligibility.
classifications_accuratebooleanRequired

Attestation that employee classifications in payroll are accurate. Set false to report corrections in the fields below.

all_benefit_eligible_employees_presentbooleanRequired

Attestation that every benefit-eligible employee is present in payroll.

is_controlled_groupbooleanRequired
Whether this employer belongs to a controlled group of related entities.
access_methodenumRequired
  • SELF_SETUP - SELF_SETUP
  • NEEDS_HELP - NEEDS_HELP
has_additional_payroll_systembooleanRequired

Whether a second payroll system is in use. When true, supply the additional_* fields below.

classification_correction_sourceenum or nullOptional

Where corrected classifications come from, when classifications_accurate is false.

misclassified_employee_nameslist of stringsOptionalDefaults to []
Names of employees whose payroll classification needs correcting.
remaining_employee_actionenum or nullOptional
How to handle employees still missing from the payroll system.
missing_employee_resolutionenum or nullOptional
How any missing employees will be added, when some are absent.
same_payroll_covers_other_einsboolean or nullOptional
Whether this payroll system also covers other EINs in the controlled group.
login_urlstring or nullOptional<=2048 characters

Sign-in URL for the payroll system.

usernamestring or nullOptional<=255 characters
Username Vitable should use to access the payroll system.
phonestring or nullOptional<=64 characters

Phone number used for payroll-system verification codes.

passwordstring or nullOptional<=979 characters
Password Vitable should use to access the payroll system.
integration_confirmedboolean or nullOptional
Whether the payroll integration has been confirmed as working.
additional_access_methodenum or nullOptional
How Vitable will access the second payroll system.
additional_login_urlstring or nullOptional<=2048 characters

Sign-in URL for the second payroll system.

additional_usernamestring or nullOptional<=255 characters
Username Vitable should use for the second payroll system.
additional_phonestring or nullOptional<=64 characters

Phone number used for second payroll-system verification codes.

additional_passwordstring or nullOptional<=979 characters
Password Vitable should use for the second payroll system.
additional_integration_confirmedboolean or nullOptional
Whether the second payroll integration has been confirmed as working.

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
Current status of the employer's payroll access setup.

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