Guide to the Leave Types API

A leave type is a category of leave, like vacation, sick leave or jury duty. Leave types are what leave policies accrue and pay out, and each one pays out under its own pay code. The Leave Types API lets you list, create and remove a company's leave types.

Leave types are identified by name

Leave types don't have an ID. A leave type is identified by its leaveTypeName, which you use in the path to delete it. Names are matched ignoring case, so "jury duty" and "Jury Duty" are the same leave type. Remember to URL-encode names with spaces.

When you create a leave type, its name is tidied up first: leading and trailing spaces are removed, and any run of spaces is collapsed into one. After that it must be from 3 to 100 characters.

System default types

Everee provides some leave types to every company. They're returned by the list endpoint with systemDefault set to true. You can't create a leave type with the same name as a system default type, and you can't delete one.

Pay codes

Creating a leave type also creates a pay code for it, so the response always includes a payCode. This is the pay code's apiKey, which is built from the name: TIME_OFF_TYPE_ followed by the name's letters and digits in upper case. "Jury Duty" gets TIME_OFF_TYPE_JURYDUTY.

Because the pay code is built from the name, two different names can produce the same pay code, like "Jury Duty" and "Jury-Duty". The second is rejected with a 409, as is a name whose pay code label matches an existing pay code.

payCode can be null on a system default type if the company doesn't have a pay code set up for it yet.

Pay stubs

alwaysVisibleOnPaystub controls whether the leave type appears on pay stubs when the worker has no leave hours of that type on the stub. It's required when you create a leave type.

Deleting and archiving

DELETE removes a leave type if it's safe to, and archives it otherwise. It returns 204 in both cases. Archiving keeps the history of a leave type that's been used.

A leave type is archived instead of deleted if any of these use it:

• a leave policy
• a worker's leave request
• a leave balance transaction
• earnings paid under its pay code

Archived leave types are left out of the list. An archived type's name can be used again: if you create a leave type with the name of one you archived, it reuses the archived type's pay code.

Deleting a leave type that's already archived, or one that doesn't exist, returns 404. Deleting a system default type returns 403.

Errors