Data foundation entities

This article details each entity and all of the fields that it contains, with mentions of mandatory fields within each entity. You must populate the entities with the data from your HRIS system to be able to import your data into the beqom PaySuite data foundation and start using the platform.

This is a warning message.

The entity file names as well as the field names within the files are case-sensitive. Using the incorrect case will result in a failure of the ingestion attempt. Make sure you respect the case outlined in this document.

Overview

The PaySuite data foundation is comprised of twenty-two (22) entities and thirty-seven (37) enums. The following table lists the twenty-two entities of the data foundation, with their effective dating type and their unique key(s):

List of data foundation enums

Entities marked with * are in the process of being deprecated and should not be used for new data implementations. For more information, see Legacy entities.
Entity name	Effective dating	Unique key(s)	Reference
Worker	None	ExternalId	Worker entity details
Employment	Effective Date	WorkerExternalId	Employment entity details
Organization	None	ExternalId	Organization entity details
CompensationElement	None	ExternalId	CompensationElement entity details
CompensationHistory*	Effective Range	WorkerExternalId CompensationElementExternalId	CompensationHistory entity details
Demographics	Effective Date	WorkerExternalId	Demographics entity details
PayScale	None	ExternalId	PayScale entity details
CostCenter	None	ExternalId	CostCenter entity details
JobArchitecture	None	ExternalId	JobArchitecture entity details
Absence	Effective Range	WorkerExternalId AbsenceType	Absence entity details
PerformanceRatingScales	None	ExternalId	PerformanceRatingScales entity details
PerformanceReviewRating	Effective Range	WorkerExternalId PerformanceRatingScalesExternalId	PerformanceReviewRating entity details
LegalEntity	None	ExternalId	LegalEntity entity details
IndividualPayRange	Effective Date	WorkerExternalId	IndividualPayRange entity details
GoalPlan	None	ExternalId	GoalPlan entity details
Goal	None	ExternalId	Goal entity details
GoalPlanGoalAssignment	None	ExternalId	GoalPlanGoalAssignment entity details
GoalAchievementNew	Effective range	WorkerExternalId GoalExternalId GoalPlanExternalId	GoalAchievementNew entity details
GoalWorkerAssignment	Effective range	WorkerExternalId GoalExternalId GoalPlanExternalId	GoalWorkerAssignment entity details
GoalResult	Effective range	GoalPlanExternalId GoalExternalId	GoalResult entity details
ContractedCompensation	Effective date	WorkerExternalId CompensationElementExternalId	ContractedCompensation entity details
PaidCompensation	Effective range	WorkerExternalId CompensationElementExternalId	PaidCompensation entity details

This is a miscellaneous message.

You can view a visual representation of the Data Foundation here:

Legacy entities

The following table lists legacy entities in the Data Foundation. These entities should not be used for any new implementation. They are, however, still supported for backward compatibility purposes.

Entity name	Replaced by	Impact
CompensationHistory	ContractedCompensation PaidCompensation	Passport > Documents Salary + bonus Compensation history drawer Analytics Hub

Worker entity details

The Worker entity stores one record per person in your organization: the worker's identifier, name details, contact information, language preferences, work and private addresses, and the settings that control whether the worker is active and has a user account. The entity is not effective-dated, so each upload holds the current values. Every other entity that holds worker-specific data refers to a worker through the ExternalId value of this entity.

The following table describes the fields contained in the Worker entity.

This is an note/information message.

The Worker entity file must be present at each data upload AND must contain data at each upload, for the fields marked as mandatory in the below table.

Worker entity details
Field name	Data type	Required	Description	Data example
ExternalId	String	Yes	Unique identifier of the worker. Usually, it is the employee ID.	000123, ABCDEF
LastName	String	Yes	Last name of the worker.	Smith (for a worker named John Richard Smith West II)
SecondaryLastName	String	No	Additional last name of the worker.	West (for a worker named John Richard Smith West II)
FirstName	String	Yes	First name of the worker.	John (for a worker named John Richard Smith West II)
MiddleName	String	No	Middle name of the worker, if any.	Richard (for a worker named John Richard Smith West II)
PreferredName	String	No	Name by which the worker preferred to be called. Can be a nickname.	Johnny (for a worker named John Richard Smith West II)
HonorificPrefix	String	No	Name prefix to be used for the worker.	Mr, Mrs, Dr, Sir
HonorificSuffix	String	No	Name suffix to be used for the worker.	II (for a worker named John Richard Smith West II)
Pronoun	String	No	Preferred pronoun of the worker.	She/her, he/him, etc.
FirstNameLatin	String	No	First name of the worker in Latin alphabet, if the name of the worker is not in Latin alphabet.	Ivan
FirstNamePreferredLatin	String	No	Name by which the worker prefers to be called, in Latin alphabet, if the name of the worker is not in Latin alphabet.	Vanya
LastNameLatin	String	No	Last name of the worker in Latin alphabet, if the name of the worker is not in Latin alphabet.	Petrov
SecondaryLastNameLatin	String	No	Additional last name of the worker in Latin alphabet, if the name of the worker is not in Latin alphabet.	West
MiddleNameLatin	String	No	Middle name of the worker in Latin alphabet, if the name of the worker is not in Latin alphabet.	Sergeevich
FullNameLatin	String	No	Full name of the worker in Latin alphabet, if the name of the worker is not in Latin alphabet.	Ivan Petrov
PrivateEmail	String	No	Personal email address of the worker. Corresponds to the home/primary address for the User service.	john.smith@myemail.com
WorkEmail	String	Yes	Professional email address of the worker. The professional email address must be provided in a valid email format and must be unique.	john.smith@companyemail.com
WorkPhone	String	No	Professional phone number of the worker.	+1 212 555 0199
PrivatePhone	String	No	Personal phone number of worker. Corresponds to the home/primary phone number for the User service.	+1 310 555 0100
PreferredLanguage	ISO enum	No	Preferred language of the worker. The language cannot be updated later for the User service. It must be updated by the user in the platform. If not set during data upload, the default language is used, without impact on the user record.	en
Proficiency	Enum	No	Proficiency of the worker in the preferred language. Proficiency is a customizable enum.	NATIVE
Language2	ISO enum	No	Second language of the worker.	fr
Proficiency2	Enum	No	Proficiency of the worker in the second language. Proficiency is a customizable enum.	FLUENT
Language3	ISO enum	No	Third language of the worker.	de-DE
Proficiency3	Enum	No	Proficiency of the worker in the third language. Proficiency is a customizable enum.	BASIC
WorkMailingAddress	String	No	Professional physical mailing address of the worker.	Company Name 15 Street, New York, USA 10001
WorkStreetAddress	String	No	Full street component of the professional address of the worker; multi-line extended street address information.	3rd Floor Company Name Building 15 Street
WorkPostalCode	String	No	Postal code of the professional address of the worker.	10001
WorkTownCity	String	No	City of the professional address of the worker.	New York
WorkRegionState	String	No	Region/state of the professional address of the worker.	New York
WorkCountry	ISO enum	No	Country of the professional address of the worker. Code of the relevant country in the Country enum.	USA
Timezone	ISO enum	No	Time zone in which the worker is located. The time zone cannot be updated later for the User service. It must be updated by the user in the platform. If not set during data upload, the default time zone is used, without impact on the user record.	Europe/Zurich
PrivateMailingAddress	String	No	Personal address of the worker. Home/primary value for the User service.	3rd Street Santa Monica California 90001
PrivateStreetAddress	String	No	Full street component of the personal address of the worker; multi-line extended street address information. Home/primary value for the User service.	Apart 5a 3rd Street
PrivatePostalCode	String	No	Postal code of the personal address of the worker. Home/primary value for the User service.	90001
PrivateTownCity	String	No	City of the personal address of the worker. Home/primary value for the User service.	Santa Monica
PrivateRegionStatePrivateRegionState	String	No	Region/state of the personal address of the worker. Home/primary value for the User service.	California
PrivateCountry	Enum	No	Country of the personal address of the worker. This is an note/information message. Corresponds to the Location field in the population settings of Performance Management. Code of the relevant country in the Country enum.	USA
PhotoId	String	No	ID of the personnel photo of the worker.	IMG-000123
ProvisionUserAccount	Boolean	Yes	Indicates whether the user is currently active in the system.	true
UserName	String	Yes	User name of the worker in the system. This value must be unique.	jsmith
ProvisionActiveWorker	Boolean	Yes	Indicates whether the worker is currently active.	true
PerformanceEligibility	Boolean	Yes	Indicates whether the worker is eligible for performance review.	true
WorkRegion	String	No	Indicates the region in which the worker works.	EMEA

This is an note/information message.

During IAM synchronization, when the user record is generated, the time zone and the language are set to default time zone and language for the user. In other words, this means that the Timezone and PreferredLanguage fields of the Worker entity are not linked to the behavior of the user settings in the application.

This is a tip message.

You can find an upload file template for the Worker entity attached to this article under the name Worker.csv.

Employment entity details

The Employment entity stores a worker's employment situation from a given date: the organization, legal entity, cost center, and job the worker belongs to, the worker's managers and HR business partner, key employment dates, contract type and status, working time, and any global mobility assignment. Each record applies from its effective date, so you can keep a history of changes to a worker's employment.

The following table describes the fields contained in the Employment entity.

This is an note/information message.

The Employment entity file must be present at each data upload and must contain data at each upload, for the fields marked as mandatory in the below table.

Employment entity details
Field name	Data type	Required	Description	Data example
WorkerExternalId	String	Yes	Unique identifier of the worker. ExternalId value of the worker in the Worker entity.	000123, ABCDEF
StartDateInCompany	Date	No	Start date of the employment in the company.	2010-02-01
DateProbationEnds	Date	No	End date of the probation period.	2010-05-01
DateOfDeath	Date	No	Date of death of the worker.	2026-05-14
DateRetired	Date	No	Date at which the worker retired.	2026-12-31
DateRehire	Date	No	Date at which the worker was rehired.	2021-09-01
DateFirstHire	Date	No	Date at which the worker was first hired, if they were rehired.	2018-03-01
startDateInJob	Date	No	Date at which the worker started their current position.	2024-01-01
DateTermination	Date	No	Date at which the worker left the company.	2026-06-30
OrganizationExternalId	String	Yes	Unique ID of the organization to which the worker is associated. Value of the ExternalId field for the relevant record in the Organization entity. Determines the OrganizationItem for the user in IAM service.	ORG-SALES-EU
LegalEntityExternalId	String	No	Unique ID of the legal entity to which the worker is associated. Value of the ExternalId field for the relevant record in the LegalEntity entity.	LE-FR-01
CostCenterExternalId	String	No	Unique ID of the cost center to which the worker is attached. Value of the ExternalId field for the relevant record in the CostCenter entity	CC-4100
JobArchitectureExternalId	String	No	Unique ID of the job architecture to which the worker is attached. Value of the ExternalId field for the relevant record in the JobArchitecture entity.	JOB-SALES-L3
LineManagerId	String	No	Unique ID of the line manager of the worker. Value of the ExternalId field for the relevant manager in the Worker entity Determines who the user reports to in the IAM service.	000045
MatrixManagerId	String	No	Unique ID of the matrix manager of the worker. Value of the ExternalId field for the matrix manager in the Worker entity.	000078
CommunicationManagerId	String	No	Unique ID of the communication manager of the worker. Value of the ExternalId field for the communication manager in the Worker entity.	000045
CompensationManagerId	String	No	Unique ID of the compensation manager of the worker. Value of the ExternalId field for the compensation manager in the Worker entity.	000045
HrBusinessPartnerId	String	No	Unique ID of the HR business partner associated with the worker. Value of the ExternalId field for the HR business partner in the Worker entity.	000210
HomeCountry	ISO enum	No	Country of origin of the worker. Code of the relevant country in the Country ISO enum.	FRA
HomeCountryCurrency	ISO enum	No	Currency associated with the country of origin of the worker. Code of the relevant currency in the Currency ISO enum.	EUR
PreferredCurrency	Enum	No	Currency in which the worker prefers to be paid. Code of the relevant currency in the Currency ISO enum.	EUR
EmploymentStatus	Enum	No	Employment status of the worker within the company. Code of the relevant employment status in the EmploymentStatus enum. To synchronize with the User service, the value used here must be one of the following: EMPLOYEE CONTRACTOR EXPATRIATE APPRENTICE INTERN TRAINEE TEMPORARY THIRDPARTY	ACTIVE
ContractType	Enum	No	Type of contract under which the worker is employed. Code of the relevant contract type in the ContractType enum.	PERMANENT
ChangeJobReason	String	No	Reason for which the worker changed jobs within the organization.	Promotion
Fte	Number	No	Full-time equivalent.	1.0
WeeklyWorkingHours	Number	No	Number of weekly hours worked by the worker.	40
ContractWorkingHours	Number	No	Contractual number of weekly working hours for the worker.	40
MaterialRiskTaker	Boolean	No	Indicates whether the worker's professional activities have a material impact on the risk profile of the company.	false
GlobalMobilityFlag	String	No	Indicates whether the worker is part of a mobility plan within the organization.	yes
GlobalMobilityId	String	No	Unique mobility ID for the worker.	GM-2026-017
HostCountryCostCenterExternalId	String	No	ID of the cost center related to the host country if the worker is part of a mobility plan. Value of the ExternalId field for the relevant cost center in the CostCenter entity.	CC-SG-200
HostCountryLegalEntityExternalId	String	No	ID of the legal entity related to the host country if the worker is part of a mobility plan.	LE-SG-01
HostAssignmentJobArchitectureExternalId	String	No	ID of the level in the job architecture that the worker occupies in the host country. Value of the ExternalId field for the relevant job architecture in the JobArchitectureExternalId entity.	JOB-SALES-L4
HostAssignmentStartDate	Date	No	Date at which the worker started their assignment in the country.	2026-01-01
HostAssignmentEndDate	Date	No	Date at which the worker ended their assignment in the host country.	2027-12-31
HostCountry	ISO enum	No	Country in which the worker is working if the worker is part of a mobility plan. Code of the relevant country in the Country ISO enum.	SGP
HostCountryCurrency	ISO enum	No	Currency of the country in which the worker is worker if they are part of a mobility plan.	SGD
HostPreferredCurrency	ISO enum	No	Currency in which workers should be paid in the host country.	USD
EffectiveDate	Date	Yes	Date from which the current situation of the worker is effective. Because of the use of the effective date, the entity can contain multiple records for a single worker based on any changes in their personal or professional situation.	2026-01-01

This is a tip message.

You can find an upload file template for the EmploymentStatus entity attached to this article under the name Employment.csv.

Organization entity details

The Organization entity stores the units of your organizational structure, such as departments, divisions, or teams. Each unit can reference a parent unit, which lets you build the organizational hierarchy. Workers are linked to a unit through the Employment entity.

The following table describes the fields contained in the Organization entity.

This is an note/information message.

The Organization entity file must be present at each data upload and must contain data at each upload, for the fields marked as mandatory in the below table.

Organization entity details
Field name	Data type	Mandatory	Description	Data example
ExternalId	String	Yes	Unique identifier of the organization. This value is mandatory and must be unique.	ORG-SALES-EU
OrganizationName	String	Yes	Name of the organization.	Sales Europe
Active	Boolean	Yes	Indicates whether the organization is active.	true
ParentOrganizationId	String	No	ID of the parent organization of the organization, if any.	ORG-SALES
OrganizationCountry	ISO enum	No	Country in which the organization is located. Code of the relevant country in the Country ISO enum.	FRA
OrganizationType	Enum	No	Type of the organization.	DEPARTMENT

This is a tip message.

You can find an upload file template for the Organization entity attached to this article under the name Organization.csv.

CompensationElement entity details

The CompensationElement entity defines the types of pay used in your organization, such as base salary, bonuses, or allowances, together with their properties: type, basis, payment frequency, whether they are recurring, paid in cash, taxable, or a target amount, and the country they apply to. Elements can be grouped through a parent element. The amounts for each worker are stored in the ContractedCompensation and PaidCompensation entities, which refer to this entity.

The following table describes the fields contained in the CompensationElement entity.

This is an note/information message.

The CompensationElement entity file must be present at each data upload. However, it does not have to contain data.

If it does indeed contain data, the fields marked as mandatory must contain data.

CompensationElement entity details
Field name	Data type	Mandatory	Description	Data example
ExternalId	String	Yes	Unique identifier of the compensation element.	BASE_SALARY
CompensationElementName	String	Yes	Name of the compensation element.	Base salary
CompensationElementParentId	String	No	Parent ID of the compensation element.	FIXED_PAY
CompensationElementIsRecurring	Boolean	No	Defines whether the compensation element corresponds to recurring compensation type.	true
CompensationElementFrequency	Enum	No	Indicates the frequency of the at which the compensation element is paid to worker. Code of the relevant frequency in the CompensationElementFrequency enum.	MONTHLY
CompensationElementType	Enum	No	Indicates the type of compensation element. Code of the relevant compensation element type in the CompensationElementType enum.	SALARY
CompensationElementBasis	String	No		Annual
CompensationElementIsTarget	Boolean	No		false
CompensationElementIsCash	Boolean	No		true
CompensationElementIsTaxible	Boolean	No		true
CompensationElementIsActive	Boolean	No		true
CompensationElementCountry	ISO enum	No	Country to which the compensation element is applicable. Code of the relevant country in the Country ISO enum.	FRA

This is a tip message.

You can find an upload file template for the CompensationElement entity attached to this article under the name CompensationElement.csv.

CompensationHistory entity details

The CompensationHistory entity stores contracted and actualized compensation amounts per worker and compensation element over a period of time. This entity is deprecated and has been replaced by the ContractedCompensation and PaidCompensation entities. For more information, see Legacy entities.

The following table describes the fields contained in the CompensationHistory entity.

This is a warning message.

This entity should not be used for any new implementations. It is still available as of now for backward compatibility purposes and it will be removed in a future version.

It is replaced by the following entities: ContractedCompensation and PaidCompensation.

This is an note/information message.

The CompensationHistory entity file must be present at each data upload. However, it does not have to contain data.

If it does indeed contain data, the fields marked as mandatory must contain data.

CompensationHistory entity details
Field name	Data type	Mandatory	Description	Data example
WorkerExternalId	String	Yes	Unique identifier of the worker in the Worker entity.	000123
CompensationElementExternalId	String	Yes	External ID of the compensation element in the CompensationElement entity.	BASE_SALARY
WorkerExternalId	ISO enum	No	Currency in which the compensation record is valued. Code of the relevant currency in the Currency ISO enum. Mandatory if either ContractedAmount or ActualizedAmount is present.	EUR
ContractedAmount	Decimal	No	Annual amount corresponding to the compensation record.	58000
ActualizedAmount	Decimal	No	Actual amount corresponding to the compensation record. Differs from the annual amount because of the date range.	29000
CompensationReason	String	No		Merit increase
MobilityId	String	No		GM-2026-017
Percentage	Decimal	No		10
Unit	String	No	Measurement unit applicable to a specific compensation component, such as hours for hourly wages, shares for equity awards, or a flat amount for allowances.	Annual
Value	Decimal	No		58000
EffectiveRangeStartDate	Date	Yes	Start date of the compensation record. Because the start and end dates define a range, there can be several records per worker.	2025-01-01
EffectiveRangeEndDate	Date	Yes	End date of the compensation record.	2025-06-30

Demographics entity details

The Demographics entity stores personal and diversity attributes of a worker, such as date of birth, gender, marital status, religion, political affiliation, education level, ethnicity, and nationality. Each record applies from its effective date.

The following table describes the fields contained in the Demographics entity.

This is an note/information message.

The DemographicsDemographics entity file must be present at each data upload. However, it does not have to contain data.

If it does indeed contain data, the fields marked as mandatory must contain data.

Demographics entity details
Field name	Data type	Mandatory	Description	Data example
WorkerExternalId	String	Yes	Unique ID of the worker in the Worker entity.	000123
Birthday	Date	No	Date of birth of the worker.	1990-04-12
Gender	Enum	No	Gender of the worker. Code of the relevant gender in the Gender ISO enum.	FEMALE
MaritalStatus	Enum	No	Marital status of the worker. Code of the relevant marital status in the MaritalStatus enum.	MARRIED
Religion	Enum	No	Religion of the worker. Code of the relevant religion in the Religion enum.	CHRISTIANITY
PoliticalAffiliation	Enum	No	Political affiliation of the worker. Code of the relevant political affiliation in the PoliticalAffiliation enum.	NONE
EducationLevel	Enum	No	Education level of the worker. Code of the relevant education level in the EducationLevel enum.	MASTER
Ethnicity	Enum	No	Ethnicity of the worker. Code of the relevant ethnicity in the Ethnicity enum.	HISPANIC
Nationality1	Enum	No	First nationality of the worker. Code of the relevant nationality in the Nationality enum.	FRENCH
Nationality2	Enum	No	Second nationality of the worker. Code of the relevant nationality in the Nationality enum.	SWISS

This is a tip message.

You can find an upload file template for the Demographics entity attached to this article under the name Demographics.csv.

PayScale entity details

The PayScale entity defines the pay scales and grades used in your organization and the salary range attached to each of them: minimum, midpoint, and maximum, with the currency of the range. Jobs are linked to a pay scale through the PayScaleExternalId field of the JobArchitecture entity.

The following table describes the fields contained in the PayScale entity.

This is an note/information message.

The PayScale entity file must be present at each data upload. However, it does not have to contain data.

If it does indeed contain data, the fields marked as mandatory must contain data.

PayScale entity details
Field name	Data type	Mandatory	Description	Data example
ExternalId	String	Yes	External ID of the pay scale.	PS-G7
PaySchedule	String	Yes		Monthly
PayScaleType	Enum	No	Type of the pay scale. Code of the relevant pay scale type in the PayScaleType enum.	SALARIED
PayScaleArea	Enum	No	Area to which the pay scale applies. Code of the relevant pay scale area in the PayScaleArea enum.	FR
PayScaleGroup	Enum	No	Group to which the pay scale belongs. Code of the relevant pay scale group in the PayScaleGroup enum.	G7
PayScaleLevel	Enum	No	Level of the pay scale. Code of the relevant pay scale level in the PayScaleLevel enum.	L2
PayScaleLocalGrade	Enum	No	Local grade of the pay scale. Code of the relevant pay scale local grade in the PayScaleLocalGrade enum.	FR-G7
PayScaleGlobalGrade	Enum	No	Global grade of the pay scale. Code of the relevant pay scale global grade in the PayScaleGlobalGrade enum.	GG7
PayGrade	Enum	No	Pay grade corresponding to the pay scale. Code of the relevant pay grade in the PayGrade enum.	PG7
GradeWidth	Decimal	No	Salary range (grade width) for the specific pay grade.	0.4
PayRangeCurrency	ISO enum	No	Currency in which the pay range is valued. Code of the relevant currency in the Currency ISO enum. Required if any amount field is present (PayRangeMin, PayRangeMid or PayRangeMax).	EUR
PayRangeMin	Decimal	No	Minimum value of the pay range. If a value is present in this field, a value must also be present in PayRangeMax. Additionally, the value in this field must be smaller than the value in PayRangeMax.	52000
PayRangeMid	Decimal	No	Mid value for the pay range.	65000
PayRangeMax	Decimal	No	Maximum value for the pay range. If a value is present in this field, a value must also be present in PayRangeMin. Additionally, the value in this field must be smaller than the value in PayRangeMin.	78000

This is a tip message.

You can find an upload file template for the PayScale entity attached to this article under the name PayScale.csv.

CostCenter entity details

The CostCenter entity stores the cost centers of your organization, with the FTE allocated to them and their value and currency. Each cost center can reference a parent cost center, which lets you build the cost center hierarchy. Workers are linked to a cost center through the Employment entity.

The following table describes the fields contained in the CostCenter entity.

This is an note/information message.

The CostCenter entity file must be present at each data upload. However, it does not have to contain data.

If it does indeed contain data, the fields marked as mandatory must contain data.

CostCenter entity details
Field name	Data type	Mandatory	Description	Data example
ExternalId	String	Yes	ID of the cost center.	CC-4100
CostCenterName	String	Yes	Name of the cost center.	Sales Operations
CostCenterParentId	String	No	Parent ID of the cost center.	CC-4000
CostCenterFte	Number	No		42.5
CostCenterValue	Number	No		2500000
CostCenterCurrency	ISO enum	No	Currency used by the cost center. Code of the relevant currency in the Currency ISO enum.	EUR

This is a tip message.

You can find an upload file template for the CostCenter entity attached to this article under the name CostCenter.csv.

JobArchitecture entity details

The JobArchitecture entity describes the jobs in your organization: job family, function, category, and level, job title and description, evaluation points, and the pay scale that applies to the job. Workers are linked to a job through the Employment entity.

The following table describes the fields contained in the JobArchitecture entity.

This is an note/information message.

The JobArchitecture entity file must be present at each data upload. However, it does not have to contain data.

If it does indeed contain data, the fields marked as mandatory must contain data.

JobArchitecture entity details
Field name	Data type	Mandatory	Description	Data example
ExternalId	String	Yes	Unique ID of the job record.	JOB-SALES-L3
PayScaleExternalId	String	No	ID of the pay scale corresponding to the job. ExternalId value of the relevant pay scale in the PayScale entity.	PS-G7
JobFamily	Enum	No	Family of the job. Code of the relevant family in the JobFamily enum.	SALES
JobFunction	Enum	No	Function of the job. Code of the relevant job function in the JobFunction enum.	ACCOUNT_MGMT
JobCategory	Enum	No	Category of the job. Code of the relevant job category in the JobCategory enum.	PROFESSIONAL
JobLevel	Enum	No	Level of the job. Code of the relevant job level in the JobLevel enum.	L3
JobTitle	String	No	Title of the job. Used when provisioning users in the User service.	Account Manager
JobDescription	String	No	Description of the job.	Manages key customer accounts in the region.
JobEvaluationPoints	Decimal	No		540
JobAlternativeId	String	No	Alternative ID for the job.	HR-JOB-1033

This is a tip message.

You can find an upload file template for the JobArchitecture entity attached to this article under the name JobArchitecture .csv.

Absence entity details

The Absence entity stores the periods during which a worker is absent: the type and reason of the absence, its duration in calendar and working days, and the pro rata factor that applies to the period. Each record covers the period defined by its start and end dates.

The following table describes the fields contained in the Absence entity.

This is an note/information message.

The Absence entity file must be present at each data upload. However, it does not have to contain data.

If it does indeed contain data, the fields marked as mandatory must contain data.

Absence entity details
Field name	Data type	Mandatory	Description	Data example
WorkerExternalId	String	Yes	ID of the worker concerned by the absence. ExternalId of the worker in the Worker entity.	000123
AbsenceType	Enum	Yes	Type of the absence. Code of the absence type in the AbsenceType enum.	Sickness
AbsenceReason	String	No	Reason for the absence.	Medical
AbsenceDays	Decimal	No	Number of days of absence.	10
AbsenceInWorkingDays	Decimal	No	Number of working days of absence.	8
AbsenceProrataFactor	Decimal	No	Prorata factor applied to the absence.	0.5
EffectiveRangeStartDate	Date	Yes	Start date of the absence.	2026-02-02
EffectiveRangeEndDate	Date	Yes	End date of the absence.	2026-02-13

This is a tip message.

You can find an upload file template for the Absence entity attached to this article under the name Absence.csv.

PerformanceRatingScales entity details

The PerformanceRatingScales entity defines the rating scales used in performance reviews and the rating values each scale contains, with their labels, display order, and reporting order. Ratings stored in the PerformanceReviewRating entity refer to this entity.

The following table describes the fields contained in the PerformanceRatingScales entity.

This is an note/information message.

The PerformanceRatingScales entity file must be present at each data upload. However, it does not have to contain data.

If it does indeed contain data, the fields marked as mandatory must contain data.

PerformanceRatingScales entity details
Field name	Data type	Mandatory	Description	Data example
ExternalId	String	Yes	Unique ID of the performance rating scale record.	SCALE-5PT
PerformanceRatingScale	Enum	No	Performance rating scale for the performance record. Code of the relevant performance rating scale in the PerformanceRatingScale enum.	FIVE_POINT
PerformanceRatingId	String	No		4
PerformanceRatingLabel	String	No		Exceeds expectations
PerformanceRatingOrder	Integer	No		4
PerformanceReportingOrder	Integer	No		4

This is a tip message.

You can find an upload file template for the PerformanceRatingScales entity attached to this article under the name PerformanceRatingScales.csv.

PerformanceReviewRating entity details

The PerformanceReviewRating entity stores the performance ratings given to workers for a review period: the rating scale used, the rating and review types, the score, and the review template. Each record covers the period defined by its start and end dates.

The following table describes the fields contained in the PerformanceReviewRating entity.

This is an note/information message.

The PerformanceReviewRating entity file must be present at each data upload. However, it does not have to contain data.

If it does indeed contain data, the fields marked as mandatory must contain data.

PerformanceReviewRating entity details
Field name	Data type	Mandatory	Description	Data example
WorkerExternalId	String	Yes	ID of the worker whom the record concerns. ExternalId value of the worker in the Worker entity.	000123
PerformanceRatingScalesExternalId	String	Yes	ID of the performance rating scale. Code of the relevant performance rating scale in the PerformanceRatingScales entity.	SCALE-5PT
PerformanceRatingType	Enum	Yes	Type of performance rating. Code of the performance rating type in the PerformanceRatingType enum.	OVERALL
PerformanceReviewType	Enum	No	Type of performance review. Code of the relevant performance review type in the PerformanceReviewType enum.	ANNUAL
PerformanceRatingScore	Decimal	No	Performance rating value.	4
PerformanceReviewTemplateId	String	No	Unique ID of the relevant performance review template.	TPL-2026-ANNUAL
PerformanceReviewTemplateName	String	No	Name of the relevant performance review template.	Annual review 2026
EffectiveRangeStartDate	Date	Yes	Start date of the performance review period.	2025-01-01
EffectiveRangeEndDate	Date	Yes	End date of the performance review period.	2025-12-31

This is a tip message.

You can find an upload file template for the PerformanceReviewRating entity attached to this article under the name PerformanceReviewRating.csv.

LegalEntity entity details

The LegalEntity entity stores the legal entities of your organization, that is, the companies that employ your workers. Each legal entity can reference a parent legal entity, which lets you build the legal entity hierarchy. Workers are linked to a legal entity through the Employment entity.

The following table describes the fields contained in the LegalEntity entity.

This is an note/information message.

The LegalEntity entity file must be present at each data upload. However, it does not have to contain data.

If it does indeed contain data, the fields marked as mandatory must contain data.

LegalEntity entity details
Field name	Data type	Mandatory	Description	Data example
ExternalId	String	Yes	Unique ID of the performance rating scale record.	LE-FR-01
LegalEntityName	String	Yes	Name of the legal entity.	beqom France SAS
LegalEntityParentId	String	No	Parent ID of the legal entity.	LE-GROUP

This is a tip message.

You can find an upload file template for the LegalEntity entity attached to this article under the name LegalEntity.csv.

IndividualPayRange entity details

The IndividualPayRange entity stores the pay range that applies to an individual worker, together with the market benchmark range and the worker's local and global grades. Each record applies from its effective date.

The following table describes the fields contained in the IndividualPayRange entity.

This is an note/information message.

The IndividualPayRange entity file must be present at each data upload. However, it does not have to contain data.

If it does indeed contain data, the fields marked as mandatory must contain data.

IndividualPayRange entity details
Field name	Data type	Mandatory	Description	Data example
WorkerExternalId	String	Yes	ID of the worker concerned by the pay range. ExternalId value in the Worker entity.	000123
PayRangeMin	Decimal	No	Minimum value of the pay range. If a value is present in this field, a value must also be provided in the field PayRangeMax. In addition, the value of PayRangeMin must be smaller than the value of PayRangeMax.	52000
PayRangeMax	Decimal	No	Maximal value of the pay range. If a value is present in this field, a value must also be provided in the field PayRangeMin. In addition, the value of PayRangeMax must be larger than the value of PayRangeMin.	78000
PayRangeMid	Decimal	No	Mid value of the pay range.	65000
Currency	ISO enum	No	Currency of the pay range. Code of the relevant currency in the Currency ISO enum. This field is required if any value is provided in the amount fields (PayRangeMin, PayRangeMax, BenchmarkRangeMin or BenchmarkRangeMax).	EUR
LocalGrade	Enum	No	Local grade of the worker. Code of the relevant local grade in the as defined in the IndividualPayRangeLocalGrade enum.	FR-G7
GlobalGrade	Enum	No	Global grade of the worker. Code of the relevant global grade in the as defined in the IndividualPayRangeGlobalGrade enum.	GG7
BenchmarkRangeMin	Decimal	No	Minimum benchmark value for the pay range. If a value is present in this field, a value must also be provided in the field BenchmarkRangeMax. In addition, the value of BenchmarkRangeMin must be smaller than the value of BenchmarkRangeMax.	50000
BenchmarkRangeMid	Decimal	No	Medium benchmark value for the pay range.	63000
BenchmarkRangeMax	Decimal	No	Maximum benchmark value for the pay range. If a value is present in this field, a value must also be provided in the field BenchmarkRangeMin. In addition, the value of BenchmarkRangeMax must be larger than the value of BenchmarkRangeMin.	76000
EffectiveDate	Date	Yes	Effective date of the pay range.	2026-01-01

This is a tip message.

You can find an upload file template for the IndividualPayRange entity attached to this article under the name IndividualPayRange.csv.

GoalPlan entity details

The GoalPlan entity defines goal plans, that is, the plans or cycles within which goals are set and measured, such as an annual bonus plan, with their name and start and end dates.

The following table describes the fields contained in the GoalPlan entity.

This is an note/information message.

The GoalPlan entity file must be present at each data upload. However, it does not have to contain data.

If it does indeed contain data, the fields marked as mandatory must contain data.

GoalPlan entity details
Field name	Data type	Mandatory	Description	Data example
ExternalId	String	Yes	External ID of the goal plan.	BONUS-2026
Name	String	Yes	Name of the goal plan.	Annual bonus 2026
StartDate	Date	No	Start date of the goal plan.	2026-01-01
EndDate	Date	No	End date of the goal plan.	2026-12-31

This is a tip message.

You can find an upload file template for the GoalPlan entity attached to this article under the name GoalPlan.csv.

Goal entity details

The Goal entity defines the goals themselves: their name, the unit in which they are measured, whether they are individual goals, and their type. A goal is linked to a goal plan through the GoalPlanGoalAssignment entity, and to workers through the GoalAchievementNew or GoalWorkerAssignment entity.

The following table describes the fields contained in the Goal entity.

This is an note/information message.

The Goal entity file must be present at each data upload. However, it does not have to contain data.

If it does indeed contain data, the fields marked as mandatory must contain data.

Goal entity details
Field name	Data type	Mandatory	Description	Data example
ExternalId	String	Yes	External ID of the goal.	TEAM-001
Name	String	Yes	Name of the goal.	Team revenue target
GoalUnit	Enum	Yes	Unit used to measure the goal. Code of the relevant unit in the GoalUnit enum.	Amount
GoalUnit	Boolean	Yes	Indicates whether or not the goal the an individual goal.	false
GoalType	Enum	No	Type of the goal. Code of the relevant goal in the GoalType enum.	FINANCIAL

This is a tip message.

You can find an upload file template for the Goal entity attached to this article under the name Goal.csv.

GoalPlanGoalAssignment entity details

The GoalPlanGoalAssignment entity specifies which goals belong to which goal plan. Each record links one goal from the Goal entity to one goal plan from the GoalPlan entity.

The following table describes the fields contained in the GoalPlanGoalAssignment entity.

This is an note/information message.

The GoalPlanGoalAssignment entity file must be present at each data upload. However, it does not have to contain data.

If it does indeed contain data, the fields marked as mandatory must contain data.

GoalPlanGoalAssignment entity details
Field name	Data type	Mandatory	Description	Data example
ExternalId	String	Yes	Unique identifier of the goal plan.	BONUS-2026-TEAM-001
GoalPlanExternalId	Entity ref	Yes	External ID of the goal plan. Corresponds to the ExternalId field in the GoalPlan entity.	BONUS-2026
GoalExternalId	Entity ref	Yes	Unique identifier of the goal. Corresponds to the ExternalId field in the Goal entity.	TEAM-001

This is a tip message.

You can find an upload file template for the GoalPlanGoalAssignment entity attached to this article under the name GoalPlanGoalAssignment.csv.

GoalAchievementNew entity details

The GoalAchievementNew entity stores the achievement of a goal by a given worker within a goal plan for a defined effective period: the weight of the goal and of its goal type, the target, the result, and the achievement percentage.

The following table describes the fields contained in the GoalAchievementNew entity.

The GoalAchievementNew entity records an achievement for one worker at a time. If the same result applies to every worker assigned to a goal, you can record it once in the GoalResult entity and link workers to the goal through the GoalWorkerAssignment entity instead.

This is an note/information message.

The GoalAchievementNew entity file must be present at each data upload. However, it does not have to contain data.

If it does indeed contain data, the fields marked as mandatory must contain data.

GoalAchievementNew entity details
Field name	Data type	Mandatory	Description	Data example
WorkerExternalId	Entity ref	Yes	Unique identifier of the worker. ExternalId value in the Worker entity.	000123
GoalExternalId	Entity ref	Yes	Unique identifier of the goal. ExternalId value in the Goal entity.	TEAM-001
GoalPlanExternalId	Entity ref	Yes	Unique identifier of the goal plan. ExternalId value in the GoalType entity.	BONUS-2026
GoalWeight	Number	Yes	Weight of the goal.	0.4
GoalTypeWeight	Number	No	Weight of the goal type.	0.6
GoalTarget	Number	No	Target of the goal.	100
GoalResult	Number	No	Result of the goal.	92
GoalAchievementPercentage	Number	No	Percentage of achievement of the goal.	92
EffectiveRangeStartDate	Date	Yes	Start date of the effective range for the goal. For individual goals, this is the goal plan's start date if the goal was created before the plan started, or the goal's publish date if it was created on or after that date.	2026-01-01
EffectiveRangeEndDate	Date	Yes	End date of the effective range for the goal.	2026-12-31

This is a tip message.

You can find an upload file template for the GoalAchievementNew entity attached to this article under the name GoalAchievementNew.csv.

GoalWorkerAssignment entity details

The GoalWorkerAssignment entity stores the assignment of a worker to a goal within a goal plan for a defined effective period, together with the organizational and compensation context of that assignment: compensation group, sector, level, the weight of the goal within the assignment, and the annual salary and bonus percentages associated with it.

The GoalWorkerAssignment entity extends the goal data model rather than replacing it: GoalPlan defines the plan or cycle, Goal defines the goal itself, GoalWorkerAssignment links individual workers to those goals, and GoalResult records what was achieved. Because assignments and results are stored separately, you can manage who is assigned to a goal independently of the result recorded for it.

The following table describes the fields contained in the GoalWorkerAssignment entity.

This is an note/information message.

A combination of WorkerExternalId, GoalPlanExternalId, GoalExternalId, and the effective range dates must be unique within the entity.

GoalWorkerAssignment entity details
Field name	Data type	Mandatory	Description	Data example
WorkerExternalId	String (entity ref)	Yes	Unique identifier of the worker assigned to the goal. ExternalId value in the Worker entity.	100045
GoalPlanExternalId	String (entity ref)	Yes	Unique identifier of the goal plan. ExternalId value in the GoalPlan entity.	BONUS-2026
GoalExternalId	String (entity ref)	Yes	Unique identifier of the goal the worker is assigned to. ExternalId value in the Goal entity.	TEAM-001
GoalWeight	Number	Yes	Weight of the goal within the worker's assignment.	1
CompensationGroup	Enum	Yes	Compensation group of the worker for this assignment. Code of the relevant compensation group in the CompensationGroup enum.	COMP-GROUP-01
Sector	Enum	Yes	Sector of the worker for this assignment. Code of the relevant sector in the Sector enum.	Beverages
Level	String	Yes	Level of the worker for this assignment.	L4
GlobalFunction	String	No	Global function of the worker, where it factors into determining the final result for the assigned goal.	Global Sales
AnnualSalaryCurrency	Enum	Yes	Currency of the annual salary. Code of the relevant currency in the Currency enum.	EUR
AnnualSalaryAmount	Number	Yes	Annual salary of the worker associated with the assignment.	65000
AnnualBonusPercentage	Number	Yes	Annual bonus percentage associated with the assignment.	15
PremiumBonusPercentage	Number	Yes	Premium bonus percentage associated with the assignment.	5
EffectiveRangeStartDate	Date	Yes	Start date of the period during which the worker is assigned to the goal.	2026-01-01
EffectiveRangeEndDate	Date	Yes	End date of the period during which the worker is assigned to the goal.	2026-12-31

This is an note/information message.

The sector, level, annual salary, annual bonus percentage, and premium bonus percentage values are displayed as read-only reference data in the verification grid of a compensation round. They are not used in any calculations.

This is a tip message.

You can find an upload file template for the GoalWorkerAssignment entity attached to this article under the name GoalWorkerAssignment.csv.

GoalResult entity details

The GoalResult entity stores the result achieved for a goal within a goal plan for a defined effective period.

Unlike the GoalAchievementNew entity, which ties an achievement to one worker at a time, GoalResult does not reference a worker. A result recorded in GoalResult applies to every worker assigned to the same goal in the same goal plan through the GoalWorkerAssignment entity, so you do not need to enter it separately for each worker.

The following table describes the fields contained in the GoalResult entity.

This is an note/information message.

A combination of GoalPlanExternalId, GoalExternalId, and the effective range dates must be unique within the entity.

GoalResult entity details
Field name	Data type	Mandatory	Description	Data example
GoalPlanExternalId	String (entity ref)	Yes	Unique identifier of the goal plan. ExternalId value in the GoalPlan entity.	BONUS-2026
GoalExternalId	String (entity ref)	Yes	Unique identifier of the goal. ExternalId value in the Goal entity.	TEAM-001
Result	Number	Yes	Result achieved for the goal within the goal plan during the effective period.	105.5
EffectiveRangeStartDate	Date	Yes	Start date of the period the result applies to.	2026-01-01
EffectiveRangeEndDate	Date	Yes	End date of the period the result applies to.	2026-12-31

This is a tip message.

You can find an upload file template for the GoalResult entity attached to this article under the name GoalResult.csv.

ContractedCompensation entity details

The ContractedCompensation entity stores what a worker is contractually entitled to for a compensation element from a given date: either an amount in a given currency or a percentage of another compensation element, together with the reason for the compensation.

The following table describes the fields contained in the ContractedCompensation entity.

This is an note/information message.

The ContractedCompensation entity file must be present at each data upload. However, it does not have to contain data.

If it does indeed contain data, the fields marked as mandatory must contain data.

ContractedCompensation entity details
Field name	Data type	Mandatory	Description	Data example
WorkerExternalId	String (entity ref)	Yes	Unique identifier of the worker. ExternalId value in the Worker entity.	000123
CompensationElementExternalId	String (entity ref)	Yes	Unique identifier of the compensation element. Corresponds to the value of the ExternalId field in the CompensationElement entity.	BASE_SALARY
AmountSource	Enum	No	Source of the contracted amount. Corresponds to the code of the amount source in the AmountSource enum.	AMOUNT
Currency	Enum	No	Currency used for the contracted salary. Code of the relevant currency in the Currency enum.	EUR
ContractedAmount	Decimal	No	Actual figure of the contracted salary.	60000
Percentage	Decimal	No	Percentage of the contracted compensation.	10
PercentageReferenceCompensationElementExternalId	String (entity ref)	No	Unique identifier of the compensation element. Corresponds to the value of the ExternalId field in the CompensationElement entity.	BASE_SALARY
CompensationReason	String	No	Motive of the compensation.	Annual review
EffectiveDate	Date	Yes	Effective date of the contracted compensation.	2026-01-01

This is a tip message.

You can find an upload file template for the ContractedCompensation entity attached to this article under the name ContractedCompensation.csv.

PaidCompensation entity details

The PaidCompensation entity stores the amounts actually paid to a worker for a compensation element over a period: the amount and currency, the payment date, the compensation element the payment derives from, and the reason for the payment.

The following table describes the fields contained in the PaidCompensation entity.

This is an note/information message.

The PaidCompensation entity file must be present at each data upload. However, it does not have to contain data.

If it does indeed contain data, the fields marked as mandatory must contain data.

PaidCompensation entity details
Field name	Data type	Mandatory	Description	Data example
WorkerExternalId	String (entity ref)	Yes	Unique identifier of the worker. ExternalId value in the Worker entity.	000123
CompensationElementExternalId	String (entity ref)	Yes	Unique identifier of the compensation element. Corresponds to the value of the ExternalId field in the CompensationElement entity.	ANNUAL_BONUS
Currency	Enum	No	Currency used for the contracted salary. Code of the relevant currency in the Currency enum.	EUR
PaidAmount	Decimal	No	Amount actually paid to the worker.	7500
PaymentDate	Date	No	Date at which the amount was transferred to the worker.	2026-03-25
DerivedFromCompensationElementExternalId	String (entity reference)	No	Unique identifier of the compensation element. Corresponds to the value of the ExternalId field in the CompensationElement entity.	TARGET_BONUS
CompensationReason	String	No	Motive of the compensation.	Annual bonus payout
EffectiveRangeStartDate	Date	Yes	Start date of the compensation period.	2025-01-01
EffectiveRangeEndDate	Date	Yes	End date of the compensation period.	2025-12-31

This is a tip message.

You can find an upload file template for the PaidCompensation entity attached to this article under the name PaidCompensation.csv.

Data foundation change history

This section lists past changes to the entities of the data foundation, for reference. It does not describe the current structure: for the entities you can use today, see Overview and the entity details above.

Data foundation change history
Version	Change	Entities	Current status
28.2	Added	GoalWorkerAssignment, GoalResult; enums CompensationGroup and Sector	Available.
27.0	Removed	GoalAchievement	No longer available. Use GoalAchievementNew.
27.0	Removed	GoalPlanTypeAssignment	No longer available. Use GoalAchievementNew, Goal, and GoalPlan.
27.0	Deprecated	CompensationHistory	No new data can be ingested. Existing models and snapshots still work. Use ContractedCompensation and PaidCompensation. See Legacy entities.
14.0	Added	Goal, GoalPlanGoalAssignment, GoalAchievementNew	Available.
1.8	Added	GoalPlan, GoalPlanTypeAssignment, GoalAchievement	GoalPlan is available. The other two were removed in version 27.0.

Going further

Attachments