Employees
The Employee object is used to represent any person who has been employed by a company.
Properties

idUUID
Required

remote_idString
Optional
The third-party API ID of the matching object.

created_atDateTime (ISO 8601)
Required

modified_atDateTime (ISO 8601)
Required
This is the datetime that this object was last updated by Merge

employee_numberString
Optional
The employee's number that appears in the third-party integration's UI.

companyUUID
Optional
The ID of the employee's company.

first_nameString
Optional
The employee's first name.

last_nameString
Optional
The employee's last name.

preferred_nameString
Optional
The employee's preferred first name.

display_full_nameString
Optional
The employee's full name, to use for display purposes. If a preferred first name is available, the full name will include the preferred first name.

usernameString
Optional
The employee's username that appears in the remote UI.

groupsArray
Required

work_emailString
Optional
The employee's work email.

personal_emailString
Optional
The employee's personal email.

mobile_phone_numberString
Optional
The employee's mobile phone number.

employmentsEmployment[]
Required
Array of Employment IDs for this Employee.
The Employment object

The Employment object is used to represent a job position at a company.

Please note: When there is a change in pay or title, integrations with historical data will create new Employment objects while integrations without historical data will update existing ones.

Properties

idUUID
Required

remote_idString
Optional
The third-party API ID of the matching object.

created_atDateTime (ISO 8601)
Required

modified_atDateTime (ISO 8601)
Required
This is the datetime that this object was last updated by Merge

employeeUUID
Optional
The employee holding this position.

job_titleString
Optional
The position's title.

pay_rateNumber
Optional
The position's pay rate in dollars.

pay_periodEnum
Optional
The time period this pay rate encompasses. Possible values include: HOUR, DAY, WEEK, EVERY_TWO_WEEKS, SEMIMONTHLY, MONTH, QUARTER, EVERY_SIX_MONTHS, YEAR. In cases where there is no clear mapping, the original value passed through will be returned.

pay_frequencyEnum
Optional
The position's pay frequency. Possible values include: WEEKLY, BIWEEKLY, MONTHLY, QUARTERLY, SEMIANNUALLY, ANNUALLY, THIRTEEN-MONTHLY, PRO_RATA, SEMIMONTHLY. In cases where there is no clear mapping, the original value passed through will be returned.

pay_currencyEnum
Optional
The position's currency code. Possible values include: XUA, AFN, AFA, ALL, ALK, DZD, ADP, AOA, AOK, AON, AOR, ARA, ARS, ARM, ARP, ARL, AMD, AWG, AUD, ATS, AZN, AZM, BSD, BHD, BDT, BBD, BYN, BYB, BYR, BEF, BEC, BEL, BZD, BMD, BTN, BOB, BOL, BOV, BOP, BAM, BAD, BAN, BWP, BRC, BRZ, BRE, BRR, BRN, BRB, BRL, GBP, BND, BGL, BGN, BGO, BGM, BUK, BIF, XPF, KHR, CAD, CVE, KYD, XAF, CLE, CLP, CLF, CNX, CNY, CNH, COP, COU, KMF, CDF, CRC, HRD, HRK, CUC, CUP, CYP, CZK, CSK, DKK, DJF, DOP, NLG, XCD, DDM, ECS, ECV, EGP, GQE, ERN, EEK, ETB, EUR, XBA, XEU, XBB, XBC, XBD, FKP, FJD, FIM, FRF, XFO, XFU, GMD, GEK, GEL, DEM, GHS, GHC, GIP, XAU, GRD, GTQ, GWP, GNF, GNS, GYD, HTG, HNL, HKD, HUF, IMP, ISK, ISJ, INR, IDR, IRR, IQD, IEP, ILS, ILP, ILR, ITL, JMD, JPY, JOD, KZT, KES, KWD, KGS, LAK, LVL, LVR, LBP, LSL, LRD, LYD, LTL, LTT, LUL, LUC, LUF, MOP, MKD, MKN, MGA, MGF, MWK, MYR, MVR, MVP, MLF, MTL, MTP, MRU, MRO, MUR, MXV, MXN, MXP, MDC, MDL, MCF, MNT, MAD, MAF, MZE, MZN, MZM, MMK, NAD, NPR, ANG, TWD, NZD, NIO, NIC, NGN, KPW, NOK, OMR, PKR, XPD, PAB, PGK, PYG, PEI, PEN, PES, PHP, XPT, PLN, PLZ, PTE, GWE, QAR, XRE, RHD, RON, ROL, RUB, RUR, RWF, SVC, WST, SAR, RSD, CSD, SCR, SLL, XAG, SGD, SKK, SIT, SBD, SOS, ZAR, ZAL, KRH, KRW, KRO, SSP, SUR, ESP, ESA, ESB, XDR, LKR, SHP, XSU, SDD, SDG, SDP, SRD, SRG, SZL, SEK, CHF, SYP, STN, STD, TVD, TJR, TJS, TZS, XTS, THB, XXX, TPE, TOP, TTD, TND, TRY, TRL, TMT, TMM, USD, USN, USS, UGX, UGS, UAH, UAK, AED, UYW, UYU, UYP, UYI, UZS, VUV, VES, VEB, VEF, VND, VNN, CHE, CHW, XOF, YDD, YER, YUN, YUD, YUM, YUR, ZWN, ZRN, ZRZ, ZMW, ZMK, ZWD, ZWR, ZWL. In cases where there is no clear mapping, the original value passed through will be returned.

pay_groupUUID
Optional
The employment's pay group

flsa_statusEnum
Optional
The position's FLSA status. Possible values include: EXEMPT, SALARIED_NONEXEMPT, NONEXEMPT, OWNER. In cases where there is no clear mapping, the original value passed through will be returned.

effective_dateDateTime (ISO 8601)
Optional
The position's effective date.

employment_typeEnum
Optional
The position's type of employment. Possible values include: FULL_TIME, PART_TIME, INTERN, CONTRACTOR, FREELANCE. In cases where there is no clear mapping, the original value passed through will be returned.

remote_was_deletedBoolean
Required
Indicates whether or not this object has been deleted in the third party platform.

field_mappingsObject
Optional

remote_dataRemoteData[]
Optional

home_locationUUID
Optional
The employee's home address.

work_locationUUID
Optional
The employee's work address.

managerUUID
Optional
The employee ID of the employee's manager.

teamUUID
Optional
The employee's team.

pay_groupUUID
Optional
The employee's pay group

ssnString
Optional
The employee's social security number.

genderEnum
Optional
The employee's gender. Possible values include: MALE, FEMALE, NON-BINARY, OTHER, PREFER_NOT_TO_DISCLOSE. In cases where there is no clear mapping, the original value passed through will be returned.

ethnicityEnum
Optional
The employee's ethnicity. Possible values include: AMERICAN_INDIAN_OR_ALASKA_NATIVE, ASIAN_OR_INDIAN_SUBCONTINENT, BLACK_OR_AFRICAN_AMERICAN, HISPANIC_OR_LATINO, NATIVE_HAWAIIAN_OR_OTHER_PACIFIC_ISLANDER, TWO_OR_MORE_RACES, WHITE, PREFER_NOT_TO_DISCLOSE. In cases where there is no clear mapping, the original value passed through will be returned.

marital_statusEnum
Optional
The employee's filing status as related to marital status. Possible values include: SINGLE, MARRIED_FILING_JOINTLY, MARRIED_FILING_SEPARATELY, HEAD_OF_HOUSEHOLD, QUALIFYING_WIDOW_OR_WIDOWER_WITH_DEPENDENT_CHILD. In cases where there is no clear mapping, the original value passed through will be returned.

date_of_birthDateTime (ISO 8601)
Optional
The employee's date of birth.

hire_dateDateTime (ISO 8601)Deprecated
Optional
The date that the employee was hired, usually the day that an offer letter is signed. If an employee has multiple hire dates from previous employments, this represents the most recent hire date. Note: If you're looking for the employee's start date, refer to the start_date field.

The hire_date field on the Employee object is deprecated


start_dateDateTime (ISO 8601)
Optional
The date that the employee started working. If an employee was rehired, the most recent start date will be returned.

remote_created_atDateTime (ISO 8601)
Optional
When the third party's employee was created.

employment_statusEnum
Optional
The employment status of the employee. Possible values include: ACTIVE, PENDING, INACTIVE. In cases where there is no clear mapping, the original value passed through will be returned.

termination_dateDateTime (ISO 8601)
Optional
The employee's termination date.

avatarString
Optional
The URL of the employee's avatar image.

custom_fieldsObject
Optional
Custom fields configured for a given model.

remote_was_deletedBoolean
Required

field_mappingsObject
Optional

remote_dataRemoteData[]
Optional


GET
/employees

https://api.merge.dev/api/hris/v1/employees

US
EU

Returns a list of Employee objects.


Query & Path Parameters

company_idString
Optional
If provided, will only return employees for this company.

created_afterDateTime (ISO 8601)
Optional
If provided, will only return objects created after this datetime.

created_beforeDateTime (ISO 8601)
Optional
If provided, will only return objects created before this datetime.

cursorString
Optional
The pagination cursor value.

display_full_nameString
Optional
If provided, will only return employees with this display name.

employment_statusString
Optional
If provided, will only return employees with this employment status.

employment_typeString
Optional
If provided, will only return employees that have an employment of the specified employment_type.

expandString
Optional
Which relations should be returned in expanded form. Multiple relation names should be comma separated without spaces.

first_nameString
Optional
If provided, will only return employees with this first name.

groupsString
Optional
If provided, will only return employees matching the group ids; multiple groups can be separated by commas.

home_location_idString
Optional
If provided, will only return employees for this home location.

include_deleted_dataBoolean
Optional
Whether to include data that was marked as deleted by third party webhooks.

include_remote_dataBoolean
Optional
Whether to include the original data Merge fetched from the third-party to produce these models.

include_sensitive_fieldsBoolean
Optional
Whether to include sensitive fields (such as social security numbers) in the response.

job_titleString
Optional
If provided, will only return employees that have an employment of the specified job_title.

last_nameString
Optional
If provided, will only return employees with this last name.

manager_idString
Optional
If provided, will only return employees for this manager.

modified_afterDateTime (ISO 8601)
Optional
If provided, only objects synced by Merge after this date time will be returned.

modified_beforeDateTime (ISO 8601)
Optional
If provided, only objects synced by Merge before this date time will be returned.

page_sizeInteger
Optional
Number of results to return per page.

pay_group_idString
Optional
If provided, will only return employees for this pay group

personal_emailString
Optional
If provided, will only return Employees with this personal email

remote_fieldsString
Optional
Deprecated. Use show_enum_origins.

remote_idString
Optional
The API provider's ID for the given object.

show_enum_originsString
Optional
A comma separated list of enum field names for which you'd like the original values to be returned, instead of Merge's normalized enum values. Learn more

started_afterDateTime (ISO 8601)
Optional
If provided, will only return employees that started after this datetime.

started_beforeDateTime (ISO 8601)
Optional
If provided, will only return employees that started before this datetime.

team_idString
Optional
If provided, will only return employees for this team.

terminated_afterDateTime (ISO 8601)
Optional
If provided, will only return employees that were terminated after this datetime.

terminated_beforeDateTime (ISO 8601)
Optional
If provided, will only return employees that were terminated before this datetime.

work_emailString
Optional
If provided, will only return Employees with this work email

work_location_idString
Optional
If provided, will only return employees for this location.

Field support by integration
See all supported fields
Use the /linked-accounts endpoint to pull platform support information
7shifts
7shifts
ADP Workforce Now
ADP Workforce Now
AlexisHR
AlexisHR
AllianceHCM
AllianceHCM
Altera Payroll
Altera Payroll
BambooHR
BambooHR
Breathe
Breathe
Charlie
Charlie
ChartHop
ChartHop
ClayHR
ClayHR
CyberArk
CyberArk
Dayforce
Dayforce
Deel
Deel
Employment Hero
Employment Hero
Factorial
Factorial
Freshteam
Freshteam
Google Workspace
Google Workspace
Gusto
Hibob
Hibob
HR Cloud
HR Cloud
HR Partner
HR Partner
Humaans
Humaans
Humi
Humi
Insperity Premier
Insperity Premier
IntelliHR
IntelliHR
IRIS Cascade
IRIS Cascade
JumpCloud
JumpCloud
Justworks
Justworks
Kallidus
Kallidus
Keka
Keka
Kenjo
Kenjo
Lano
Lano
Lucca
Lucca
Microsoft Entra ID
Microsoft Entra ID
Namely
Namely
Nmbrs
Nmbrs
Officient
Officient
Okta
Okta
OneLogin
OneLogin
Oracle Human Capital Management (HCM)
Oracle Human Capital Management (HCM)
OysterHR
OysterHR
PayCaptain
PayCaptain
Paychex
Paychex
Paycom
Paycom
Paycor
Paycor
PayFit
PayFit
Paylocity
Paylocity
PeopleHR
PeopleHR
Personio
Personio
PingOne
PingOne
Proliant
Proliant
Remote
Remote
Sage HR
Sage HR
SAP SuccessFactors
SAP SuccessFactors
Sesame
Sesame
Square Payroll
Square Payroll
TriNet
TriNet
TriNet HR Platform
TriNet HR Platform
UKG Pro
UKG Pro
UKG Pro Workforce Management
UKG Pro Workforce Management
UKG Ready
UKG Ready
Workday
Workday
Zoho People
Zoho People
POST
/employees
Beta

https://api.merge.dev/api/hris/v1/employees

US
EU

Creates an Employee object with the given values.


Query & Path Parameters

is_debug_modeBoolean
Optional
Whether to include debug fields (such as log file links) in the response.

run_asyncBoolean
Optional
Whether or not third-party updates should be run asynchronously.
Body Parameters

modelObject
Required
Find available fields below under “Model Parameters”.
Model Parameters
View app-specific writable fields under “Field support by platform” in this section.

employee_numberString
The employee's number that appears in the third-party integration's UI.

companyUUID
The ID of the employee's company. Must pass in a valid Merge ID, which can be obtained from the id field in the Company object.

first_nameString
The employee's first name.

last_nameString
The employee's last name.

preferred_nameString
The employee's preferred first name.

display_full_nameString
The employee's full name, to use for display purposes. If a preferred first name is available, the full name will include the preferred first name.

usernameString
The employee's username that appears in the remote UI.

groupsArray

work_emailString
The employee's work email.

personal_emailString
The employee's personal email.

mobile_phone_numberString
The employee's mobile phone number.

employmentsArray
Array of Employment IDs for this Employee.

home_locationUUID
The employee's home address. Must pass in a valid Merge ID, which can be obtained from the id field in the Location object.

work_locationUUID
The employee's work address. Must pass in a valid Merge ID, which can be obtained from the id field in the Location object.

managerUUID
The employee ID of the employee's manager. Must pass in a valid Merge ID, which can be obtained from the id field in the Employee object.

teamUUID
The employee's team. Must pass in a valid Merge ID, which can be obtained from the id field in the Team object.

pay_groupUUID
The employee's pay group Must pass in a valid Merge ID, which can be obtained from the id field in the PayGroup object.

ssnString
The employee's social security number.

genderEnum
The employee's gender. Must pass in one of the following choices: MALE, FEMALE, NON-BINARY, OTHER, PREFER_NOT_TO_DISCLOSE.

ethnicityEnum
The employee's ethnicity. Must pass in one of the following choices: AMERICAN_INDIAN_OR_ALASKA_NATIVE, ASIAN_OR_INDIAN_SUBCONTINENT, BLACK_OR_AFRICAN_AMERICAN, HISPANIC_OR_LATINO, NATIVE_HAWAIIAN_OR_OTHER_PACIFIC_ISLANDER, TWO_OR_MORE_RACES, WHITE, PREFER_NOT_TO_DISCLOSE.

marital_statusEnum
The employee's filing status as related to marital status. Must pass in one of the following choices: SINGLE, MARRIED_FILING_JOINTLY, MARRIED_FILING_SEPARATELY, HEAD_OF_HOUSEHOLD, QUALIFYING_WIDOW_OR_WIDOWER_WITH_DEPENDENT_CHILD.

date_of_birthDateTime (ISO 8601)
The employee's date of birth.

hire_dateDateTime (ISO 8601)
The date that the employee was hired, usually the day that an offer letter is signed. If an employee has multiple hire dates from previous employments, this represents the most recent hire date. Note: If you're looking for the employee's start date, refer to the start_date field.

start_dateDateTime (ISO 8601)
The date that the employee started working. If an employee was rehired, the most recent start date will be returned.

employment_statusEnum
The employment status of the employee. Must pass in one of the following choices: ACTIVE, PENDING, INACTIVE.

termination_dateDateTime (ISO 8601)
The employee's termination date.

avatarString
The URL of the employee's avatar image.

integration_paramsObject

linked_account_paramsObject

Field support by integration
See all supported fields
Use the /linked-accounts endpoint to pull platform support information
BambooHR
BambooHR
Humaans
Humaans
IntelliHR
IntelliHR
Personio
Personio
UKG Pro
UKG Pro
ADP Workforce Now
ADP Workforce Now
Coming soon
AlexisHR
AlexisHR
Coming soon
ChartHop
ChartHop
Coming soon
Dayforce
Dayforce
Coming soon
Freshteam
Freshteam
Coming soon
Gusto
Coming soon
HR Cloud
HR Cloud
Coming soon
Kallidus
Kallidus
Coming soon
Lano
Lano
Coming soon
Namely
Namely
Coming soon
Nmbrs
Nmbrs
Coming soon
Paylocity
Paylocity
Coming soon
Sage HR
Sage HR
Coming soon
Square Payroll
Square Payroll
Coming soon
TriNet
TriNet
Coming soon
UKG Ready
UKG Ready
Coming soon
To include the correct model fields when making POST requests, use the GET /employees/meta/post endpoint. Learn more in our /meta guide.
GET
/employees/{id}

https://api.merge.dev/api/hris/v1/employees/{id}

US
EU

Returns an Employee object with the given id.


Query & Path Parameters

expandString
Optional
Which relations should be returned in expanded form. Multiple relation names should be comma separated without spaces.

idUUID
Required

include_remote_dataBoolean
Optional
Whether to include the original data Merge fetched from the third-party to produce these models.

include_sensitive_fieldsBoolean
Optional
Whether to include sensitive fields (such as social security numbers) in the response.

remote_fieldsString
Optional
Deprecated. Use show_enum_origins.

show_enum_originsString
Optional
A comma separated list of enum field names for which you'd like the original values to be returned, instead of Merge's normalized enum values. Learn more

Field support by integration
See all supported fields
Use the /linked-accounts endpoint to pull platform support information
7shifts
7shifts
ADP Workforce Now
ADP Workforce Now
AlexisHR
AlexisHR
AllianceHCM
AllianceHCM
Altera Payroll
Altera Payroll
BambooHR
BambooHR
Breathe
Breathe
Charlie
Charlie
ChartHop
ChartHop
ClayHR
ClayHR
CyberArk
CyberArk
Dayforce
Dayforce
Deel
Deel
Employment Hero
Employment Hero
Factorial
Factorial
Freshteam
Freshteam
Google Workspace
Google Workspace
Gusto
Hibob
Hibob
HR Cloud
HR Cloud
HR Partner
HR Partner
Humaans
Humaans
Humi
Humi
Insperity Premier
Insperity Premier
IntelliHR
IntelliHR
IRIS Cascade
IRIS Cascade
JumpCloud
JumpCloud
Justworks
Justworks
Kallidus
Kallidus
Keka
Keka
Kenjo
Kenjo
Lano
Lano
Lucca
Lucca
Microsoft Entra ID
Microsoft Entra ID
Namely
Namely
Nmbrs
Nmbrs
Officient
Officient
Okta
Okta
OneLogin
OneLogin
Oracle Human Capital Management (HCM)
Oracle Human Capital Management (HCM)
OysterHR
OysterHR
PayCaptain
PayCaptain
Paychex
Paychex
Paycom
Paycom
Paycor
Paycor
PayFit
PayFit
Paylocity
Paylocity
PeopleHR
PeopleHR
Personio
Personio
PingOne
PingOne
Proliant
Proliant
Remote
Remote
Sage HR
Sage HR
SAP SuccessFactors
SAP SuccessFactors
Sesame
Sesame
Square Payroll
Square Payroll
TriNet
TriNet
TriNet HR Platform
TriNet HR Platform
UKG Pro
UKG Pro
UKG Pro Workforce Management
UKG Pro Workforce Management
UKG Ready
UKG Ready
Workday
Workday
Zoho People
Zoho People
POST
/employees/ignore/{model_id}

https://api.merge.dev/api/hris/v1/employees/ignore/{model_id}

US
EU

Ignores a specific row based on the model_id in the url. These records will have their properties set to null, and will not be updated in future syncs. The "reason" and "message" fields in the request body will be stored for audit purposes.


Query & Path Parameters

model_idUUID
Required
Body Parameters

reasonEnum
Required
Must pass in one of the following choices: GENERAL_CUSTOMER_REQUEST, GDPR, OTHER.

messageString
Required
Field support by integration
See all supported fields
Use the /linked-accounts endpoint to pull platform support information
BambooHR
BambooHR
Humaans
Humaans
IntelliHR
IntelliHR
Personio
Personio
UKG Pro
UKG Pro
ADP Workforce Now
ADP Workforce Now
Coming soon
AlexisHR
AlexisHR
Coming soon
ChartHop
ChartHop
Coming soon
Dayforce
Dayforce
Coming soon
Freshteam
Freshteam
Coming soon
Gusto
Coming soon
HR Cloud
HR Cloud
Coming soon
Kallidus
Kallidus
Coming soon
Lano
Lano
Coming soon
Namely
Namely
Coming soon
Nmbrs
Nmbrs
Coming soon
Paylocity
Paylocity
Coming soon
Sage HR
Sage HR
Coming soon
Square Payroll
Square Payroll
Coming soon
TriNet
TriNet
Coming soon
UKG Ready
UKG Ready
Coming soon
GET
/employees/meta/post

https://api.merge.dev/api/hris/v1/employees/meta/post

US
EU

Returns metadata for Employee POSTs.


Field support by integration
See all supported fields
Use the /linked-accounts endpoint to pull platform support information
BambooHR
BambooHR
Humaans
Humaans
IntelliHR
IntelliHR
Personio
Personio
UKG Pro
UKG Pro
ADP Workforce Now
ADP Workforce Now
Coming soon
AlexisHR
AlexisHR
Coming soon
ChartHop
ChartHop
Coming soon
Dayforce
Dayforce
Coming soon
Freshteam
Freshteam
Coming soon
Gusto
Coming soon
HR Cloud
HR Cloud
Coming soon
Kallidus
Kallidus
Coming soon
Lano
Lano
Coming soon
Namely
Namely
Coming soon
Nmbrs
Nmbrs
Coming soon
Paylocity
Paylocity
Coming soon
Sage HR
Sage HR
Coming soon
Square Payroll
Square Payroll
Coming soon
TriNet
TriNet
Coming soon
UKG Ready
UKG Ready
Coming soon