openapi: 3.1.0 info: title: Accounting subpackage_employees API version: 1.0.0 servers: - url: https://api.merge.dev/api - url: https://api-eu.merge.dev/api - url: https://api-ap.merge.dev/api tags: - name: subpackage_employees paths: /accounting/v1/employees: get: operationId: list summary: List description: Returns a list of `Employee` objects.{/* BEGIN_ACCOUNTING_EMPLOYEE_FETCH_SUPPORTED_FIELDS */}{/* END_ACCOUNTING_EMPLOYEE_FETCH_SUPPORTED_FIELDS */} tags: - subpackage_employees parameters: - name: company_id in: query description: If provided, will only return employees for this company. required: false schema: type: string - name: created_after in: query description: If provided, will only return objects created after this datetime. required: false schema: type: string format: date-time - name: created_before in: query description: If provided, will only return objects created before this datetime. required: false schema: type: string format: date-time - name: cursor in: query description: The pagination cursor value. required: false schema: type: string - name: expand in: query description: Which relations should be returned in expanded form. Multiple relation names should be comma separated without spaces. required: false schema: type: array items: $ref: '#/components/schemas/EmployeesGetParametersExpandSchemaItems' - name: include_deleted_data in: query description: 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](https://docs.merge.dev/integrations/hris/supported-features/). required: false schema: type: boolean - name: include_remote_data in: query description: Whether to include the original data Merge fetched from the third-party to produce these models. required: false schema: type: boolean - name: include_shell_data in: query description: Whether to include shell records. Shell records are empty records (they may contain some metadata but all other fields are null). required: false schema: type: boolean - name: modified_after in: query description: If provided, only objects synced by Merge after this date time will be returned. required: false schema: type: string format: date-time - name: modified_before in: query description: If provided, only objects synced by Merge before this date time will be returned. required: false schema: type: string format: date-time - name: page_size in: query description: Number of results to return per page. The maximum limit is 100. required: false schema: type: integer - name: remote_id in: query description: The API provider's ID for the given object. required: false schema: type: string - name: Authorization in: header description: Token-based authentication with required prefix "Bearer" required: true schema: type: string - name: X-Account-Token in: header description: Token identifying the end user. required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/PaginatedEmployeeList' /accounting/v1/employees/{id}: get: operationId: retrieve summary: Retrieve description: Returns an `Employee` object with the given `id`.{/* BEGIN_ACCOUNTING_EMPLOYEE_FETCH_SUPPORTED_FIELDS */}{/* END_ACCOUNTING_EMPLOYEE_FETCH_SUPPORTED_FIELDS */} tags: - subpackage_employees parameters: - name: id in: path required: true schema: type: string format: uuid - name: expand in: query description: Which relations should be returned in expanded form. Multiple relation names should be comma separated without spaces. required: false schema: type: array items: $ref: '#/components/schemas/EmployeesIdGetParametersExpandSchemaItems' - name: include_remote_data in: query description: Whether to include the original data Merge fetched from the third-party to produce these models. required: false schema: type: boolean - name: include_shell_data in: query description: Whether to include shell records. Shell records are empty records (they may contain some metadata but all other fields are null). required: false schema: type: boolean - name: Authorization in: header description: Token-based authentication with required prefix "Bearer" required: true schema: type: string - name: X-Account-Token in: header description: Token identifying the end user. required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/Employee' /hris/v1/employees: get: operationId: list summary: List description: Returns a list of `Employee` objects.{/* BEGIN_HRIS_EMPLOYEE_FETCH_SUPPORTED_FIELDS */}{/* END_HRIS_EMPLOYEE_FETCH_SUPPORTED_FIELDS */} tags: - subpackage_employees parameters: - name: company_id in: query description: If provided, will only return employees for this company. required: false schema: type: string - name: created_after in: query description: If provided, will only return objects created after this datetime. required: false schema: type: string format: date-time - name: created_before in: query description: If provided, will only return objects created before this datetime. required: false schema: type: string format: date-time - name: cursor in: query description: The pagination cursor value. required: false schema: type: string - name: display_full_name in: query description: If provided, will only return employees with this display name. required: false schema: type: string - name: employee_number in: query description: If provided, will only return employees with this employee number. required: false schema: type: string - name: employment_status in: query description: 'If provided, will only return employees with this employment status. ' required: false schema: $ref: '#/components/schemas/EmployeesGetParametersEmploymentStatus' - name: employment_type in: query description: If provided, will only return employees that have an employment of the specified employment type. required: false schema: type: string - name: expand in: query description: Which relations should be returned in expanded form. Multiple relation names should be comma separated without spaces. required: false schema: type: array items: $ref: '#/components/schemas/EmployeesGetParametersExpandSchemaItems_2' - name: first_name in: query description: If provided, will only return employees with this first name. required: false schema: type: string - name: groups in: query description: If provided, will only return employees matching the group ids; multiple groups can be separated by commas. required: false schema: type: string - name: home_location_id in: query description: If provided, will only return employees for this home location. required: false schema: type: string - name: include_deleted_data in: query description: 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](https://docs.merge.dev/integrations/hris/supported-features/). required: false schema: type: boolean - name: include_remote_data in: query description: Whether to include the original data Merge fetched from the third-party to produce these models. required: false schema: type: boolean - name: include_sensitive_fields in: query description: Whether to include sensitive fields (such as social security numbers) in the response. required: false schema: type: boolean - name: include_shell_data in: query description: Whether to include shell records. Shell records are empty records (they may contain some metadata but all other fields are null). required: false schema: type: boolean - name: job_title in: query description: If provided, will only return employees that have an employment of the specified job title. required: false schema: type: string - name: last_name in: query description: If provided, will only return employees with this last name. required: false schema: type: string - name: manager_id in: query description: If provided, will only return employees for this manager. required: false schema: type: string - name: modified_after in: query description: If provided, only objects synced by Merge after this date time will be returned. required: false schema: type: string format: date-time - name: modified_before in: query description: If provided, only objects synced by Merge before this date time will be returned. required: false schema: type: string format: date-time - name: page_size in: query description: Number of results to return per page. The maximum limit is 100. required: false schema: type: integer - name: pay_group_id in: query description: If provided, will only return employees for this pay group required: false schema: type: string - name: personal_email in: query description: If provided, will only return Employees with this personal email required: false schema: type: string - name: remote_fields in: query description: Deprecated. Use show_enum_origins. required: false schema: $ref: '#/components/schemas/EmployeesGetParametersRemoteFields' - name: remote_id in: query description: The API provider's ID for the given object. required: false schema: type: string - name: show_enum_origins in: query description: 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](https://help.merge.dev/en/articles/8950958-show_enum_origins-query-parameter) required: false schema: $ref: '#/components/schemas/EmployeesGetParametersShowEnumOrigins' - name: started_after in: query description: If provided, will only return employees that started after this datetime. required: false schema: type: string format: date-time - name: started_before in: query description: If provided, will only return employees that started before this datetime. required: false schema: type: string format: date-time - name: team_id in: query description: If provided, will only return employees for this team. required: false schema: type: string - name: terminated_after in: query description: If provided, will only return employees that were terminated after this datetime. required: false schema: type: string format: date-time - name: terminated_before in: query description: If provided, will only return employees that were terminated before this datetime. required: false schema: type: string format: date-time - name: work_email in: query description: If provided, will only return Employees with this work email required: false schema: type: string - name: work_location_id in: query description: If provided, will only return employees for this location. required: false schema: type: string - name: Authorization in: header description: Token-based authentication with required prefix "Bearer" required: true schema: type: string - name: X-Account-Token in: header description: Token identifying the end user. required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/PaginatedEmployeeList' /hris/v1/employees/{id}: get: operationId: retrieve summary: Retrieve description: Returns an `Employee` object with the given `id`.{/* BEGIN_HRIS_EMPLOYEE_FETCH_SUPPORTED_FIELDS */}{/* END_HRIS_EMPLOYEE_FETCH_SUPPORTED_FIELDS */} tags: - subpackage_employees parameters: - name: id in: path required: true schema: type: string format: uuid - name: expand in: query description: Which relations should be returned in expanded form. Multiple relation names should be comma separated without spaces. required: false schema: type: array items: $ref: '#/components/schemas/EmployeesIdGetParametersExpandSchemaItems_2' - name: include_remote_data in: query description: Whether to include the original data Merge fetched from the third-party to produce these models. required: false schema: type: boolean - name: include_sensitive_fields in: query description: Whether to include sensitive fields (such as social security numbers) in the response. required: false schema: type: boolean - name: include_shell_data in: query description: Whether to include shell records. Shell records are empty records (they may contain some metadata but all other fields are null). required: false schema: type: boolean - name: remote_fields in: query description: Deprecated. Use show_enum_origins. required: false schema: $ref: '#/components/schemas/EmployeesIdGetParametersRemoteFields' - name: show_enum_origins in: query description: 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](https://help.merge.dev/en/articles/8950958-show_enum_origins-query-parameter) required: false schema: $ref: '#/components/schemas/EmployeesIdGetParametersShowEnumOrigins' - name: Authorization in: header description: Token-based authentication with required prefix "Bearer" required: true schema: type: string - name: X-Account-Token in: header description: Token identifying the end user. required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/Employee_2' /hris/v1/employees/ignore/{model_id}: post: operationId: ignore-create summary: Ignore Create description: 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.{/* BEGIN_HRIS_EMPLOYEE_CREATE_SUPPORTED_FIELDS */}{/* END_HRIS_EMPLOYEE_CREATE_SUPPORTED_FIELDS */} tags: - subpackage_employees parameters: - name: model_id in: path required: true schema: type: string format: uuid - name: Authorization in: header description: Token-based authentication with required prefix "Bearer" required: true schema: type: string - name: X-Account-Token in: header description: Token identifying the end user. required: true schema: type: string responses: '200': description: No response body content: application/json: schema: $ref: '#/components/schemas/employees_ignoreCreate_Response_200' requestBody: content: application/json: schema: $ref: '#/components/schemas/IgnoreCommonModelRequest' /hris/v1/employees/meta/post: get: operationId: meta-post-retrieve summary: Meta Post Retrieve description: Returns metadata for `Employee` POSTs.{/* BEGIN_HRIS_EMPLOYEE_FETCH_SUPPORTED_FIELDS */}{/* END_HRIS_EMPLOYEE_FETCH_SUPPORTED_FIELDS */} tags: - subpackage_employees parameters: - name: Authorization in: header description: Token-based authentication with required prefix "Bearer" required: true schema: type: string - name: X-Account-Token in: header description: Token identifying the end user. required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/MetaResponse' components: schemas: EmployeesGetParametersExpandSchemaItems_2: type: string enum: - company - employments - groups - home_location - manager - pay_group - team - work_location title: EmployeesGetParametersExpandSchemaItems EmployeesIdGetParametersExpandSchemaItems: type: string enum: - company title: EmployeesIdGetParametersExpandSchemaItems PaginatedEmployeeList: type: object properties: next: type: - string - 'null' previous: type: - string - 'null' results: type: array items: $ref: '#/components/schemas/Employee' title: PaginatedEmployeeList MaritalStatusEnum: type: string enum: - SINGLE - MARRIED_FILING_JOINTLY - MARRIED_FILING_SEPARATELY - HEAD_OF_HOUSEHOLD - QUALIFYING_WIDOW_OR_WIDOWER_WITH_DEPENDENT_CHILD title: MaritalStatusEnum Employee: type: object properties: id: type: string format: uuid remote_id: type: - string - 'null' description: The third-party API ID of the matching object. created_at: type: string format: date-time description: The datetime that this object was created by Merge. modified_at: type: string format: date-time description: The datetime that this object was modified by Merge. first_name: type: - string - 'null' description: The employee's first name. last_name: type: - string - 'null' description: The employee's last name. is_contractor: type: - boolean - 'null' description: '`True` if the employee is a contractor, `False` if not.' employee_number: type: - string - 'null' description: The employee's internal identification number. email_address: type: - string - 'null' description: The employee's email address. company: type: - string - 'null' format: uuid description: The subsidiary that the employee belongs to. status: $ref: '#/components/schemas/Status895Enum' description: The employee's status in the accounting system. remote_was_deleted: type: boolean description: 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](https://docs.merge.dev/integrations/hris/supported-features/). field_mappings: oneOf: - $ref: '#/components/schemas/EmployeeFieldMappings' - type: 'null' remote_data: type: - array - 'null' items: $ref: '#/components/schemas/RemoteData' required: - status description: '# The Employee Object ### Description An `Employee` is an individual who works for the company of the linked account. The `Employee` model contains both contractors and full time employees. * An `Employee` is a contractor if `is_contractor` property is `True` * An `Employee` is a full time employee if `is_contractor` property is `False` ### Usage Example Fetch from the `LIST Employees` endpoint and view a company''s employees.' title: Employee EmployeesGetParametersRemoteFields: type: string enum: - employment_status - employment_status,ethnicity - employment_status,ethnicity,gender - employment_status,ethnicity,gender,marital_status - employment_status,ethnicity,marital_status - employment_status,gender - employment_status,gender,marital_status - employment_status,marital_status - ethnicity - ethnicity,gender - ethnicity,gender,marital_status - ethnicity,marital_status - gender - gender,marital_status - marital_status title: EmployeesGetParametersRemoteFields EmployeesIdGetParametersExpandSchemaItems_2: type: string enum: - company - employments - groups - home_location - manager - pay_group - team - work_location title: EmployeesIdGetParametersExpandSchemaItems EmployeesGetParametersShowEnumOrigins: type: string enum: - employment_status - employment_status,ethnicity - employment_status,ethnicity,gender - employment_status,ethnicity,gender,marital_status - employment_status,ethnicity,marital_status - employment_status,gender - employment_status,gender,marital_status - employment_status,marital_status - ethnicity - ethnicity,gender - ethnicity,gender,marital_status - ethnicity,marital_status - gender - gender,marital_status - marital_status title: EmployeesGetParametersShowEnumOrigins EmployeeFieldMappings: type: object properties: organization_defined_targets: type: object additionalProperties: description: Any type linked_account_defined_targets: type: object additionalProperties: description: Any type title: EmployeeFieldMappings Employee_2: type: object properties: id: type: string format: uuid remote_id: type: - string - 'null' description: The third-party API ID of the matching object. created_at: type: string format: date-time description: The datetime that this object was created by Merge. modified_at: type: string format: date-time description: The datetime that this object was modified by Merge. employee_number: type: - string - 'null' description: The employee's number that appears in the third-party integration's UI. company: type: - string - 'null' format: uuid description: The ID of the employee's company. first_name: type: - string - 'null' description: The employee's first name. last_name: type: - string - 'null' description: The employee's last name. preferred_name: type: - string - 'null' description: The employee's preferred first name. display_full_name: type: - string - 'null' description: 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. username: type: - string - 'null' description: The employee's username that appears in the remote UI. groups: type: array items: type: string format: uuid work_email: type: - string - 'null' format: email description: The employee's work email. personal_email: type: - string - 'null' format: email description: The employee's personal email. mobile_phone_number: type: - string - 'null' description: The employee's mobile phone number. employments: type: array items: type: string format: uuid description: Array of `Employment` IDs for this Employee. home_location: type: - string - 'null' format: uuid description: The employee's home address. work_location: type: - string - 'null' format: uuid description: The employee's work address. manager: type: - string - 'null' format: uuid description: The employee ID of the employee's manager. team: type: - string - 'null' format: uuid description: The employee's team. pay_group: type: - string - 'null' format: uuid description: The employee's pay group ssn: type: - string - 'null' description: The employee's social security number. gender: oneOf: - $ref: '#/components/schemas/GenderEnum' - type: 'null' description: The employee's gender. ethnicity: oneOf: - $ref: '#/components/schemas/EthnicityEnum' - type: 'null' description: The employee's ethnicity. marital_status: oneOf: - $ref: '#/components/schemas/MaritalStatusEnum' - type: 'null' description: The employee's filing status as related to marital status. date_of_birth: type: - string - 'null' format: date-time description: The employee's date of birth. hire_date: type: - string - 'null' format: date-time description: '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_date: type: - string - 'null' format: date-time description: The date that the employee started working. If an employee was rehired, the most recent start date will be returned. remote_created_at: type: - string - 'null' format: date-time description: When the third party's employee was created. employment_status: oneOf: - $ref: '#/components/schemas/EmploymentStatusEnum' - type: 'null' description: The employment status of the employee. termination_date: type: - string - 'null' format: date-time description: The employee's termination date. avatar: type: - string - 'null' format: uri description: The URL of the employee's avatar image. custom_fields: type: - object - 'null' additionalProperties: description: Any type description: Custom fields configured for a given model. remote_was_deleted: type: boolean description: 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](https://docs.merge.dev/integrations/hris/supported-features/). field_mappings: oneOf: - $ref: '#/components/schemas/EmployeeFieldMappings' - type: 'null' remote_data: type: - array - 'null' items: $ref: '#/components/schemas/RemoteData' description: '# The Employee Object ### Description The `Employee` object is used to represent any person who has been employed by a company. By default, it returns all employees. To filter for only active employees, set the `employment_status` query parameter to `ACTIVE`. ### Usage Example Fetch from the `LIST Employee` endpoint and filter by `ID` to show all employees.' title: Employee EmployeesIdGetParametersRemoteFields: type: string enum: - employment_status - employment_status,ethnicity - employment_status,ethnicity,gender - employment_status,ethnicity,gender,marital_status - employment_status,ethnicity,marital_status - employment_status,gender - employment_status,gender,marital_status - employment_status,marital_status - ethnicity - ethnicity,gender - ethnicity,gender,marital_status - ethnicity,marital_status - gender - gender,marital_status - marital_status title: EmployeesIdGetParametersRemoteFields EmployeesGetParametersExpandSchemaItems: type: string enum: - company title: EmployeesGetParametersExpandSchemaItems EmployeesIdGetParametersShowEnumOrigins: type: string enum: - employment_status - employment_status,ethnicity - employment_status,ethnicity,gender - employment_status,ethnicity,gender,marital_status - employment_status,ethnicity,marital_status - employment_status,gender - employment_status,gender,marital_status - employment_status,marital_status - ethnicity - ethnicity,gender - ethnicity,gender,marital_status - ethnicity,marital_status - gender - gender,marital_status - marital_status title: EmployeesIdGetParametersShowEnumOrigins employees_ignoreCreate_Response_200: type: object properties: {} description: Empty response body title: employees_ignoreCreate_Response_200 ReasonEnum: type: string enum: - GENERAL_CUSTOMER_REQUEST - GDPR - OTHER title: ReasonEnum MetaResponse: type: object properties: request_schema: type: object additionalProperties: description: Any type status: $ref: '#/components/schemas/LinkedAccountStatus' has_conditional_params: type: boolean has_required_linked_account_params: type: boolean remote_fields: type: array items: type: string format: uuid description: Remote field values to populate required: - request_schema - has_conditional_params - has_required_linked_account_params title: MetaResponse IgnoreCommonModelRequest: type: object properties: reason: $ref: '#/components/schemas/ReasonEnum' message: type: string required: - reason title: IgnoreCommonModelRequest RemoteData: type: object properties: path: type: string description: The third-party API path that is being called. data: description: The data returned from the third-party for this object in its original, unnormalized format. required: - path description: '# The RemoteData Object ### Description The `RemoteData` object is used to represent the full data pulled from the third-party API for an object. ### Usage Example TODO' title: RemoteData GenderEnum: type: string enum: - MALE - FEMALE - NON-BINARY - OTHER - PREFER_NOT_TO_DISCLOSE title: GenderEnum EmploymentStatusEnum: type: string enum: - ACTIVE - PENDING - INACTIVE title: EmploymentStatusEnum LinkedAccountStatus: type: object properties: linked_account_status: type: string can_make_request: type: boolean required: - linked_account_status - can_make_request title: LinkedAccountStatus EmployeesGetParametersEmploymentStatus: type: string enum: - ACTIVE - INACTIVE - PENDING title: EmployeesGetParametersEmploymentStatus Status895Enum: type: string enum: - ACTIVE - INACTIVE title: Status895Enum EthnicityEnum: type: string enum: - 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 title: EthnicityEnum securitySchemes: tokenAuth: type: http scheme: bearer description: Token-based authentication with required prefix "Bearer"