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
The datetime that this object was created by Merge.

modified_atDateTime (ISO 8601)
Required
The datetime that this object was modified 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.

If an integration supports historical tracking of employments, it will be reflected in the data. If not, a new Employment object will be created whenever there is a change in job title or pay. The effective_date field should be used to order Employment objects, with the most recent date corresponding to the latest employment record for an employee.

Properties

idUUID
Required

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

created_atDateTime (ISO 8601)
Required
The datetime that this object was created by Merge.

modified_atDateTime (ISO 8601)
Required
The datetime that this object was modified by Merge.

employeeUUID
Optional
The employee holding this position.

job_titleString
Optional
The position's title.

pay_rateNumber
Optional
The position's pay rate.

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. To receive all enum values in the original format, use the show_enum_origins query parameter. Learn more.

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. To receive all enum values in the original format, use the show_enum_origins query parameter. Learn more.

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. To receive all enum values in the original format, use the show_enum_origins query parameter. Learn more.

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. To receive all enum values in the original format, use the show_enum_origins query parameter. Learn more.

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. To receive all enum values in the original format, use the show_enum_origins query parameter. Learn more.

remote_was_deletedBoolean
Required
Indicates whether or not this object has been deleted in the third party platform. Full coverage deletion detection is a premium add-on. Native deletion detection is offered for free with limited coverage. Learn more.

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.

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. To receive all enum values in the original format, use the show_enum_origins query parameter. Learn more.

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. To receive all enum values in the original format, use the show_enum_origins query parameter. Learn more.

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. To receive all enum values in the original format, use the show_enum_origins query parameter. Learn more.

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. To receive all enum values in the original format, use the show_enum_origins query parameter. Learn more.

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

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

remote_was_deletedBoolean
Required
Indicates whether or not this object has been deleted in the third party platform. Full coverage deletion detection is a premium add-on. Native deletion detection is offered for free with limited coverage. Learn more.

field_mappingsObject
Optional

remote_dataRemoteData[]
Optional


GET
/employees

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

US
EU
APAC

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
Indicates whether or not this object has been deleted in the third party platform. Full coverage deletion detection is a premium add-on. Native deletion detection is offered for free with limited coverage. Learn more.

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.

include_shell_dataBoolean
Optional
Whether to include shell records. Shell records are empty records (they may contain some metadata but all other fields are null).

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 RUN
ADP RUN
ADP Workforce Now
ADP Workforce Now
AlexisHR
AlexisHR
AllianceHCM
AllianceHCM
Altera Payroll
Altera Payroll
BambooHR
BambooHR
Breathe
Breathe
Cezanne HR
Cezanne HR
Charlie
Charlie
ChartHop
ChartHop
ClayHR
ClayHR
CyberArk
CyberArk
Darwinbox
Darwinbox
Dayforce
Dayforce
Deel
Deel
Employment Hero
Employment Hero
Factorial
Factorial
Freshteam
Freshteam
Google Workspace
Google Workspace
Gusto
Hailey HR
Hailey HR
Hibob
Hibob
HR Cloud
HR Cloud
HR Partner
HR Partner
Humaans
Humaans
Humi
Humi
Insperity Premier
Insperity Premier
IntelliHR
IntelliHR
IRIS Cascade
IRIS Cascade
ISolved
ISolved
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 Cloud Human Capital Management (HCM)
Oracle Cloud Human Capital Management (HCM)
OysterHR
OysterHR
PayCaptain
PayCaptain
Paychex
Paychex
Paycom
Paycom
Paycor
Paycor
PayFit
PayFit
Paylocity
Paylocity
PeopleHR
PeopleHR
Personio
Personio
PingOne
PingOne
Planday
Planday
Proliant
Proliant
Remote
Remote
Rippling
Rippling
Sage HR
Sage HR
Sage People
Sage People
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
Zelt
Zelt
Zoho People
Zoho People
POST
/employees
Beta

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

US
EU
APAC

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
Namely
Namely
Personio
Personio
UKG Pro
UKG Pro
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
APAC

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 RUN
ADP RUN
ADP Workforce Now
ADP Workforce Now
AlexisHR
AlexisHR
AllianceHCM
AllianceHCM
Altera Payroll
Altera Payroll
BambooHR
BambooHR
Breathe
Breathe
Cezanne HR
Cezanne HR
Charlie
Charlie
ChartHop
ChartHop
ClayHR
ClayHR
CyberArk
CyberArk
Darwinbox
Darwinbox
Dayforce
Dayforce
Deel
Deel
Employment Hero
Employment Hero
Factorial
Factorial
Freshteam
Freshteam
Google Workspace
Google Workspace
Gusto
Hailey HR
Hailey HR
Hibob
Hibob
HR Cloud
HR Cloud
HR Partner
HR Partner
Humaans
Humaans
Humi
Humi
Insperity Premier
Insperity Premier
IntelliHR
IntelliHR
IRIS Cascade
IRIS Cascade
ISolved
ISolved
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 Cloud Human Capital Management (HCM)
Oracle Cloud Human Capital Management (HCM)
OysterHR
OysterHR
PayCaptain
PayCaptain
Paychex
Paychex
Paycom
Paycom
Paycor
Paycor
PayFit
PayFit
Paylocity
Paylocity
PeopleHR
PeopleHR
Personio
Personio
PingOne
PingOne
Planday
Planday
Proliant
Proliant
Remote
Remote
Rippling
Rippling
Sage HR
Sage HR
Sage People
Sage People
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
Zelt
Zelt
Zoho People
Zoho People
POST
/employees/ignore/{model_id}

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

US
EU
APAC

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
Namely
Namely
Personio
Personio
UKG Pro
UKG Pro
GET
/employees/meta/post

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

US
EU
APAC

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
Namely
Namely
Personio
Personio
UKG Pro
UKG Pro