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.

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
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 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
Hailey HR
Hailey HR
Hibob
Hibob
HR Cloud
HR Cloud
HR Partner
HR Partner