---
title: HiBob field mapping
description: The message tokens and employee profile fields Pyn can fill from HiBob when HiBob is connected, the Bob field behind each one, which other sources can supply it, and what to check when a value does not show.
sidebar:
  order: 1
area: integrations
feature: hibob
appPath: /settings/integrations/installed
lastVerified: 2026-11-15
version: "2026-11-06"
audience: admin
related:
  - flows/steps/reference-tokens
  - integrations/hibob
  - integrations/hris-fields
  - directory/employees/reference-employee-properties
  - directory/employees/fix-missing-details
---

A token in a message, such as `principal.preferredName` or `principal.managerName`, reads a field on the employee's profile in Pyn. When HiBob is connected, Pyn can fill those profile fields from Bob. Whether a field has a value depends on what your Bob tenant holds, what the connected Bob account can view, and which other sources are connected. Use the tables to trace a token back to the Bob field to fill in, or to correct, in Bob.

## Tokens and the Bob fields behind them

Select **Insert token** in the editor toolbar, or type `@`, and the list shows each token by its name under **principal** (the enrolled employee) and **recipient** (the person receiving the message). Each row is a token Pyn can fill from Bob, not one that always has a value: when the profile field is empty, the token shows its fallback. Every `principal` token below with a `recipient` twin in the list reads the same field for the recipient.

| Token | Profile field it reads | Bob field id |
| --- | --- | --- |
| `principal.preferredName` (listed as **Preferred Name**) | **Preferred Name**, else the first word of **Display Name** | `root.displayName` |
| `principal.firstName` | First word of **Display Name** | `root.displayName` |
| `principal.preferredFullName` | **Preferred Name** and surname, else **Display Name** | `root.displayName` |
| `principal.legalName` | **Legal Name** | `root.fullName` |
| `principal.jobTitle` | **Job Title** | `work.title` |
| `principal.department` | **Department** | `work.department` |
| `principal.location` | **Location** | `work.site`, else `address.city` |
| `principal.startDate`, `principal.startDate.dayAfter`, `principal.startDate.nextBusinessDay`, `principal.nextAnniversary` | **Start Date** | `work.startDate` |
| `principal.tenure` | **Tenure Date**, else **Start Date** | `work.originalStartDate`, else `work.startDate` |
| `principal.birthday`, `principal.nextBirthday` | **Birthday** | `personal.shortBirthDate` |
| `principal.managerName`, `principal.managerPreferredName`, `principal.managerEmail` | The **Manager**'s **Display Name** and **Primary Email Address** | `work.reportsTo` picks the manager; their own `root.displayName` and `root.email` fill the values |
| `principal.hrbp.name`, `principal.hrbp.preferredName`, `principal.hrbp.preferredFullName`, `principal.hrbp.email` | The **HRBP**'s name and email | `employee.hrbp` picks the HRBP; their own `root.displayName` and `root.email` fill the values |
| `principal.buddy.name`, `principal.buddy.preferredName`, `principal.buddy.preferredFullName`, `principal.buddy.email`, `principal.buddy.startDate.nextBusinessDay` | The **Buddy**'s name, email and start date | Your buddy custom field picks the buddy; their own `root.displayName`, `root.email` and `work.startDate` fill the values |

Bob has no preferred name field that Pyn reads, so the preferred-name tokens show the first word of Bob's Display name, unless another source supplies a preferred name.

These tokens in the list have no HiBob source: `date.reference`, which is the enrollment's reference date, and `recipient.surveyLink`.

For any other profile field, such as **Probation End Date** or a Bob custom field that Pyn support has mapped, select **Insert token**, then **Employee Field…**, and choose the field. In a Raw HTML email, `principal.email` reads `root.email`, `principal.personalEmail` reads `home.privateEmail`, `principal.endDate` reads `internal.terminationDate` and `principal.country` reads `address.country`. See [Tokens](https://support.pyn.ai/flows/steps/reference-tokens/) for every token and its fallback.

## Profile fields HiBob can fill

The first column is the field's label on the employee profile in Pyn. Each row is a field Pyn can fill from Bob, not one every profile has: a field stays empty when Bob has no value or the connected account cannot view it, and another source can supply it instead. The Bob field id is the name Bob's API uses for the field.

| Pyn field | Field in Bob | Bob field id | Notes |
| --- | --- | --- | --- |
| **Display Name** | Display name | `root.displayName` | Falls back to Full name, then First name and Last name. |
| **Legal Name** | Full name | `root.fullName` | Falls back to First name and Last name (`root.firstName`, `root.surname`). |
| **Primary Email Address** | Email | `root.email` | The work address messages go to. Also used to match records. |
| **Personal Email Address** | Personal email | `home.privateEmail` | Used to match a pre-hire who has no work address. |
| **Job Title** | Job title | `work.title` | |
| **Department** | Department | `work.department` | The value as Bob shows it, not its list id. |
| **Location** | Site | `work.site` | Falls back to the Address city (`address.city`). |
| **Primary Country** | Country | `address.country` | From the address. |
| **Postal Code** | Postal code | `address.postalCode` | From the address. |
| **Time Zone** | None | | Worked out from country and postal code; see below. |
| **Birthday** | Date of birth | `personal.shortBirthDate` | Day and month only. |
| **Start Date** | Start date | `work.startDate` | |
| **Tenure Date** | Original start date, else Start date | `work.originalStartDate`, `work.startDate` | Counts from Bob's original start date when it has one, otherwise the same as **Start Date**. |
| **Termination Date** | Termination date | `internal.terminationDate` | |
| **Probation End Date** | Probation end date | `internal.probationEndDate` | |
| **Original Start Date in HiBob** | Original start date | `work.originalStartDate` | A HiBob-only property. Feeds **Tenure Date**. |
| **Active status** | Lifecycle status, then Status | `internal.lifecycleStatus`, `internal.status` | A lifecycle status containing "leave" is **On Leave**. Otherwise a Status of Active, or none, is **Active**, and anything else is **Inactive**. |
| **Manager** | Reports to | `work.reportsTo` | Matched to the manager's Bob record. See [Manager](#manager) below. |
| **HRBP** | HRBP | `employee.hrbp` | Matched to the HRBP's Bob record. |
| **Buddy** | Your buddy field | A custom field | Bob has no standard buddy field. Pyn support sets which custom field holds it. |
| Custom fields | The field you choose | Any field id | Read as text, yes/no, a date or a number. Pyn support maps each one for you. |

Pyn does not read these from Bob: **Preferred Name**, **Avatar Image**, **Secondary Email Address**, **Employment Type**, **Business Unit**, **Division**, **Team** and **Mentor**. Bob's employment type and contract fields are not mapped to **Employment Type**; Pyn support can map either one as a custom field instead. Any other custom field in Bob, such as a "Manager ID" field, is ignored unless it is mapped.

### Manager

Pyn takes the id inside **Reports to** and finds the Bob employee with that id. When Bob returns no id, Pyn uses the manager's **Employee ID** from Bob (`work.reportsToIdInCompany`) and matches it to the person with that **Employee ID** (`work.employeeIdInCompany`) in the same Bob company. The manager must be in the sync too, so the connected Bob account needs view access to their record.

### Time zone

Pyn reads no time zone from Bob. It works one out from **Primary Country** and **Postal Code**: the postal code for the United States, Canada and Australia, and the country alone where it has a single time zone. For other countries with more than one time zone, Pyn uses the person's Slack time zone where they have one; otherwise **Time Zone** stays empty, and a step scheduled in the recipient's time zone sends in the workspace time zone instead.

## How the sync runs

A change in Bob reaches Pyn, and the tokens in the next message sent, within about an hour. A run where nothing changed in Bob is recorded under **History** as "Successfully integrated to HiBob. No employee changes found". Pyn reads from Bob only and never writes back.

Leavers stay in the sync, so their termination dates arrive. A person who disappears from Bob's results is marked **Removed** and becomes **Terminated**.

## Troubleshooting

| What you see | What to check |
| --- | --- |
| A token shows its fallback, such as "Manager" or "department" | The profile field behind it is empty. Open the person in [Employees](https://support.pyn.ai/directory/employees/) and check the field, then the rows below. Other connected sources can also fill some fields; the profile's **Sources** tab lists every record behind a person. |
| A field is filled in Bob but empty in Pyn | Open the HiBob integration under **Installed** and select **Advanced**. **Fields in Report** lists what Bob returned and for how many people. A missing field means the service user's permission group, or your own account if you signed in with **Connect with HiBob**, cannot view it. Bob leaves such a field out without an error. |
| **Manager** is empty | **Reports to** is empty in Bob, the permission group cannot view it, or the manager is not visible to the service user. A custom field holding a manager id is not read. |
| **Location** shows a city | The person has no Site in Bob, so Pyn used the address city. |
| A Bob custom field is missing | Custom fields are read only once Pyn support maps them. |
| A change in Bob has not arrived | Wait for the next hourly refresh and check **History** on the integration. |

## Related

- [Tokens](https://support.pyn.ai/flows/steps/reference-tokens/) for every token, its fallback and its formatting.
- [HiBob](https://support.pyn.ai/integrations/hibob/) to connect Bob and grant the permissions Pyn needs.
- [HRIS fields](https://support.pyn.ai/integrations/hris-fields/) to compare HiBob with the other sources.
- [Employee properties](https://support.pyn.ai/directory/employees/reference-employee-properties/) for every Pyn field.
- [Fix a missing manager, time zone or email](https://support.pyn.ai/directory/employees/fix-missing-details/) to put a value right.
