Workflows, Hiring & HRHR Checks, Limits & Data Objects
On this page0
Unfamiliar word? See Glossary: words used in these docs. Looking for the tasks in order? Begin at Start Here.
Reference
Included in: Org chart and the employee file: All plans. Time off, pay history, goals, reviews and surveys: Team and Advanced. Which Plan Includes What
HR Checks, Limits & Data Objects
The technical reference for the HR module: what the server checks on each action, record states, hard limits, scheduled jobs and the API objects. A person’s own record and a manager’s view of the people who report to them need no permission. The list of HR permissions is on the overview page, under Permissions. This page is part of the reference HR Records, Time Off & Reviews.
What This Page Is For
In plain words: the other HR pages say what people can do. This one says what the product itself enforces, so you can tell an action that is not allowed from one that has gone wrong. It answers four kinds of question:
- Why was this refused? For each action, such as approving time off or adding a pay record, the page lists what is checked before it goes through: who is asking, whose record it is, and what state the record is in.
- What happens next to this record? A request, a review or a job change moves through a fixed set of stages. The page lists the stages and what moves a record from one to the next.
- How much is allowed? The product has fixed ceilings. For example, a stored document can be up to 10 MB and one person can hold up to 100 documents. The page lists each ceiling.
- What runs without anyone pressing a button? Some work is done on a timer, such as the daily reminders about probation and contract dates. The page lists each of those jobs and how often it runs.
If you are here to do a task and not to look up a rule, the steps are in the guides: Open and maintain an employee file, Set up time off and Run a review cycle. The technical part below is written for a developer or an IT administrator and names the exact routes, permissions and fields.
If something here is not working as you expect, start with When something goes wrong.
The plain explanation is above. This part is for IT and developers: the exact settings, permission names, API addresses and data fields behind it. Closed: select the heading above to open it. While it is closed, your browser’s find-on-page (Ctrl+F or Cmd+F) does not search this part.
The Check Behind Each Action
Each row is one thing a person does on screen and what the server checks when it happens. “Signed in” means the route asks for no permission: the service then checks that the record is the caller’s own, or belongs to someone below them in the reporting line, and answers 404 when it is neither, so the answer does not confirm that the record exists. Rows marked HR module also answer 403 when the hris entitlement is switched off on your licence. Paths are under /user-management; the request and reply of each is in the API reference.
| Action | Route | What Is Checked |
|---|---|---|
| Open the People directory or any employee file | GET /employees, GET /employees/:userId | view_employee_records or manage_employee_records |
| Edit a file, emergency contacts, a job change, the leaving record | PUT /employees/:userId, PUT …/emergency-contacts, POST and DELETE …/job-changes, PUT …/departure | manage_employee_records |
| Reveal a date of birth or home address | POST /employees/:userId/reveal | view_employee_records or manage_employee_records; each reveal is written to the audit log |
| Read or change HR Settings and retention | GET /employees/hr-settings; PUT /employees/hr-settings, PUT …/retention | Read: view_employee_records or manage_employee_records. Change: manage_employee_records |
| Read your own file and change your own details | GET and PUT /employees/me, PUT /employees/me/emergency-contacts | Signed in |
| Read your team, or one person in it | GET /employees/my-team, GET /employees/my-team/:userId | Signed in; the person must be below you in the reporting line (404 otherwise) |
| See pay history, reveal an amount | GET /employees/:userId/compensation, POST …/compensation/:recordId/reveal | view_compensation or manage_compensation. HR module |
| Add or void a pay record | POST /employees/:userId/compensation, POST …/compensation/:recordId/void | manage_compensation. HR module |
| Read or download a person's documents | GET /employees/:userId/documents, GET …/documents/:docId/download | view_employee_records or manage_employee_records. HR module |
| Upload, change or remove a document | POST /employees/:userId/documents, PUT …/documents/:docId/content, PUT and DELETE …/documents/:docId | manage_employee_records. HR module |
| Read documents shared with you, or with you as a manager | GET /employees/me/documents, GET /employees/my-team/:userId/documents | Signed in; only entries whose visibility includes you. HR module |
| People Reports | GET /employees/reports/summary | view_employee_reports. HR module |
| Payroll hand-off | GET /employees/payroll-export, GET /employees/payroll-export/last | export_compensation. HR module |
| Request, preview or cancel your own time off | GET /leave/me, GET /leave/preview, POST /leave/requests, POST /leave/requests/:id/cancel | Signed in. Someone else's request can be cancelled only with manage_leave or as an administrator. HR module |
| Approve or decline time off | GET /leave/approvals, POST /leave/requests/:id/decide, POST /leave/approvals/approve, POST /leave/approvals/decline | Signed in; the decider must be above the requester in the reporting line, an administrator, or hold manage_leave, and nobody decides their own. HR module |
| Who is out | GET /leave/calendar | Signed in. HR module |
| Types of time off, working calendars, balance adjustments | GET /leave/setup; POST, PUT and DELETE /leave/types and /leave/calendars; POST /leave/people/:userId/adjust | manage_leave. HR module |
| Read one person's balances and requests | GET /leave/people/:userId | manage_leave, view_employee_records or manage_employee_records. HR module |
| Read or change goals | GET /goals/mine, GET /goals/people/:userId, POST /goals, PUT and DELETE /goals/:id | Signed in; you may read and change your own goals and those of people below you. manage_employee_records also reads and changes anyone's; view_employee_records reads only. HR module |
| Write your self review, write a review as the reviewer, share it | PUT /reviews/:reviewId/self, PUT /reviews/:reviewId/manager, POST /reviews/:reviewId/share | Signed in; the review must be yours to write (404 otherwise). HR module |
| Run review cycles: create, launch, close, progress, calibration, reassign, reopen, read a review | /reviews/cycles and its sub-routes, PUT /reviews/:reviewId/reviewer, POST /reviews/:reviewId/reopen, GET /reviews/:reviewId | manage_employee_reviews. HR module |
| Answer a survey | GET /surveys/mine, POST /surveys/:id/respond | Signed in; you must have been invited (404 otherwise). HR module |
| Run surveys: create, open, close, duplicate, results, trends | GET and POST /surveys, PUT and DELETE /surveys/:id, POST /surveys/:id/open, /close and /duplicate, GET /surveys/:id/results, GET /surveys/trends | manage_employee_surveys. HR module |
States And Transitions
The HR records that move through fixed states, with the value the API returns for each and what moves a record from one to the next. A move that is not listed is refused.
| Record | States | What Moves It |
|---|---|---|
| Time-off request (status) | pending → approved | declined | cancelled; approved → cancelled | A request for a type with approval switched off starts as approved. A decision is accepted only while the request is pending (409 afterwards). The requester can cancel a pending request, or an approved one that has not started; manage_leave or an administrator can cancel any live request. Cancelling an approved request returns its days to the balance. declined and cancelled are final. |
| Job change (status) | scheduled → applied | cancelled | A change dated today or earlier is applied at once. A change dated in the future is stored as scheduled and applied by the hourly job on its day. Only a scheduled change can be cancelled; one that cannot be applied on its day is cancelled with the reason added to it. |
| Review (state) | with_person → with_reviewer → ready_to_share → shared | The person submitting their self review moves it to with_reviewer; the reviewer submitting moves it to ready_to_share; sharing moves it to shared. In a cycle that uses calibration, sharing is refused until HR has released the ratings. HR can reopen either half, which moves the review back to that step. |
| Review cycle (status) | draft → open → closed | Launch opens a draft; launching an open cycle again adds people who are now in scope. Only an open cycle can be closed, only a draft can be deleted, and a closed cycle cannot be changed or launched again. |
| Survey (status) | draft → open → closed | Only a draft can be opened or deleted, only an open survey can be closed, and a closed survey cannot be changed. Run again makes a new draft; it does not reopen the old survey. |
| Compensation record | live → voided | Only a record a person typed in can be voided, once, with a reason. A void cannot be undone, and a record is never edited or deleted. |
Limits
The hard limits the server enforces. A request beyond one is answered with 400 and the reason in words, unless the row says otherwise.
| What | Limit |
|---|---|
| People directory page | limit 1 to 200 (default 50); a search uses the first 8 words typed |
| Job history on a file | The newest 200 changes (the newest 100 on your own file and on a team member's) |
| Emergency contacts | 5 per person; a phone number up to 40 characters |
| Free-text fields on a file | 255 characters; home address 1,000; the reason on a job change 1,000 |
| Documents | 100 per person; 10 MB each; PDF, PNG, JPEG, Word (.docx) or Excel (.xlsx), decided from the file's own bytes (413 over the size, 415 for another type); a name up to 180 characters |
| Time off by the hour | A whole number of minutes, at least 15, starting and ending on the same day |
| One time-off request | A span of at most 366 days; a note up to 500 characters; a weekly repeat of 2 to 12 weeks; at most 20 bookings by the hour replaced by one request |
| Bulk approve or decline | 1 to 50 requests in one call |
| Time-off lists | Your requests: the newest 100 by start date. Requests waiting for your decision: the 200 with the earliest start date. Who is out: a range of at most 366 days |
| Type of time off | A name up to 60 characters, unique without regard to case; days per year and carry-over limit 0 to 366 |
| Balance adjustment | Not zero, and at most 366 days either way; a reason is required |
| Goals | 50 per person; 30 example goals |
| Review cycle | 12 questions; an answer up to 4,000 characters; 8 colleagues asked for feedback per review |
| Survey | 20 questions; a written answer up to 1,000 characters; an audience of at least 5 people; results need at least 5 responses |
| Payroll hand-off | A period of at most 366 days |
| Retention for people who have left | 0 (off), or a whole number of months from 6 to 240 |
Scheduled Jobs
Four jobs run inside your instance without anyone starting them. Each also runs once a few minutes after the service starts, and each can be run again safely: a reminder already sent, a change already applied or an allowance already credited is not repeated.
| Job | Runs | What It Does |
|---|---|---|
| Scheduled job changes | Every hour | Applies each scheduled job change whose effective date has arrived, oldest first, up to 500 in one run. The person's title, department, manager, level, employment type or location changes at that moment. |
| Time-off accrual | Once a day | Credits the time off each person has earned under their types of time off, and at the turn of the year removes what is above a type's carry-over limit. Correcting a person's start date credits that person at once, without waiting for the run. |
| Date reminders | Once a day | Notifies the holders of manage_employee_records, and for probation and contract dates the person's manager too. Probation end: 14 days before and on the day. Contract end: 30 days, 7 days and on the day. Right to work: 60 days, 14 days and on the day. A document with an expiry date: 30 days before and on the day, on plans with the HR module. A reminder missed by up to 7 days is still sent; the person the date belongs to is never the one notified. |
| Retention for people who have left | Once a day | Does nothing unless a retention period is set in HR Settings. For a person whose account is in a left state and whose last day is further back than the period, it removes their HR profile, pay records, emergency contacts, time-off requests and balance entries, documents, goals, reviews and the feedback about them, training assignments and completions, learning-path memberships and survey invitations. Each removal is written to the audit log at warning level. The removal is permanent. |
Data Objects (Typed Fields)
In plain words: a call to the API answers with objects such as an employee file, a compensation record or a time-off request. This section lists what is inside each one: every field, its type, and whether it can be empty. Open an object to see its fields. In the API reference, a capitalised name in a row’s returns line is one of these objects. The training, learning-path and phishing objects are on the page Training, Phishing & Policy Signing.
- Types.
integer,number,string,boolean,objectand arrays written asinteger[].string (date-time)is ISO 8601 in UTC;string (date)isYYYY-MM-DD. A type followed by a colon and values separated by|takes only those values. A capitalised type is another object in this list. - The third column. “nullable” means the field can be
null; “optional” means the key can be missing; “no” means neither. Do not fail on a field you do not recognise: a reply can carry fields beyond these. A card marked “request body” is what you send, not what comes back: its third column is headed Required, where “required” means the field must be sent and every other field is optional. - Not part of
EmployeeListItem,EmployeeFileorCompensationRecord: a date of birth, a home address and a pay amount. Someone else’s is read one at a time through its reveal route, and each reveal is written to the audit log. Two routes do carry them: your own file (GET /employees/me) holds your own date of birth and home address, and the payroll hand-off (GET /employees/payroll-export, permissionexport_compensation) holds the pay amounts of the period.
EmployeeListItemin a reply18 fields
One row of GET /user-management/employees.
| Field | Type | Null / optional / read-only | Note |
|---|---|---|---|
| id | integer | no | |
| firstName | string | nullable | |
| lastName | string | nullable | |
| string | no | ||
| name | string | no | First and last name joined; the email address when both are empty. |
| position | string | nullable | Job title. |
| department | string | nullable | |
| managerId | integer | nullable | |
| managerName | string | nullable | |
| status | string | nullable | The account status, for example active. |
| employeeId | string | nullable | Your own employee number, not the Zonitix id. |
| photoUrl | string | nullable | |
| terminationDate | string (date-time) | nullable | |
| hireDate | string (date) | nullable | |
| employmentType | string | nullable | |
| workLocation | string | nullable | |
| level | string | nullable | |
| reminders | EmployeeReminder[] | no | Empty for a person who has left. |
EmployeeReminderin a reply5 fields
An upcoming date on a file. Worked out on each read, not stored.
| Field | Type | Null / optional / read-only | Note |
|---|---|---|---|
| kind | string: probation | contract | right_to_work | no | |
| label | string | no | "Probation ends", "Contract ends" or "Right to work expires". |
| date | string (date) | no | |
| days | integer | no | Days from today; negative once the date has passed. |
| overdue | boolean | no | true when days is below 0. |
EmployeeFilein a reply7 fields
GET /user-management/employees/:userId, and the reply of every write on a file.
| Field | Type | Null / optional / read-only | Note |
|---|---|---|---|
| user | EmployeeFileUser | no | |
| profile | EmployeeProfile | no | |
| emergencyContacts | EmergencyContact[] | no | In the stored order. |
| history | EmploymentEvent[] | no | The newest 200 job changes, newest effective date first. |
| reminders | EmployeeReminder[] | no | |
| authority | HrAuthority | no | Which system owns each governed field. |
| people | object | no | { "<user id>": name } for the managers named in history. |
EmployeeFileUserin a reply18 fields
The identity half of an employee file.
| Field | Type | Null / optional / read-only | Note |
|---|---|---|---|
| id | integer | no | |
| firstName | string | nullable | |
| lastName | string | nullable | |
| string | no | ||
| name | string | no | |
| position | string | nullable | |
| department | string | nullable | |
| managerId | integer | nullable | |
| managerName | string | nullable | |
| status | string | nullable | |
| employeeId | string | nullable | |
| phoneNumber | string | nullable | |
| personalEmail | string | nullable | |
| photoUrl | string | nullable | |
| terminationDate | string (date-time) | nullable | |
| personaId | integer | nullable | |
| source | string | nullable | Where the account came from, for example local. |
| createdAt | string (date-time) | no |
EmployeeProfilein a reply18 fields
The HR half of an employee file. Every field is null until it is set.
| Field | Type | Null / optional / read-only | Note |
|---|---|---|---|
| preferredName | string | nullable | |
| legalName | string | nullable | |
| nationality | string | nullable | |
| hireDate | string (date) | nullable | |
| originalHireDate | string (date) | nullable | |
| employmentType | string | nullable | |
| workLocation | string | nullable | |
| level | string | nullable | |
| costCenter | string | nullable | |
| legalEntity | string | nullable | |
| probationEndDate | string (date) | nullable | |
| contractEndDate | string (date) | nullable | |
| noticePeriod | string | nullable | Free text, up to 255 characters. |
| rightToWorkStatus | string: verified | pending | expired | not_required | nullable | |
| rightToWorkVerifiedAt | string (date) | nullable | |
| rightToWorkExpiresAt | string (date) | nullable | |
| hasDateOfBirth | boolean | no | The date itself is never in a file; reveal it with POST /reveal. |
| hasHomeAddress | boolean | no | The address itself is never in a file; reveal it with POST /reveal. |
EmergencyContactin a reply4 fields
| Field | Type | Null / optional / read-only | Note |
|---|---|---|---|
| id | integer | no | |
| name | string | nullable | null only when the stored value cannot be read. |
| relationship | string | nullable | |
| phone | string | nullable |
EmploymentEventin a reply13 fields
One job change in a file's history.
| Field | Type | Null / optional / read-only | Note |
|---|---|---|---|
| id | integer | no | |
| userId | integer | no | |
| type | string | no | promotion | transfer | manager_change | title_change | other for a change a person recorded. |
| effectiveDate | string (date) | no | |
| status | string: applied | scheduled | cancelled | no | scheduled until its effective date arrives. |
| changes | object | no | { "<field>": { from, to } } for each field that changed. |
| reason | string | nullable | |
| source | string | no | manual for a change a person recorded. |
| sourceRef | string | nullable | |
| actorEmail | string | nullable | |
| appliedAt | string (date-time) | nullable | |
| createdAt | string (date-time) | no | |
| updatedAt | string (date-time) | no |
HrAuthorityin a reply7 fields
Which system owns people data. Also the base of GET /employees/hr-settings.
| Field | Type | Null / optional / read-only | Note |
|---|---|---|---|
| mode | string: zonitix | external | no | |
| providerId | integer | nullable | The connected HR system, when mode is external. |
| providerName | string | nullable | |
| providerMissing | boolean | no | true when mode is external and that connection no longer exists. |
| fields | object | no | { "<field key>": "zonitix" | "external" }: the owner of each governed field. |
| overrides | object | no | The per-field choices as saved. |
| lastSync | object | nullable | What the last sync from the HR system recorded. |
CompensationRecordin a reply13 fields
The amount is never part of this object: reveal one with POST /compensation/:recordId/reveal.
| Field | Type | Null / optional / read-only | Note |
|---|---|---|---|
| id | integer | no | |
| effectiveDate | string (date) | no | |
| currency | string | no | A 3-letter code. |
| payPeriod | string: annual | monthly | hourly | no | |
| bonusPct | number | nullable | |
| reason | string | nullable | |
| source | string | no | manual for a record a person typed in. |
| sourceOfferId | integer | nullable | The signed offer the record was carried over from. |
| actorEmail | string | nullable | |
| createdAt | string (date-time) | no | |
| voidedAt | string (date-time) | nullable | |
| voidedBy | string | nullable | |
| voidReason | string | nullable |
EmployeeDocumentin a reply9 fields
The entry for a stored file. The file itself is fetched from the download route.
| Field | Type | Null / optional / read-only | Note |
|---|---|---|---|
| id | integer | no | |
| name | string | no | Up to 180 characters. |
| category | string: contract | offer | job_change | policy | certificate | review | letter | other | no | |
| visibility | string: hr | employee | manager | no | |
| mimeType | string | nullable | null until the file has been uploaded. |
| sizeBytes | integer | no | 0 until the file has been uploaded. |
| expiresAt | string (date) | nullable | |
| uploadedBy | string | nullable | The email address of the person who created the entry. |
| createdAt | string (date-time) | no |
DepartureRecordin a reply9 fields
The leaving record on a file.
| Field | Type | Null / optional / read-only | Note |
|---|---|---|---|
| id | integer | no | |
| lastDay | string (date) | no | |
| departureType | string: voluntary | involuntary | end_of_contract | nullable | |
| reasonCode | string | nullable | One of the keys in the reply's reasons list. |
| rehireEligible | boolean | nullable | |
| checklist | object[] | no | Each { key:string, label:string, done:boolean, doneBy:string|null, doneAt:string (date-time)|null }. |
| source | string | no | |
| recordedBy | string | nullable | |
| createdAt | string (date-time) | no |
LeaveBalancein a reply16 fields
One per type of time off.
| Field | Type | Null / optional / read-only | Note |
|---|---|---|---|
| typeId | integer | no | |
| name | string | no | |
| paid | boolean | no | |
| tracksBalance | boolean | no | |
| requiresApproval | boolean | no | |
| annualDays | number | no | |
| allowNegative | boolean | no | |
| isActive | boolean | no | |
| allowHours | boolean | no | |
| minPartMinutes | integer | no | The smallest booking by the hour. |
| maxPartMinutes | integer | nullable | The most per booking by the hour. |
| balance | number | nullable | null for a type that does not track a balance. |
| pending | number | no | Days in requests still waiting for a decision. |
| available | number | nullable | balance minus pending, to two places; null without a balance. |
| availableExact | number | nullable | The same figure before rounding. |
| taken | number | no | Approved days that start in the current calendar year. |
LeaveRequestin a reply17 fields
| Field | Type | Null / optional / read-only | Note |
|---|---|---|---|
| id | integer | no | |
| userId | integer | no | |
| leaveTypeId | integer | no | |
| typeName | string | nullable | Not sent in the reply to a cancel. |
| startDate | string (date) | no | |
| endDate | string (date) | no | |
| startHalf | boolean | no | |
| endHalf | boolean | no | |
| startTime | string (HH:MM) | nullable | Set only for time off by the hour. |
| minutes | integer | nullable | Set only for time off by the hour. |
| days | number | no | Working days the request uses. |
| status | string: pending | approved | declined | cancelled | no | |
| note | string | nullable | Up to 500 characters. |
| decidedByEmail | string | nullable | |
| decidedAt | string (date-time) | nullable | |
| decisionNote | string | nullable | |
| createdAt | string (date-time) | no |
LeaveTypein a reply15 fields
| Field | Type | Null / optional / read-only | Note |
|---|---|---|---|
| id | integer | no | |
| name | string | no | Up to 60 characters; unique without regard to case. |
| paid | boolean | no | |
| requiresApproval | boolean | no | |
| tracksBalance | boolean | no | |
| annualDays | number | no | 0 to 366. |
| accrual | string: upfront | monthly | no | |
| accrueFrom | string (date) | nullable | |
| carryOverMaxDays | number | no | 0 to 366. |
| allowNegative | boolean | no | |
| allowHours | boolean | no | |
| minPartMinutes | integer | no | |
| maxPartMinutes | integer | nullable | |
| isActive | boolean | no | false for a retired type. |
| sortOrder | integer | no |
WorkingCalendarin a reply8 fields
| Field | Type | Null / optional / read-only | Note |
|---|---|---|---|
| id | integer | no | |
| name | string | no | |
| location | string | nullable | |
| workDays | integer[] | no | The working days of the week. |
| hoursPerDay | number | no | |
| dayStart | string (HH:MM) | no | |
| isDefault | boolean | no | |
| holidays | object[] | no | Each { date:string (date), name:string }, earliest first. |
Goalin a reply13 fields
| Field | Type | Null / optional / read-only | Note |
|---|---|---|---|
| id | integer | no | |
| userId | integer | no | |
| title | string | no | |
| description | string | nullable | |
| period | string | nullable | |
| dueDate | string (date) | nullable | |
| status | string: on_track | at_risk | done | dropped | no | |
| progress | integer | no | |
| weight | integer | nullable | |
| createdByEmail | string | nullable | |
| completedAt | string (date-time) | nullable | |
| createdAt | string (date-time) | no | |
| updatedAt | string (date-time) | no |
GoalTemplatein a reply5 fields
An example goal.
| Field | Type | Null / optional / read-only | Note |
|---|---|---|---|
| id | integer | no | |
| title | string | no | |
| description | string | nullable | Up to 2,000 characters. |
| isActive | boolean | no | |
| sortOrder | integer | no |
ReviewCyclein a reply16 fields
| Field | Type | Null / optional / read-only | Note |
|---|---|---|---|
| id | integer | no | |
| name | string | no | |
| periodLabel | string | nullable | |
| selfDueDate | string (date) | nullable | |
| managerDueDate | string (date) | nullable | |
| questions | object[] | no | Each { key:string, label:string, help:string|null }; at most 12. |
| includeRating | boolean | no | |
| department | string | nullable | null when the cycle covers everyone. |
| peerFeedback | string | no | The colleague-feedback mode of the cycle. |
| calibration | boolean | no | |
| ratingsReleased | boolean | no | |
| ratingTargets | object | nullable | null when the cycle does not use calibration. |
| goalRatings | boolean | no | |
| status | string | no | draft, open or closed. |
| launchedAt | string (date-time) | nullable | |
| closedAt | string (date-time) | nullable |
Surveyin a reply10 fields
| Field | Type | Null / optional / read-only | Note |
|---|---|---|---|
| id | integer | no | |
| title | string | no | |
| intro | string | nullable | |
| questions | object[] | no | Each { key:string, label:string, type: scale | enps | text }; at most 20. |
| department | string | nullable | null when everyone is asked. |
| status | string | no | draft, open or closed. |
| closesAt | string (date) | nullable | |
| openedAt | string (date-time) | nullable | |
| closedAt | string (date-time) | nullable | |
| expired | boolean | no | true once the closing date has passed. |
EmployeeProfileUpdaterequest body15 fields
Only the keys you send are changed. Job title, department, manager, level, employment type and work location are not read here: they change through a job change.
| Field | Type | Required | Note |
|---|---|---|---|
| preferredName | string | optional, null clears it | |
| legalName | string | optional, null clears it | |
| nationality | string | optional, null clears it | |
| costCenter | string | optional, null clears it | |
| legalEntity | string | optional, null clears it | |
| noticePeriod | string | optional, null clears it | |
| rightToWorkStatus | string: verified | pending | expired | not_required | optional, null clears it | Any other value answers 400. |
| hireDate | string (date) | optional, null clears it | A real calendar date, or the answer is 400. The same for every date below. |
| originalHireDate | string (date) | optional, null clears it | |
| probationEndDate | string (date) | optional, null clears it | |
| contractEndDate | string (date) | optional, null clears it | |
| rightToWorkVerifiedAt | string (date) | optional, null clears it | |
| rightToWorkExpiresAt | string (date) | optional, null clears it | |
| dateOfBirth | string (date) | optional, null clears it | Stored encrypted. |
| homeAddress | string | optional, null clears it | At most 1000 characters. Stored encrypted. |
EmergencyContactInputrequest body3 fields
One entry of { contacts: [...] }. A call replaces the whole list: at most 5, kept in the order sent.
| Field | Type | Required | Note |
|---|---|---|---|
| name | string | required | |
| relationship | string | optional | |
| phone | string | optional | At most 40 characters. |
JobChangeCreaterequest body4 fields
| Field | Type | Required | Note |
|---|---|---|---|
| type | string: promotion | transfer | manager_change | title_change | other | required | |
| effectiveDate | string (date) | optional | Default today. A later date stores the change as scheduled; it is applied on that day. |
| changes | object | required | At least one of position, department, level, employmentType, workLocation (strings; null clears) and managerId (a user id; null removes the manager). |
| reason | string | optional | At most 1000 characters. |
MyDetailsUpdaterequest body4 fields
What a person may change on their own file. At least one key is needed, or the answer is 400.
| Field | Type | Required | Note |
|---|---|---|---|
| phoneNumber | string | optional, null clears it | At most 40 characters. |
| personalEmail | string (email) | optional, null clears it | Must be an email address and must differ from the work email. |
| preferredName | string | optional, null clears it | |
| homeAddress | string | optional, null clears it | At most 1000 characters. Stored encrypted. |
CompensationCreaterequest body6 fields
| Field | Type | Required | Note |
|---|---|---|---|
| amount | number | required | Greater than 0 and at most 10000000000. |
| currency | string | required | Three letters; upper-cased. |
| effectiveDate | string (date) | optional | Default today. |
| payPeriod | string: annual | monthly | hourly | optional | Default annual. |
| bonusPct | number | optional | 0 to 999. |
| reason | string | optional |
EmployeeDocumentWriterequest body4 fields
The entry a file is then uploaded to. An update (PUT on the document) takes the same keys and changes only those sent.
| Field | Type | Required | Note |
|---|---|---|---|
| name | string | required on create | Characters that cannot be in a file name become spaces; cut to 180 characters. |
| category | string: contract | offer | job_change | policy | certificate | review | letter | other | optional | Default other. |
| visibility | string: hr | employee | manager | optional | Default hr. employee means HR and the person; manager means HR, the person and their manager. |
| expiresAt | string (date) | optional, null clears it |
LeaveRequestCreaterequest body10 fields
Whole or half days over a range, or hours on one day when minutes is sent.
| Field | Type | Required | Note |
|---|---|---|---|
| leaveTypeId | integer | required | A type that is in use. |
| startDate | string (date) | required | |
| endDate | string (date) | optional | Default startDate. Not before startDate and at most 366 days after it. With minutes it must be the same day. |
| startHalf | boolean | optional | The first day is a half day. |
| endHalf | boolean | optional | The last day is a half day. |
| minutes | integer | optional | Time off by the hour: at least 15, and it must end on the day it starts. |
| startTime | string | required with minutes | HH:MM. |
| note | string | optional | At most 500 characters. |
| repeatWeeks | integer | optional | 2 to 12: the same one-day request on that weekday for this many weeks. Weeks that hold no working day are reported in skipped. |
| replaceIds | integer[] | optional | At most 20 of your own bookings by the hour that this whole-day request replaces. |
LeaveDecisionrequest body2 fields
| Field | Type | Required | Note |
|---|---|---|---|
| decision | string: approve | decline | required | |
| note | string | required for decline | At most 500 characters. Shown to the person. |
LeaveTypeWriterequest body14 fields
Create and update take the same keys, and an update sets every one of them: a key left out takes its default.
| Field | Type | Required | Note |
|---|---|---|---|
| name | string | required | At most 60 characters. |
| tracksBalance | boolean | optional | Default true. When false, annualDays and carryOverMaxDays are stored as 0. |
| annualDays | number | optional | 0 to 366. Default 0. |
| accrual | string: upfront | monthly | optional | Default upfront; any other value is stored as upfront. |
| carryOverMaxDays | number | optional | 0 to 366. Default 0. |
| paid | boolean | optional | Default true. |
| requiresApproval | boolean | optional | Default true. |
| allowHours | boolean | optional | Default true. |
| allowNegative | boolean | optional | Default false. |
| minPartMinutes | integer | optional, null clears it | The smallest amount by the hour: 15 to 1440. |
| maxPartMinutes | integer | optional, null clears it | The most by the hour in one request: 15 to 1440, not less than minPartMinutes. |
| isActive | boolean | optional | Default true. |
| sortOrder | integer | optional | Default 0. |
| accrueFrom | string (date) | optional | Create only: the day balances start to build from. Kept between 1 January of this year and today; default 1 January. |
HolidayCalendarWriterequest body7 fields
Create and update take the same keys. The holidays sent replace the stored list.
| Field | Type | Required | Note |
|---|---|---|---|
| name | string | required | |
| location | string | optional, null clears it | The work location this calendar applies to. |
| workDays | integer[] | optional | Days of the week as 0 (Sunday) to 6 (Saturday). Default 1 to 5. |
| holidays | object[] | optional | Each { date:string (YYYY-MM-DD), name:string }, both required. At most 400, and no date twice. |
| hoursPerDay | number | optional | 1 to 24. |
| dayStart | string | optional | HH:MM. |
| isDefault | boolean | optional | true makes this the default calendar. The only calendar is always the default. |
LeaveBalanceAdjustrequest body3 fields
| Field | Type | Required | Note |
|---|---|---|---|
| leaveTypeId | integer | required | A type that tracks a balance. |
| days | number | required | Not 0, between -366 and 366; a negative number removes days. |
| note | string | required | Why the balance is changed. |
GoalWriterequest body8 fields
Create and update take the same keys; an update changes only the keys you send. A person can have at most 50 goals.
| Field | Type | Required | Note |
|---|---|---|---|
| title | string | required on create | |
| userId | integer | optional | Create only: whose goal it is. Default yourself. |
| description | string | optional, null clears it | At most 2000 characters. |
| period | string | optional, null clears it | At most 40 characters. |
| dueDate | string (date) | optional, null clears it | |
| status | string: on_track | at_risk | done | dropped | optional | done sets progress to 100. |
| progress | integer | optional | 0 to 100. 100 with no status sets status to done. |
| weight | integer | optional, null clears it | 0 to 100. |
ReviewCycleWriterequest body10 fields
Create and update take the same keys. The questions, department, rating and feedback options can be changed only while the cycle is a draft; a closed cycle cannot be changed.
| Field | Type | Required | Note |
|---|---|---|---|
| name | string | required | |
| periodLabel | string | optional, null clears it | At most 60 characters. |
| selfDueDate | string (date) | optional, null clears it | |
| managerDueDate | string (date) | optional, null clears it | Not before selfDueDate. |
| department | string | optional, null clears it | Limits the cycle to one department. |
| questions | object[] | optional | 1 to 12, each { label:string (required), key?:string, help?:string (at most 300 characters) }. The default questions when left out. |
| includeRating | boolean | optional | Default true. |
| calibration | boolean | optional | Default false. Takes effect only with includeRating. |
| goalRatings | boolean | optional | Default false. |
| peerFeedback | string: off | reviewer | person | optional | Default off. Any other value answers 400. |
SurveyWriterequest body5 fields
Create and update take the same keys. The questions and the department can be changed only while the survey is a draft; a closed survey cannot be changed.
| Field | Type | Required | Note |
|---|---|---|---|
| title | string | required | |
| intro | string | optional, null clears it | At most 2000 characters. |
| department | string | optional, null clears it | Limits the survey to one department. |
| closesAt | string (date) | optional, null clears it | Not in the past. |
| questions | object[] | optional | 1 to 20, each { label:string (required, at most 300 characters), type: scale | enps | text (required), key?:string }. The default questions when left out. |
SensitiveFieldRevealrequest body1 field
| Field | Type | Required | Note |
|---|---|---|---|
| field | string: dateOfBirth | homeAddress | required | Any other value is refused with 400. |
HrAuthorityWriterequest body3 fields
Which system holds the people data: this instance, or a connected HR system.
| Field | Type | Required | Note |
|---|---|---|---|
| mode | string: zonitix | external | required | Any other value is refused with 400. |
| providerId | integer | required for external | A connected HR system; any other id is refused with 400. Not read for zonitix. |
| fields | object | optional | Per field: the field key, and zonitix or external as its value. |
HrRetentionWriterequest body1 field
| Field | Type | Required | Note |
|---|---|---|---|
| months | integer | required | 0 switches retention off; otherwise a whole number from 6 to 240. Anything else is refused with 400. |
CompensationVoidrequest body1 field
| Field | Type | Required | Note |
|---|---|---|---|
| reason | string | required | Cut to 255 characters; blank is refused with 400. |
LeaveApproveManyrequest body1 field
| Field | Type | Required | Note |
|---|---|---|---|
| ids | integer[] | required | 1 to 50 request ids. An id sent twice is handled once. |
LeaveDeclineItemrequest body2 fields
| Field | Type | Required | Note |
|---|---|---|---|
| id | integer | required | A request id. |
| note | string | required | The reason the person reads; cut to 500 characters. |
LeaveDeclineManyrequest body1 field
| Field | Type | Required | Note |
|---|---|---|---|
| items | LeaveDeclineItem[] | required | 1 to 50 items. When any item has no note, the whole call is refused with 400 and nothing is declined. |
FeedbackRequestrequest body1 field
| Field | Type | Required | Note |
|---|---|---|---|
| userIds | integer[] | required | Active colleagues; not the person reviewed and not the reviewer. |
ReviewerReassignrequest body1 field
| Field | Type | Required | Note |
|---|---|---|---|
| reviewerId | integer | required | An active person other than the person reviewed. |