Guide to the Requirements API

A requirement is something that must be fixed before a company's payroll can process: a worker without a bank account, a funding account that's been disconnected, a company that isn't approved yet. The Requirements API lists them for the whole company, so you can prompt the right person to fix each one before payroll day. A payroll run's blockers show the same requirements for one run.

Endpoint	What it does
List requirements	Lists the company's open requirements, newest first
Retrieve a requirement	Retrieves one requirement, open or resolved

Subjects

Each requirement is about a worker or the company:

`subjectType`	`subjectId`
`WORKER`	The worker's `externalWorkerId`, or their `workerId` when they have none. `workerId` and `externalWorkerId` are also set.
`COMPANY`	The company's ID

The list is newest first and cursor-paginated, like every list in the Payroll Run API: see Listing and paging.

To list one subject's requirements, send subject-type and subject-id. For a worker, subject-id can be an externalWorkerId or a workerId: an externalWorkerId is matched first.

Resolving requirements

Follow resolutionInstructions. Most requirements resolve on their own once the fix is made: for example, when the worker's bank account is updated. Everee sends requirement.resolved when one does, and a payroll run it was blocking goes back to OPEN to be calculated again.

Some requirements are checked again on a schedule rather than when something changes. earliestRecheckAt is the earliest time Everee checks one again.

Requirement types

Most types are requirements, listed by this API and shown as blockers on the runs they affect. The rest come from a payment's own error: they only appear as blockers on a payroll run, with no requirementId, and clear when the run is calculated again after the fix.

Requirements

`type`	`sourceDomain`	Meaning and fix
`MISSING_BANK_ACCOUNT`	`WORKER_PROFILE`	Add a direct deposit bank account for the worker, or choose a different payment method.
`INVALID_BANK_ACCOUNT`	`WORKER_PROFILE`	Update the worker's direct deposit bank account with a valid routing and account number.
`MISSING_PAY_CARD`	`WORKER_PROFILE`	Have the worker sign up for a pay card, or choose a different payment method.
`CLOSED_PAY_CARD`	`WORKER_PROFILE`	The worker's pay card is closed. Add a direct deposit bank account or a new pay card for the worker.
`MISSING_OR_INVALID_ADDRESS`	`WORKER_PROFILE`	Update the worker's home address with a complete, valid street address.
`MISSING_TAX_PAYER_IDENTIFIER`	`WORKER_PROFILE`	Add a valid SSN or TIN for the worker.
`MISSING_EMPLOYEE_POSITION`	`WORKER_PROFILE`	Assign the worker a position with compensation details.
`MISSING_SOC_CODE`	`WORKER_PROFILE`	Assign a valid SOC code to the worker's position.
`MISSING_UNEMPLOYMENT_RATES`	`COMPANY_CONFIGURATION`	Contact Everee support to set up unemployment insurance rates for the worker's state.
`COMPANY_NOT_APPROVED`	`COMPANY_CONFIGURATION`	Finish setting up the company and wait for Everee to approve it before running payroll.
`FUNDING_ACCOUNT_DISCONNECTED`	`COMPANY_FUNDING`	Reconnect the company's funding bank account so payroll can be debited.
`INSUFFICIENT_FUNDS`	`COMPANY_FUNDING`	The funding account can't cover a payroll run. Add funds, then calculate the run again.
`WIRE_FUNDING_REQUIRED`	`COMPANY_FUNDING`	The run is funded by wire. Send the wire for the funding amount before the run's processing-blocked deadline.
`FUNDING_FAILED`	`COMPANY_FUNDING`	A funding debit was returned. If it reopened a payroll run, make sure the account has enough money, then calculate and approve the run again. Otherwise contact support to repay it: until it's repaid, no payroll run can be approved.

Payment errors (blockers only)

`type`	Blocker subject	Meaning and fix
`NEGATIVE_NET`	`WORKER`	Adjust the worker's earnings or deductions so their net pay isn't negative.
`EMPLOYMENT_NOT_STARTED`	`WORKER`	Check the worker's start date. Workers can't be paid before their employment starts.
`INSUFFICIENT_NET_FOR_ACH_FEE`	`PAYMENT`	The worker's net pay doesn't cover the ACH fee. Combine this payment with a future payment.
`MISSING_OR_INVALID_PAY_PERIOD`	`PAYMENT`	Check the worker's pay schedule, or contact Everee support.
`PREVIOUS_NOT_FINALIZED`	`PAYMENT`	Approve all earlier payroll runs for this worker, then try again.
`FUTURE_FINALIZED`	`PAYMENT`	A later payment has already been finalized. Contact Everee support.
`MISSING_CONTRIBUTION_DEDUCTION_LIMITS`	`PAYMENT`	Contact Everee support.
`FAILED_VALIDATION`	`PAYMENT`	Review the payment details and correct any invalid values.
`UNEXPECTED`	`PAYMENT`	Contact Everee support.

A WORKER payment-error blocker has the source WORKER_PROFILE, and a PAYMENT one has the source SYSTEM_ISSUE.

Webhook events

Event	Sent when
`requirement.created`	A requirement opens
`requirement.resolved`	A requirement is resolved

Each event's data.object is the requirement, as the API returns it. See Payroll Run Events.