Managing Leave and PTO

Paid time off in Everee is built from two pieces: leave types, the categories of leave like vacation, sick, or jury duty, and leave policies, the rules for who earns how much of each. Workers are enrolled in a policy, and Everee accrues their balances as they work and pays leave hours under the leave type's pay code.

This guide shows the workflow for setting leave up, getting workers into it, and keeping balances right. The Guide to the Leave Accrual API documents every field and rule.

Leave applies to employees. Contractors can't be enrolled.

How the pieces fit

Leave policy "Michigan PTO"           Leave types
├── accrues ───────────────────────►  Vacation   → pay code TIME_OFF_TYPE_VACATION
└── accrues ───────────────────────►  Sick       → pay code TIME_OFF_TYPE_SICK

Workers ── enrolled in ──► one policy at a time

A leave type has a name and, when it's paid, its own pay code. Everee provides some to every company.
A leave policy accrues one or more leave types. A worker is actively enrolled in only one policy at a time.
A worker's balances are tracked per leave type of the policy they're enrolled in, in hours.

1. Set up leave types

List leave types first. Everee includes system defaults, and you can't recreate or delete those.

Create a leave type for any category that's missing:

POST https://api.everee.com/integration/v1/leave/types

{
  "leaveTypeName": "Jury Duty",
  "alwaysVisibleOnPaystub": false
}

Leave types are identified by name, not an ID, and names match ignoring case. URL-encode them when you use them in a path.
Creating a type also creates its pay code, built from the name. "Jury Duty" gets TIME_OFF_TYPE_JURYDUTY. Two names that produce the same pay code, like "Jury Duty" and "Jury-Duty", clash and the second is rejected.
Some states require sick leave that accrues only on wages earned in that state. Pass state with a two-letter code, and Everee names the type for you, like "Sick (WI)". Don't put the state in the name yourself. This isn't available to every company yet.

2. Create a leave policy

A policy has a name and one or more leave types, each earned in one of three ways:

List	How it's earned	Pays out
`accruedLeaveTypes`	A little at a time as workers work, such as 1 hour for every 30 hours worked	Yes
`frontLoadedLeaveTypes`	A lump of hours granted at the start of each year, quarter, or month	Yes
`unpaidFrontLoadedLeaveTypes`	The same, for unpaid leave	No

Each leave type in a policy also carries:

Eligibility. eligibleAfterEmployedDays and eligibleAfterWorkedHours. A worker starts earning once both are met. Use 0 for both to start straight away.
A base award rule. The hours earned per hours worked, or the hours granted per period, plus optional limits: an annual accrual cap, a balance cap, a roll-over limit, and how far negative a balance can go.
Tenure tiers, optionally. Each tier replaces the base rule for workers who've reached a number of years. Values are totals rather than increases, and can't go down as tenure goes up.

See the Leave Accrual guide for the rules about front-loaded periods and how periods are aligned.

Create a leave policy with the types you want, and store the policy's id. A policy takes effect today. There are no drafts.

Two things to know before you create one:

You can only edit a policy's name and description afterward. Its leave types and award rules are fixed. To get different rules, create a new policy and move workers to it.
You can change one worker's rules without touching the policy, with Update a worker's leave award rules.

3. Enroll workers

A worker earns leave only while enrolled.

List workers with no policy to find employees who need one.
Enroll workers, up to 200 at a time.
Or enroll new hires when you create them, by sending the policy's id as timeOffPolicyId when you kick off onboarding or create an employee record. See Onboarding and managing workers.

Enrollment starts tomorrow. Moving a worker to a different policy ends their current enrollment today, so there's no gap and no overlap. Requests are all-or-nothing: if any worker or enrollment in the request can't be used, nothing changes and the error names every problem.

To remove workers, unenroll them by enrollment ID. This ends an active enrollment today and cancels an upcoming one. It doesn't move them to another policy.

4. Read and adjust balances

Get a worker's leave balances returns one balance per leave type, in hours. These endpoints work on a worker's active enrollment, and return 404 if they don't have one.

To load starting balances, for example when you migrate from another system, set a worker's balance to the target. Everee records the difference as a manual adjustment, so history is kept.

PUT https://api.everee.com/integration/v1/workers/{workerId}/leave/balances/TIME_OFF_TYPE_VACATION

Here a leave type is identified by its pay code, not its name.

How leave gets paid

Leave hours earn wages under the leave type's pay code, and show on the worker's pay stub under that type. Wages that Everee generates for paid time off can't be coded to cost centers individually. They use the worker's default cost centers, so workers who need leave allocated to a client or department should have defaults. See Working with cost centers.

When a worker is separated, you choose how their remaining balances are paid out as part of separating an employee.

Reporting on leave

Run the Outstanding Paid Leave Liability report from the Reports API to see what accrued leave the company owes. See Reconciling payroll and posting to your GL for how reports and webhooks work together.

Removing leave types and policies

Deleting a leave type or policy removes it if nothing has used it, and archives it otherwise. Either way you get a 204. Archiving keeps history. A policy that still has active enrollments can't be removed (409), so unenroll its workers first. System default leave types can't be deleted.

Checklist

List leave types before creating any.
Choose the way each leave type is earned, and get eligibility and limits right before you create the policy, because they can't be edited afterward.
Enroll workers when you create them, and use the unenrolled list to catch the rest.
Use pay codes in worker leave endpoints, and names in leave type endpoints.
Set default cost centers on workers if you allocate leave by client or department.