Create employee

POST

hris

employees

Authorization

Header

Body

curl --request POST \
  --url https://api.kombo.dev/v1/hris/employees \
  --header 'Authorization: <authorization>' \
  --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",
  "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"
  }
}'

{
  "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",
    "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",
        "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": {}
  }
}

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": "john.doe@acme.com",
  "gender": "MALE",
  "job_title": "Integrations Team Lead",
  "home_address": {
    "city": "Berlin",
    "country": "DE",
    "state": "Berlin",
    "street_1": "Sonnenallee 63",
    "zip_code": "12045"
  },
  "date_of_birth": "1986-01-01",
  "start_date": "2020-04-07"
}

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.

Body

application/json

first_name

string

required

last_name

string

required

work_email

string

required

gender

enum<string>

The gender of the employee.

Available options:

MALE,

FEMALE,

NON_BINARY,

NOT_SPECIFIED

job_title

string

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) of the employee's nationality. For systems that have other formats than ISO 3166-1 alpha-2 codes, 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.

remote_fields

object

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

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

An optional, 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 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

data.ssn

string | null

required

Social security number

data.tax_id

string | null

required

data.gender

required

One of 4 standardized values (MALE, FEMALE, NON_BINARY, or NOT_SPECIFIED) or — in rare cases where can't find a clear mapping — the original string passed through.

Available options:

MALE,

FEMALE,

NON_BINARY,

NOT_SPECIFIED

data.ethnicity

required

One of 8 standardized values (WHITE, ASIAN, HISPANIC_LATINO, HAWAIIAN, NATIVE_AMERICAN, BLACK_AFRICAN_AMERICAN, MULTIPLE_ETHNICITIES, or DECLINE_TO_SPECIFY) or — in rare cases where can't find a clear mapping — the original string passed through.

Available options:

WHITE,

ASIAN,

HISPANIC_LATINO,

HAWAIIAN,

NATIVE_AMERICAN,

BLACK_AFRICAN_AMERICAN,

MULTIPLE_ETHNICITIES,

DECLINE_TO_SPECIFY

data.marital_status

required

One of 7 standardized values (SINGLE, MARRIED, DOMESTIC_PARTNERSHIP, WIDOWED, DIVORCED, SEPARATED, or NOT_MARRIED) or — in rare cases where can't find a clear mapping — the original string passed through.

Available options:

SINGLE,

MARRIED,

DOMESTIC_PARTNERSHIP,

WIDOWED,

DIVORCED,

SEPARATED,

NOT_MARRIED

data.employment_status

required

The current employment status of the employee:

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)

Please note that 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

One of 8 standardized values (FULL_TIME, PART_TIME, CONTRACT, INTERNSHIP, FREELANCE, WORKING_STUDENT, APPRENTICESHIP, or TRAINING) or — in rare cases where can't find a clear mapping — the original string passed through.

Available options:

FULL_TIME,

PART_TIME,

CONTRACT,

INTERNSHIP,

FREELANCE,

WORKING_STUDENT,

APPRENTICESHIP,

TRAINING

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 ID of the employee’s work location. Can be used to retrieve the work location from the hris_locations endpoint.

data.legal_entity_id

string | null

required

The ID of the employee’s legal entity.

data.manager_id

string | null

required

data.home_address

object | null

required

data.bank_accounts

object[] | null

required

data.date_of_birth

string | null

required

YYYY-MM-DDTHH:mm:ss.sssZ

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

Get employments Update employee

curl --request POST \
  --url https://api.kombo.dev/v1/hris/employees \
  --header 'Authorization: <authorization>' \
  --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",
  "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"
  }
}'

{
  "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",
    "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",
        "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": {}
  }
}

General

Features

General API Reference

HRIS API Reference

DATEV API Reference

Silae API Reference

Create employee

Example Request Body

Authorizations

Headers

Body

Response

General

Features

General API Reference

HRIS API Reference

DATEV API Reference

Silae API Reference

​Example Request Body

Authorizations

Headers

Body

Response

Example Request Body