Update employee

PATCH

hris

employees

{employee_id}

object

first_name

string

last_name

string

work_email

string

gender

enum<string>

job_title

string

home_address

object

street_1

string

street_2

string

city

string

state

string

zip_code

string

country

string

date_of_birth

string

mobile_phone_number

string

nationality

string

start_date

string

legal_entity_id

string

location_id

string

remote_fields

object

humaans

object

employee

object

peoplehr

object

job_role_effective_date

string

department

string

zohopeople

object

employee_id

string

workday

object

job_requisition_id

string

deel

object

candidate_id

string

candidate_link

string

ssn

string

marital_status

enum<string>

termination_date

string

tax_id

string

curl --request PATCH \
  --url https://api.kombo.dev/v1/hris/employees/{employee_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Integration-Id: <x-integration-id>' \
  --data '{
  "first_name": "John",
  "last_name": "Doe",
  "work_email": "john.doe@acme.com",
  "ssn": "555-32-6395",
  "tax_id": "12 345 678 901",
  "gender": "MALE",
  "marital_status": "MARRIED",
  "date_of_birth": "1986-01-01",
  "start_date": "2020-04-07",
  "termination_date": "2022-05-20",
  "job_title": "Integrations Team Lead",
  "nationality": "DE",
  "home_address": {
    "city": "Berlin",
    "country": "DE",
    "state": "Berlin",
    "street_1": "Sonnenallee 63",
    "zip_code": "12045"
  }
}'

{
  "status": "success",
  "data": {
    "id": "26vafvWSRmbhNcxJYqjCzuJg",
    "remote_id": "32",
    "employee_number": "3243422",
    "first_name": "John",
    "last_name": "Doe",
    "nationality": "French",
    "display_full_name": "John Doe",
    "job_title": "Integrations Team Lead",
    "work_email": "john.doe@acme.com",
    "personal_email": "john@doe.me",
    "mobile_phone_number": "801-555-4687",
    "ssn": "555-32-6395",
    "tax_id": "12 345 678 901",
    "gender": "MALE",
    "ethnicity": "BLACK_AFRICAN_AMERICAN",
    "marital_status": "MARRIED",
    "employment_status": "INACTIVE",
    "employment_type": "FULL_TIME",
    "weekly_hours": 40,
    "avatar": "https://resources.bamboohr.com/images/photo_person_150x150.png",
    "work_location_id": "7E2gyuv6TmvtByzBxW9Sxt53",
    "legal_entity_id": "xB32bied320csBSsl3XWdlw33",
    "manager_id": "9pf2pxBB8VX8EQMC9aipW2Bo",
    "home_address": {
      "city": "Berlin",
      "country": "DE",
      "raw": "Sonnenallee 63\n12045 Berlin\nGermany",
      "state": "Berlin",
      "street_1": "Sonnenallee 63",
      "street_2": null,
      "zip_code": "12045"
    },
    "bank_accounts": [
      {
        "account_number": "1234567890",
        "bank_name": "Commerzbank",
        "bic": "COBADEFFXXX",
        "domestic_bank_routing": {
          "number": "34567890",
          "type": "DE_BANKLEITZAHL"
        },
        "holder_name": "John Doe",
        "iban": "DE12345678901234567890"
      }
    ],
    "date_of_birth": "1986-01-01T00:00:00.000Z",
    "start_date": "2020-04-07T00:00:00.000Z",
    "termination_date": "2022-05-20T00:00:00.000Z",
    "remote_created_at": "2020-04-07T12:32:01.000Z",
    "changed_at": "2022-08-07T14:01:29.196Z",
    "remote_deleted_at": null,
    "custom_fields": {},
    "remote_data": null
  }
}

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

Example Request Body

{
  "employee_id": "BkgfzSr5muN9cUTMD4wDQFn4",
  "first_name": "John",
  "last_name": "Doe",
  "work_email": "john.doe@acme.com",
  "ssn": "555-32-6395",
  "tax_id": "12 345 678 901",
  "gender": "MALE",
  "marital_status": "MARRIED",
  "date_of_birth": "1986-01-01",
  "start_date": "2020-04-07",
  "termination_date": "2022-05-20",
  "job_title": "Integrations Team Lead",
  "nationality": "DE",
  "home_address": {
    "city": "Berlin",
    "country": "DE",
    "state": "Berlin",
    "street_1": "Sonnenallee 63",
    "zip_code": "12045"
  }
}

Authorizations

Authorization

string

headerrequired

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.

Path Parameters

employee_id

string

required

The ID of the employee that should be updated. You can use their Kombo id or their ID in the remote system by prefixing it with remote: (e.g., remote:12312)

Body

application/json

first_name

string

required

The first name of the employee.

last_name

string

required

The last name of the employee.

work_email

string

required

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.

date_of_birth

string

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

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

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.

ssn

string

The social security number of the employee.

marital_status

enum<string>

The marital status of an employee.

Available options:

SINGLE,

MARRIED,

DOMESTIC_PARTNERSHIP,

WIDOWED,

DIVORCED,

SEPARATED,

NOT_MARRIED

termination_date

string

The date on which the employment ends. This date can be in the past or in the future. This is a plain date (i.e., yyyy-MM-dd), all time information is discarded.

tax_id

string

Tax ID of the employee. Most contries have different formats of that. In Germany, this is the Steuer ID and in the US it's the TIN.

Response

200 - application/json

status

enum<string>

required

Available options:

success

data

object

required

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.work_email

string | null

required

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

data.personal_email

string | null

required

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

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.gender

required

The employee’s gender.

Available options:

MALE,

FEMALE,

NON_BINARY,

NOT_SPECIFIED

data.ethnicity

required

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

required

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

required

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

required

The employee’s current employment type. 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.weekly_hours

number | null

required

The employee’s weekly working hours.

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.home_address

object | null

required

The employee’s home address.

data.bank_accounts

object[] | null

required

The employee’s bank accounts.

data.date_of_birth

string | null

required

The employee’s date of birth.

data.start_date

string | null

required

The date the employee started working for the organization.

data.termination_date

string | null

required

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

data.remote_created_at

string | null

required

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

data.changed_at

string

required

The timestamp when this object was last changed. This value is tracked by Kombo based on changes in the data.

data.remote_deleted_at

string | 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 | null

required

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

data.remote_data

object | null

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.

Create employee Add attachment to employees 🦄

curl --request PATCH \
  --url https://api.kombo.dev/v1/hris/employees/{employee_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Integration-Id: <x-integration-id>' \
  --data '{
  "first_name": "John",
  "last_name": "Doe",
  "work_email": "john.doe@acme.com",
  "ssn": "555-32-6395",
  "tax_id": "12 345 678 901",
  "gender": "MALE",
  "marital_status": "MARRIED",
  "date_of_birth": "1986-01-01",
  "start_date": "2020-04-07",
  "termination_date": "2022-05-20",
  "job_title": "Integrations Team Lead",
  "nationality": "DE",
  "home_address": {
    "city": "Berlin",
    "country": "DE",
    "state": "Berlin",
    "street_1": "Sonnenallee 63",
    "zip_code": "12045"
  }
}'

{
  "status": "success",
  "data": {
    "id": "26vafvWSRmbhNcxJYqjCzuJg",
    "remote_id": "32",
    "employee_number": "3243422",
    "first_name": "John",
    "last_name": "Doe",
    "nationality": "French",
    "display_full_name": "John Doe",
    "job_title": "Integrations Team Lead",
    "work_email": "john.doe@acme.com",
    "personal_email": "john@doe.me",
    "mobile_phone_number": "801-555-4687",
    "ssn": "555-32-6395",
    "tax_id": "12 345 678 901",
    "gender": "MALE",
    "ethnicity": "BLACK_AFRICAN_AMERICAN",
    "marital_status": "MARRIED",
    "employment_status": "INACTIVE",
    "employment_type": "FULL_TIME",
    "weekly_hours": 40,
    "avatar": "https://resources.bamboohr.com/images/photo_person_150x150.png",
    "work_location_id": "7E2gyuv6TmvtByzBxW9Sxt53",
    "legal_entity_id": "xB32bied320csBSsl3XWdlw33",
    "manager_id": "9pf2pxBB8VX8EQMC9aipW2Bo",
    "home_address": {
      "city": "Berlin",
      "country": "DE",
      "raw": "Sonnenallee 63\n12045 Berlin\nGermany",
      "state": "Berlin",
      "street_1": "Sonnenallee 63",
      "street_2": null,
      "zip_code": "12045"
    },
    "bank_accounts": [
      {
        "account_number": "1234567890",
        "bank_name": "Commerzbank",
        "bic": "COBADEFFXXX",
        "domestic_bank_routing": {
          "number": "34567890",
          "type": "DE_BANKLEITZAHL"
        },
        "holder_name": "John Doe",
        "iban": "DE12345678901234567890"
      }
    ],
    "date_of_birth": "1986-01-01T00:00:00.000Z",
    "start_date": "2020-04-07T00:00:00.000Z",
    "termination_date": "2022-05-20T00:00:00.000Z",
    "remote_created_at": "2020-04-07T12:32:01.000Z",
    "changed_at": "2022-08-07T14:01:29.196Z",
    "remote_deleted_at": null,
    "custom_fields": {},
    "remote_data": null
  }
}

General

Features

General API Reference

HRIS API Reference

DATEV API Reference

Update employee

Example Request Body

Authorizations

Headers

Path Parameters

Body

Response

General

Features

General API Reference

HRIS API Reference

DATEV API Reference

​Example Request Body

Authorizations

Headers

Path Parameters

Body

Response

Example Request Body