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.

Paying out leave

Leave hours are paid under the leave type's pay code. There are two ways a payout happens, and you can use either or both.

Everee generates it. When a worker takes leave in Everee, the wages are created for you and show on the pay stub under the leave type. They use the worker's default cost centers, if the worker has any.
You send it. Your system decides that leave should be paid, and sends it to Everee as a payable item. This is how you drive leave payouts through the API, for example when your own time-off or scheduling system approves leave, or when you pay out a balance.

Sending a leave payout with the Payables API

A leave payout is an ordinary payable item coded to the leave type's pay code. Every leave type has one, and it always starts with TIME_OFF_TYPE_, like TIME_OFF_TYPE_VACATION. You can find it in two places:

The Pay Codes API is the authoritative list of every pay code you can use, and it includes your leave types' pay codes alongside your other pay codes.
The Leave Accrual API returns each leave type's payCode, when you list leave types or get a policy.

POST https://api.everee.com/integration/v1/payables

{
  "externalId": "client_123::emp-1042::vacation_20261020",
  "externalWorkerId": "emp-1042",
  "label": "Vacation, October 20",
  "payableModel": "PRE_CALCULATED",
  "payCode": "TIME_OFF_TYPE_VACATION",
  "type": "vacation",
  "unitCount": 8,
  "amount": { "amount": 180.00, "currency": "USD" },
  "timestamp": 1792000000,
  "workLocationId": 1234,
  "costCenters": [{ "type": "clientId", "value": "290" }]
}

What makes a leave payout different from other payables:

	Leave payout
`unitCount`	Required. It's the number of hours being paid out and used. The request is rejected without it
`amount`	You calculate it, as with any payable. Everee doesn't derive it from the hours
Balance check	If the worker is enrolled in a policy, the hours you send for a leave type can't exceed their available balance for it. If they do, the request is rejected, and the error shows the requested hours and the balance
Balance	Once the payment that includes the payable is approved, the hours come off the worker's balance for that leave type, and the withdrawal is recorded against their policy. See What happens to the balance
Cost centers	Coded with the `costCenters` you send, like any other payable
Work location	Use `workLocationId` as you would for other wages. Without it, the worker's default work location is used

Everything else about payables applies unchanged. See Sending pay to Everee for idempotency with externalId, how employees are paid with regular payroll, requesting an earlier payout, and how to change or remove an unpaid item.

📘
Check the balance before you send
Sending more hours than a worker has is rejected, but only when they're enrolled in a policy. Get the worker's balances first, so you can show a clear message in your product. If you're loading balances from another system, set them before you pay out against them.

What happens to the balance

A leave payout and a worker's balance are two views of the same record. The balance you read with Get a worker's leave balances is the total of every entry for that leave type: accruals, manual adjustments from Set a worker's leave balance, and the withdrawals that payouts create. A payout lowers that same balance, whichever way the balance got its hours.


Which balance	The leave type of the pay code you send, in the policy the worker is enrolled in. `TIME_OFF_TYPE_SICK` draws on the sick balance and no other
When it comes off	When the payment that includes the payable is approved. Until then the balance doesn't change, and you can still change or remove the payable (see Changing or removing an amount)
When it's checked	When you send the payable, against the balance at that moment. The check doesn't count payouts you've already sent whose payments aren't approved yet, so several unapproved payouts can each pass it. Keep track of the hours you've sent, or read the balance again after each payment is approved
A leave type outside the worker's policy	The worker has no balance for it, so the request is rejected as exceeding an available balance of 0
A worker who isn't enrolled	There's no balance to check or to lower. The request isn't checked against a balance, and no balance changes

Cost centers on leave

Leave can be allocated to cost centers like any other wage:

Leave you send as a payable uses the costCenters on the payable.
Leave Everee generates uses the worker's default cost centers. Workers who need generated 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, and send costCenters on leave payables.
Send unitCount in hours on every leave payout, and check the balance first.

How the pieces fit

1. Set up leave types

2. Create a leave policy

3. Enroll workers

4. Read and adjust balances

Paying out leave

Sending a leave payout with the Payables API

Check the balance before you send

What happens to the balance

Cost centers on leave

Reporting on leave

Removing leave types and policies

Checklist

Next steps