Microsoft 365 Organizational Data Service - Attribute reference

Microsoft 365 Organizational Data Service supports two types of organizational data attributes: reserved attributes and custom attributes.

Reserved attributes

Reserved attributes are attributes with a predefined meaning in Microsoft 365. Microsoft defines what each attribute represents so that supported Microsoft applications and services can consistently recognize and use the data.

For example, attributes such as Organization, Job Title, Cost Center, and Company have an established meaning. When you map data from your source system to a reserved attribute, Microsoft 365 understands what that data represents and supported experiences can use it accordingly.

Use a reserved attribute when your organizational data corresponds to an attribute already defined by Microsoft 365.

Use the table below to identify the appropriate reserved attribute for your data and whether the downstream apps support it (Yes or No).

Reserved attribute name	Microsoft 365 Profile	Viva Insights (including Copilot Dashboard)	Viva Glint	People Skills
Microsoft_PersonEmail	Yes	Yes	Yes	No
Microsoft_FirstName	Yes	No	Yes	No
Microsoft_LastName	Yes	No	Yes	No
Microsoft_DisplayName	Yes	No	Yes	No
Microsoft_JobTitle	Yes	Yes	Yes	No
Microsoft_JobDiscipline	Yes	Yes	Yes	No
Microsoft_LevelDesignation	Yes	Yes	Yes	No
Microsoft_Layer	Yes	Yes	Yes	No
Microsoft_Company	Yes	Yes	Yes	No
Microsoft_CompanyCode	Yes	Yes	Yes	No
Microsoft_Organization	Yes	Yes	Yes	No
Microsoft_CompanyOfficeLocation	Yes	Yes	Yes	No
Microsoft_CompanyPostOfficeBox	Yes	Yes	Yes	No
Microsoft_CompanyOfficeStreet	Yes	Yes	Yes	No
Microsoft_CompanyOfficeCity	Yes	Yes	Yes	No
Microsoft_CompanyOfficeState	Yes	Yes	Yes	No
Microsoft_CompanyOfficeCountryOrRegion	Yes	Yes	Yes	No
Microsoft_CompanyOfficePostalCode	Yes	Yes	Yes	No
Microsoft_ManagerEmail	Yes	Yes	Yes	No
Microsoft_EmploymentType	Yes	Yes	Yes	No
Microsoft_SecondaryJobTitle	Yes	No	No	Yes
Microsoft_HireDate	Yes	Yes	Yes	No
Microsoft_EmployeeID	Yes	No	Yes	No
Microsoft_CostCenter	Yes	Yes	Yes	No
Microsoft_Division	Yes	Yes	Yes	No
Microsoft_Phone	Yes	No	No	No
Microsoft_AssistantsEmail	Yes	No	No	No
Microsoft_DotLineManagersEmailAndLabel	Yes	No	No	No
Microsoft_UserSkillNames	No	No	No	Yes
Microsoft_HourlyRate	No	Yes	No	No
Microsoft_SupervisorIndicator	No	Yes	Yes	No
Microsoft_WeeklyBadgeOnsiteDays	No	Yes	No	No
Microsoft_GlintEmploymentStatus	No	No	Yes	No
Microsoft_ManagerID	No	No	Yes	No
Microsoft_EndDate	No	No	Yes	No
Microsoft_EmploymentStatus	No	Yes	No	No

Attribute description

Reserved attribute name	Description	Data type	Example
Microsoft_PersonEmail	Unique identifier for an employee record. It can be the employee's primary SMTP address or email alias.	Email	person.name@contoso.com
Microsoft_FirstName	First name of the employee.	String	Alexa
Microsoft_LastName	Last name of the employee.	String	Smith
Microsoft_DisplayName	Preferred name of employee to display. This is the public display name an employee chooses to list.	String	Alexa Smith
Microsoft_JobTitle	The public facing job title of the employee.	String	Software engineer
Microsoft_JobDiscipline	The discipline that an employee belongs to. For more actionable insights, avoid using too few or too many unique Job disciplines. This is the public job discipline.	String	Finance management
Microsoft_LevelDesignation	Level that represents an employee's experience, management level, or seniority within the organization. This is whatever public level designation your company uses.	String	Director
Microsoft_Layer	An employee's position within the organizational hierarchy, expressed as their distance from the top leader of the organization. For example, the CEO is at Layer 0. Avoid using too few or too many unique layers. This is the layer that's publicly available in your company.	Integer	2
Microsoft_Company	The company name.	String	Contoso
Microsoft_CompanyCode	The legal entity number of the company or its subdivision.	String	A2518
Microsoft_Organization	The internal organization or department name that an employee belongs to.	String	Financial Planning and Analysis
Microsoft_CompanyOfficeLocation	An employee's company office location. This is a location code, like a building number, floor, or room. This shouldn't be an employee's home office or personal address.	String	2N
Microsoft_CompanyPostOfficeBox	The publicly available company office box number.	String	PO Box 12
Microsoft_CompanyOfficeStreet	The publicly available company office street address.	String	NE 12th Street
Microsoft_CompanyOfficeCity	The publicly available office address city.	String	Redmond
Microsoft_CompanyOfficeState	The publicly available company office state.	String	Washington
Microsoft_CompanyOfficeCountryOrRegion	The publicly available company office country or region. It's a free-format string value, for example, "United States".	String	United States
Microsoft_CompanyOfficePostalCode	The publicly available company office postal code.	String	98004
Microsoft_ManagerEmail	Unique identifier for an employee's manager. It can be the manager's primary SMTP address or email alias. For CEOs, this can be left blank.	Email	manager.name@contoso.com
Microsoft_EmploymentType	Used to classify employees based on their employment type.	String	Regular
Microsoft_SecondaryJobTitle	The secondary job title for the employee.	String	Software engineer
Microsoft_HireDate	The date an employee began employment. If an employee has multiple hire dates, it's best to use the most recent hire date. Viva Glint uses Hire Date to derive Tenure groups.	DateTime	12/31/2021
Microsoft_EmployeeID	A unique identifier assigned to each employee.	String	E123456
Microsoft_CostCenter	The financial cost center to which the employee is assigned.	String	CC-7890
Microsoft_Division	The division or business unit the employee belongs to.	String	Human Resources
Microsoft_Phone	The employee's work phone number.	String	123-456-7890
Microsoft_DotLineManagersEmailAndLabel	Dotted-line manager who oversees an employee's work across projects or functions without being their direct manager, along with their relationship label. Supports multiple email or string values separated by semicolons. TupleList: Email | String	mgr1@contoso.com | tech lead; mgr2@contoso.com | project lead
Microsoft_AssistantsEmail	Designated support person for an employee, who is typically an executive or senior leader. Responsible for calendar management, coordination, and administrative support.	TupleList: Email	adam@contoso.com; alex@contoso.com
Microsoft_UserSkillNames	Skills the employee has, separated by a semi-colon. This value is used for Viva Skills inferencing, so it's important to make sure the field uploaded here is a field that you want to use to generate skills for your users.	String	Project management; organization
Microsoft_HourlyRate	An employee's salary represented as an hourly rate.	Double	50.25
Microsoft_SupervisorIndicator	The manager status of each employee as IC (individual contributor), Mngr (manager), or Mngr+ (manager of managers).	String (IC/Mngr/Mngr+)	Mngr
Microsoft_WeeklyBadgeOnsiteDays	The actual average number of days per week that an employee works at the company's main worksite. Must be a number between 0 and 7.	Integer	1
Microsoft_ManagerID	The employee ID of the manager.	String	E246801
Microsoft_EndDate	The date when an employee's association with the organization ends.	DateTime	12/31/2021
Microsoft_EmploymentStatus	Indicates the current employment status of an individual within the organization.	String	Active
Microsoft_GlintEmploymentStatus	Indicates the current employment status of an employee within the organization. Must be "ACTIVE" or "INACTIVE", in all caps.	String	ACTIVE

Attribute to app mapping

Reserved attribute name	Property in Microsoft 365 User Profile schema	Property in Viva Insights
Microsoft_PersonEmail	N/A The email is converted to the Microsoft Entra objectId of the end user and is used for internal processing.	PersonID
Microsoft_ManagerEmail	positions -> manager -> userId The email is converted to the Microsoft Entra objectId for the manager and is stored in the Microsoft 365 User Profile.	ManagerID
Microsoft_DotLineManagersEmailAndLabel	positions->colleagues->userid, relationship = dotlinemanager	N/A
Microsoft_AssistantsEmail	positions->colleagues->userid, relationship = assistant	N/A
Microsoft_Organization	positions -> positionDetail -> companyDetail -> department	Organization
Microsoft_LevelDesignation	positions -> positionDetail -> level	LevelDesignation
Microsoft_JobDiscipline	positions -> positionDetail -> role	FunctionType
Microsoft_Layer	positions -> positionDetail -> layer	Layer
Microsoft_FirstName	names -> first	N/A
Microsoft_LastName	names -> last	N/A
Microsoft_DisplayName	names -> displayName	N/A
Microsoft_JobTitle	positions -> positionDetail -> jobTitle	EmployeeJobTitle
Microsoft_CompanyOfficeLocation	positions -> positionDetail -> companyDetail -> officeLocation	Location
Microsoft_CompanyPostOfficeBox	positions -> positionDetail -> companyDetail -> physicalAddress -> postOfficeBox	CompanyPostOfficeBox
Microsoft_CompanyOfficeStreet	positions -> positionDetail -> companyDetail -> physicalAddress -> street	CompanyOfficeStreet
Microsoft_CompanyOfficeCity	positions -> positionDetail -> companyDetail -> physicalAddress -> city	CompanyOfficeCity
Microsoft_CompanyOfficeState	positions -> positionDetail -> companyDetail -> physicalAddress -> state	CompanyOfficeState
Microsoft_CompanyOfficeCountryOrRegion	positions -> positionDetail -> companyDetail -> physicalAddress -> countryOrRegion	CountryOrRegion
Microsoft_CompanyOfficePostalCode	positions -> positionDetail -> companyDetail -> physicalAddress -> postalCode	CompanyOfficePostalCode
Microsoft_Company	positions -> positionDetail -> companyDetail -> displayName	OrgCompany
Microsoft_CompanyCode	positions -> positionDetail -> companyDetail ->companyCode	OrgCompanyCode
Microsoft_SecondaryJobTitle	positions -> positionDetail -> secondaryJobTitle	N/A
Microsoft_EmploymentType	positions->positionDetail->EmployeeType	EmploymentType
Microsoft_HireDate	anniversaries->date[type='originalHireDate']	HireDate
Microsoft_EmployeeID	positions->positionDetail->employeeid	N/A
Microsoft_CostCenter	positions-> positionDetail ->company->costcenter	N/A
Microsoft_Division	positions-> positionDetail ->company->division	N/A
Microsoft_Phone	phones->number(type=business)	N/A

Custom attributes

Custom attributes are attributes that are specific to your organization's data and don't have a predefined meaning in Microsoft 365.

For example, your organization might maintain attributes such as Workforce Segment, Leadership Program, or Employee Population that are meaningful to your business but aren't represented by an existing reserved attribute.

Use a custom attribute when there isn't an appropriate reserved attribute to map for the information you want to import.

How to choose attributes

When preparing your organizational data:

• Use a reserved attribute when one matches the meaning of your source data.

• Use a custom attribute when no reserved attribute accurately represents the data.

• Don't map data to a reserved attribute simply because the names are similar. The meaning of the data should align with the definition of the reserved attribute.