[DEPRECATED] Create employee

We are deprecating this endpoint in favor of the new create employee form endpoint.

Supported integrations

This feature is currently available for the following integrations:

You’d like to see this feature for another integration? Please reach out! We’re always happy to discuss extending our coverage.

This endpoint requires the permission Create and manage employees to be enabled in your scope config.

Example Request Body

{
  "first_name": "John",
  "last_name": "Doe",
  "work_email": "[email protected]",
  "gender": "MALE",
  "date_of_birth": "1986-01-01",
  "start_date": "2020-04-07",
  "job_title": "Integrations Team Lead",
  "home_address": {
    "city": "Berlin",
    "country": "DE",
    "state": "Berlin",
    "street_1": "Sonnenallee 63",
    "zip_code": "12045"
  }
}

Authorizations

Authorization

string

header

required

Create an API key on the Secrets page in the Kombo dashboard.

Headers

X-Integration-Id

string

required

ID of the integration you want to interact with.

Body

application/json

POST /hris/employees Request body

first_name

string

required

The first name of the employee.

last_name

string

required

The last name of the employee.

work_email

string<email>

The email address of the employee to be created. For tools where the personal email address is required, we map this input to the personal email. This is documented on a per-tool basis.

gender

enum<string>

The gender of the employee.

Available options:

MALE,

FEMALE,

NON_BINARY,

NOT_SPECIFIED

job_title

string

The title of the position this person is working in.

home_address

object

The employee's home address.

Show child attributes

home_address.street_1

string

home_address.street_2

string

home_address.city

string

home_address.state

string

home_address.zip_code

string

home_address.country

string

The uppercase two-letter ISO country (e.g., DE). For systems that use codes in formats other than ISO 3166-1 alpha-2, Kombo transforms the ISO Codes to the appropriate value.

date_of_birth

string<date-time>

The employee's date of birth. This is a plain date (i.e., yyyy-MM-dd), all time information is discarded.

mobile_phone_number

string

home_phone_number

string

nationality

string

The uppercase two-letter ISO country (e.g., DE). For systems that use codes in formats other than ISO 3166-1 alpha-2, Kombo transforms the ISO Codes to the appropriate value.

start_date

string<date-time>

Start date of the employee. Also considered to be the hire date. This is a plain date (i.e., yyyy-MM-dd), all time information is discarded.

legal_entity_id

string

The Kombo ID of the legal entity the employee should be in. This field is required for certain integrations.

location_id

string

The Kombo ID of the location the employee should be in. This field is required for certain integrations.

remote_fields

object

Additional fields that we will pass through to specific HRIS systems.

Show child attributes

remote_fields.humaans

object

Fields specific to Humaans.

Show child attributes

remote_fields.humaans.employee

object

Fields that we will pass through to Humaans Employee object.

remote_fields.hibob

object

Fields specific to Hibob.

Show child attributes

remote_fields.hibob.employee

object

Fields that we will pass through to Hibob's Person endpoint.

remote_fields.sympa

object

Fields specific to Sympa.

Show child attributes

remote_fields.sympa.GenericNewHire

object

Fields that we will pass through to Sympa's Employee object.

remote_fields.peoplehr

object

Fields specific to PeopleHR.

Show child attributes

remote_fields.peoplehr.job_role_effective_date

string<date-time>

The effective date of the employee's current role. This is a plain date (i.e., yyyy-MM-dd), all time information is discarded.

remote_fields.peoplehr.department

string

remote_fields.zohopeople

object

Fields specific to Zoho People.

Show child attributes

remote_fields.zohopeople.employee_id

string

A personnel code used to identify individuals working for the business.

Minimum string length: 1

remote_fields.workday

object

Fields specific to Workday.

Show child attributes

remote_fields.workday.job_requisition_id

string

Workday job requisition ID of that the employee should be hired for. Provide either this or position_id.

remote_fields.workday.position_id

string

Workday position ID of that the employee should be hired to. Provide either this or job_requisition_id.

remote_fields.workday.ssn

string

The social security number of the employee.

remote_fields.workday.bank_account

object

The employee's bank account.

Show child attributes

remote_fields.workday.bank_account.iban

string

required

remote_fields.workday.bank_account.bic

string

required

remote_fields.workday.bank_account.bank_name

string

required

remote_fields.deel

object

Fields specific to Deel.

Show child attributes

remote_fields.deel.candidate_id

string

required

The unique identifier of the candidate in the ATS.

remote_fields.deel.candidate_link

string

required

The link to the candidate's profile in the ATS.

remote_fields.bamboohr

object

Fields specific to BambooHR.

Show child attributes

remote_fields.bamboohr.employee

object

Fields that we will pass through to BambooHR Employee object.

remote_fields.oracle

object

Fields specific to Oracle HCM.

Show child attributes

remote_fields.oracle.group_id

string

required

The business unit group ID for which the employee should be created. It can be found as a group with the type null.

remote_fields.oracle.department_id

string

required

The department group ID for which the employee should be created. It can be found as a group with the type DEPARTMENT.

remote_fields.adpworkforcenow

object

Fields specific to ADP Workforce Now.

Show child attributes

remote_fields.adpworkforcenow.onboarding_template_code

string

required

The onboarding template to be used for the created employee. View the possible values in the Kombo dashboard by clicking on the ADP Workforce Now integration and viewing the field report in the settings tab.

remote_fields.adpworkforcenow.applicant_payroll_profile_group_code

string

required

The payroll group code (a.k.a. "Company Code") to be used for the created employee. View the possible values in the Kombo dashboard by clicking on the ADP Workforce Now integration and viewing the field report in the settings tab.

remote_fields.adpworkforcenow.manager_position_id

string

The position ID of the employment of the manager. Available as mappable custom field on employments. Not the employment ID or employment remote ID!

remote_fields.adpworkforcenow.home_organization_unit_code

string

The remote id of a Kombo group with type "DEPARTMENT" that will be used as the employee's home department.

remote_fields.adpworkforcenow.personal_email

string

The personal email for the employee.

remote_fields.azuread

object

Fields specific to Azure AD/Entra ID.

Show child attributes

remote_fields.azuread.password

string

required

Azure / entra requires a password to be set when creating a user. The user has to use the password on his initial sign-in and will be forced to change the password once signed in.

remote_fields.paycor

object

Fields specific to Paycor.

Show child attributes

remote_fields.paycor.paygroupRemoteId

string

required

[REQUIRED] Remote ID of a Kombo Group with type "COST_CENTER"

remote_fields.paycor.departmentRemoteId

string

required

[REQUIRED] Remote ID of a Kombo Group with type "DEPARTMENT"

remote_fields.planday

object

Fields specific to PlanDay.

Show child attributes

remote_fields.planday.department_remote_id

string

required

The remote ID of the department for which the employee should be assigned to. It can be found as a group with the type DEPARTMENT.

remote_fields.dayforce

object

Fields specific to Dayforce.

Show child attributes

The social security number of the employee

remote_fields.dayforce.pay_type

string

required

The pay type of the employee. This needs to be a valid XRefCode from Dayforce.

remote_fields.dayforce.pay_class

string

required

The pay class of the employee. This needs to be a valid XRefCode from Dayforce.

remote_fields.dayforce.pay_group

string

required

The pay group of the employee. This needs to be a valid XRefCode from Dayforce.

remote_fields.dayforce.base_rate

number<double>

required

The base rate of the employee.

Required range: x >= -1.7976931348623157e+308

remote_fields.dayforce.role

string

required

The role of the employee. This needs to be a valid XRefCode from Dayforce.

remote_fields.dayforce.location

string

required

The location of the employee. This needs to be a valid XRefCode from Dayforce.

remote_fields.dayforce.department

string

required

The department of the employee. This needs to be a valid XRefCode from Dayforce.

remote_fields.dayforce.job

string

required

The job of the employee. This needs to be a valid XRefCode from Dayforce.

remote_fields.dayforce.country

string

required

The country of the employee. This needs to be a valid XRefCode from Dayforce.

Response

POST /hris/employees Positive response

status

string

required

Allowed value: "success"

data

object

required

Show child attributes

data.id

string

required

The globally unique ID of this object generated by Kombo. We recommend using this as a stable primary key for syncing.

data.remote_id

string

required

The raw ID of the object in the remote system. We don't recommend using this as a primary key on your side as it might sometimes be compromised of multiple identifiers if a system doesn't provide a clear primary key.

data.employee_number

string | null

required

The employee’s organization-internal employee number.

data.first_name

string | null

required

The employee’s first name.

data.last_name

string | null

required

The employee’s last name.

data.nationality

string | null

required

The employee’s nationality.

data.display_full_name

string | null

required

The employee’s full name, including any middle names. Not all HR systems provide an explicit display name, so we recommend falling back to first_name and last_name.

data.job_title

string | null

required

The employee’s job title.

data.mobile_phone_number

string | null

required

The employee’s mobile phone number.

data.ssn

string | null

required

The employee’s social security number

data.tax_id

string | null

required

The employee’s tax ID.

data.weekly_hours

number<double> | null

required

The employee’s weekly working hours.

Required range: x >= -1.7976931348623157e+308

data.avatar

string | null

required

URL to the employee’s avatar. This is either the raw URL from the HR system (in cases where it can be requested without short-lived authentication) or a URL to a temporarily cached version of the file hosted by Kombo. Kombo will delete the cached file after its deletion in the source system.

data.work_location_id

string | null

required

The Kombo ID of the employee’s work location. The ID can be used to retrieve the work location from the get work locations endpoint.

data.legal_entity_id

string | null

required

The Kombo ID of the employee’s legal entity. The ID can be used to retrieve the legal entity from the get legal entities endpoint.

data.manager_id

string | null

required

The Kombo ID of the employee’s manager. The ID can be used to retrieve the manager from the get employees endpoint.

data.date_of_birth

string<date-time> | null

required

The employee’s date of birth.

data.start_date

string<date-time> | null

required

The date the employee started working for the organization.

data.termination_date

string<date-time> | null

required

The date when the employment ends. Can be in the past or future.

data.remote_created_at

string<date-time> | null

required

The date and time the object was created in the remote system.

data.changed_at

string<date-time>

required

The timestamp when this specific record was last modified. This field only updates when properties directly on this record change, NOT when related or nested models change. For filtering that considers nested data changes, use the updated_after parameter which will return records when either the record itself OR its related models have been updated.

data.remote_deleted_at

string<date-time> | null

required

The date and time the object was deleted in the remote system. Objects are automatically marked as deleted when Kombo can't retrieve them from the remote system anymore. Kombo will also anonymize entries 14 days after they disappear.

data.custom_fields

object

required

A key-value store of fields not covered by the schema. Read more

data.integration_fields

object[]

required

An array of selected passthrough integration fields. Read more

Show child attributes

data.integration_fields.id

string

required

The globally unique ID of this object.

data.integration_fields.key

string

required

The key of the field in the remote system.

data.integration_fields.type

enum<string>

required

DEFAULT: static fields in the remote system.
CUSTOM: fields that are created/editable by the user.

Available options:

DEFAULT,

CUSTOM

data.integration_fields.label

string | null

required

The label of the field. (not always available)

data.integration_fields.value

null

The field's value.

data.remote_data

object

required

Includes the data fetched from the remote system. Please be aware that including this in you scope config might violate other scopes that are set.

Remote data always has the endpoint path that we got the data from as the top level key. For example, it could look like: { "/companies": { ... }}

This is not available on all plans. Reach out to Kombo if you need it.

data.work_email

string | null

The employee’s work email address. If the email address is invalid, we will set this to null.

data.personal_email

string | null

The employee’s personal email address. If the email address is invalid, we will set this to null.

data.gender

The employee’s gender.

Available options:

MALE,

FEMALE,

NON_BINARY,

NOT_SPECIFIED

data.ethnicity

The employee’s ethnicity. In rare cases where we can’t find a clear mapping, the original string is passed through.

Available options:

WHITE,

ASIAN,

HISPANIC_LATINO,

HAWAIIAN,

NATIVE_AMERICAN,

BLACK_AFRICAN_AMERICAN,

MULTIPLE_ETHNICITIES,

DECLINE_TO_SPECIFY

data.marital_status

The employee’s current marital status. In rare cases where we can’t find a clear mapping, the original string is passed through.

Available options:

SINGLE,

MARRIED,

DOMESTIC_PARTNERSHIP,

WIDOWED,

DIVORCED,

SEPARATED,

NOT_MARRIED

data.employment_status

The employee’s current employment status:

ACTIVE: the employee is actively employed
PENDING: the employee is not actively employed yet (but they signed their contract or are part of an onboarding process)
INACTIVE: the employee is not actively employed anymore
LEAVE: the employee is still employed but currently on leave (note that not all HR systems support this status — use our absences API for detailed information)

In rare cases where we can’t find a clear mapping, the original string is passed through.

Available options:

ACTIVE,

PENDING,

INACTIVE,

LEAVE

data.employment_type

The employee’s current employment type:

FULL_TIME: the employee is actively employed
PART_TIME: the employee is working only part of the usual working hours
CONTRACT: the employee is working temporarily under a contract
INTERNSHIP: the employee is working as an intern
FREELANCE: the employee is working as a freelancer
WORKING_STUDENT: the employee is working as a working student
APPRENTICESHIP: the employee is working in an apprenticeship
TRAINING: the employee is working in a training program

In rare cases where we can’t find a clear mapping, the original string is passed through.

Available options:

FULL_TIME,

PART_TIME,

CONTRACT,

INTERNSHIP,

FREELANCE,

WORKING_STUDENT,

APPRENTICESHIP,

TRAINING

data.home_address

object

The employee’s home address.

Show child attributes

data.home_address.city

string | null

data.home_address.country

string | null

Contains the ISO2 country code if possible. If not, it contains the original value.

data.home_address.raw

string | null

If we have address data, this is filled with the raw address string.

data.home_address.state

string | null

data.home_address.street_1

string | null

If we can parse the address data, this field contains the first part of the street information.

data.home_address.street_2

string | null

data.home_address.zip_code

string | null

data.bank_accounts

object[] | null

The employee’s bank accounts.

Show child attributes

data.bank_accounts.iban

string | null

The internationally unique IBAN identifying this account. If we detect a valid IBAN from the account number and this field would otherwise be empty, we will automatically populate this field.

data.bank_accounts.bic

string | null

The internationally unique BIC/SWIFT code identifying the bank behind this account. If we detect a valid BIC from the domestic bank routing number and this field would otherwise be empty, we will automatically populate this field.

data.bank_accounts.account_number

string | null

The bank-specific account number. Some companies use the account number field to put the IBAN here.

data.bank_accounts.holder_name

string | null

The name of the holder of this account.

data.bank_accounts.bank_name

string | null

The name of the bank behind this account.

data.bank_accounts.domestic_bank_routing

object

Show child attributes

data.bank_accounts.domestic_bank_routing.number

string

required

Bank routing number (e.g. DE Bankleitzahl, GB Sort Code, US ABA routing number, AU BSB code). This field is not formatted and therefore might contain delimiters (eg. 01-23-45).

data.bank_accounts.domestic_bank_routing.type

enum<string> | null

required

Enum of the routing type, prefixed with the iso-3166-1-alpha-2 banks origin country. If there is uncertainty about the type, it will be set to null.

Available options:

GB_SORT_CODE,

DE_BANKLEITZAHL,

US_ABA_ROUTING_TRANSIT_NUMBER,

CA_ROUTING_NUMBER,

AU_BSB_CODE,

FR_RIB

warnings

object[]

required

These are the interaction warnings that are shown in the dashboard. They are meant to provide debug information to you. We recommend logging them to the console.

Show child attributes

warnings.message

string

required

General

Features

Guides

HRIS API Reference

General API Reference

DATEV

[DEPRECATED] Create employee

Example Request Body

Authorizations

Headers

Body

Response

General

Features

Guides

HRIS API Reference

General API Reference

DATEV

​Example Request Body

Authorizations

Headers

Body

Response

Example Request Body