---
title: "Employee properties"
description: "Every field on an employee, the relations between employees, the external ids that tie a profile to its sources, how the lifecycle stage is decided and how a time zone is resolved."
sidebar:
  order: 3
area: directory
feature: employees
appPath: /directory/home
lastVerified: 2026-10-22
version: "2026-10-16"
audience: admin
related:
  - directory/employees/fix-missing-details
  - directory/employees/upload-employees-from-a-spreadsheet
  - directory/employee-groups/reference-group-types
intercom:
  - id: "6024089"
    title: "How does Pyn determine a message recipient's time zone?"
    url: https://intercom.help/pyn/en/articles/6024089-how-does-pyn-determine-a-message-recipient-s-time-zone
    note: draws on
---

An employee profile is a fixed set of properties plus any custom fields your HRIS adds. The key in the first column is the column header Pyn expects in an Employee File upload and the name a token uses.

## Properties

| Key | Label | Notes |
| --- | --- | --- |
| `displayName` | Display Name | The full name shown everywhere. |
| `preferredName` | Preferred Name | Used by tokens such as the first name in a greeting. |
| `legalName` | Legal Name | For documents. |
| `jobTitle` | Job Title | |
| `primaryEmail` | Primary Email Address | The work address messages go to. Required on an upload. |
| `personalEmail` | Personal Email Address | Shown in italics in lists when there is no work address. |
| `secondaryEmail` | Secondary Email Address | |
| `avatarUri` | Avatar Image | A URL. Initials are shown when empty. |
| `startDate` | Start Date | Most recent or upcoming start. `yyyy-MM-dd`. Drives Onboarding and anniversary triggers and the Upcoming view. |
| `terminationDate` | Termination Date | `yyyy-MM-dd`. |
| `tenureDate` | Tenure Date | Original start for seniority, when it differs from Start Date. |
| `probationEndDate` | Probation End Date | Shown only when a source supplies it. |
| `birthday` | Birthday | `MM-dd` on the profile; an upload also accepts `dd/MM` and `yyyy-MM-dd`. |
| `businessUnit`, `department`, `division`, `location`, `team` | Business Unit, Department, Division, Location, Team | Free text. Department, Division, Location and Country are demographics from the start. |
| `employmentType` | Employment Type | Free text such as Full-Time or Contractor. A demographic from the start. |
| `jobClass` | Job Class | Free text; can be a demographic. |
| `country` | Primary Country | ISO code on the profile; an upload accepts a name. |
| `postalCode` | Postal Code | Used to resolve a time zone for the US, Canada and Australia. |
| `timeZone` | Time Zone | IANA name. |
| `locale` | Locale | BCP 47 tag such as `en-US`. Resolved from country when absent. |
| `active` | Active status | **Active**, **Inactive**, **On Leave** or **Removed**. `status` on an upload. |
| `stage` | Lifecycle | Worked out by Pyn; see below. |
| `exempt` | Exempt Status | **Exempt** or **Non-Exempt** (US). |
| `workerType`, `employeeType`, `timeType` | Worker Type, Employee Type, Time Type | **Contingent Worker** / **Employee**; **Fixed Term** / **PEO** / **Regular**; **Full-Time** / **Part-Time**. From Workday and ADP. |
| `removed` | Removed | Set when the person has gone from the source system. |
| `returningEmployee` | Returning Employee | Rehired after leaving (BambooHR). |

An HRIS can add custom fields; they appear at the end of **Details** and in the **Filters** list. A string, boolean or single-select property can become a demographic: [Create a demographic](https://support.pynhq.com/directory/demographics/create-a-demographic/).

## Relations

| Relation | Upload column | Used for |
| --- | --- | --- |
| **Manager** | `managerId` | The Manager recipient and tokens; the **Managers** relationship group. |
| **Buddy** | `buddyId` | The Buddy recipient; the **Buddies** group. |
| **HRBP** | `hrbpId` | The HRBP recipient and tokens; the **HRBPs** group. |
| **Mentor** | `mentorId` | The **Mentors** group. |

Each upload column holds the other person's `employeeId` from the same file. An HRIS supplies its own ids and Pyn matches them.

## External ids and sources

Every source record carries an external key: the system's own id (a BambooHR employee id, a Workday worker id, your `employeeId` in an Employee File) and the person's email. Pyn matches records to one profile on those keys, so a spreadsheet row and an HRIS record with the same work email become one employee. Signing in with an email that matches a profile links the user to it.

Values are merged source by source in this order, first wins: addendum (form answers and webhooks), Workday, BambooHR, ADP, Greenhouse, Ashby, Rippling, HiBob, Pyn Classic, Employee File, Sample Data, Slack. The **Sources** tab on a profile lists the records, and **Disconnect** on one removes it from the merge.

## How the lifecycle stage is decided

Pyn orders the start date, the termination date and today, and reads the stage from the order:

| Dates | Stage |
| --- | --- |
| Removed from the source | **Terminated**, whatever the dates say. |
| Start date in the future (termination absent or earlier) | **Upcoming Joiner** |
| Start date in the past, no termination or termination in the future, active in a source | **Current Active Employee** |
| Start date in the past and the person is inactive | **Terminated**; except within a day of the start date, when they stay **Upcoming Joiner** to cover an HRIS that has not caught up. |
| Termination date in the past | **Terminated** |
| No dates at all | **Current Active Employee** if active, else **Terminated** |

"Active" means the source says so and that source is an employment system. Slack, Google Workspace and Microsoft 365 are not: a person known only to them reads as inactive. An `active` of `leave` keeps the person out of the Active view and in the **Inactive Employees** lifecycle group under the **Lifecycle** demographic.

## How a time zone is resolved

1. The time zone the source supplies, if it is a valid IANA name, a recognised abbreviation or a Windows time-zone name.
2. Otherwise the country and postal code, for the US (ZIP), Canada and Australia.
3. Otherwise the country, if it has a single time zone.
4. Otherwise none. Messages to the person send in the workspace's time zone from **Settings** > **Account Settings**, and an Employee File upload reports the row so you can add a time zone or postal code.

## Related

- [Fix a missing manager, time zone or email](https://support.pynhq.com/directory/employees/fix-missing-details/) for putting a value right.
- [Upload employees from a spreadsheet](https://support.pynhq.com/directory/employees/upload-employees-from-a-spreadsheet/) for the file these keys head.
- [Group types](https://support.pynhq.com/directory/employee-groups/reference-group-types/) for the groups built from these properties.

## Related Intercom articles

- [How does Pyn determine a message recipient's time zone?](https://intercom.help/pyn/en/articles/6024089-how-does-pyn-determine-a-message-recipient-s-time-zone) — draws on