/employees

Creates an employee for your account. Required scope: w_employees.

🚧

This particular endpoint uses w_employees scope, which can be enabled through the Integrations section found within the Settings menu.

Body

An example body for the POST endpoint follows:

JSON

{
    "state": "draft",
    "employee":
    {
        "firstname": "Zinedin",
        "lastname": "Doe",
        "preferred_name": "Zizu",
        "country": "GB",
        "address":
        {
            "locationString": "Kifisias 95, Athens, Greece"
        },
        "gender": "gender_male",
        "birthdate": "1987-09-23T00:00:00.000Z",
        "marital_status_group":
        {
            "marital_status": "marital_status_married"
        },
        "phone_group":
        [
            {
                "value":
                {
                    "phone_type": "phone_type_mobile",
                    "phone": "[phone]"
                }
            }
        ],
        "work_email": "[email protected]",
        "personal_email":
        [
            {
                "value": "[email protected]"
            }
        ],
        "chat_group":
        [
            {
                "value":
                {
                    "chat_type": "chat_type_slack",
                    "chat_username": "zizu"
                }
            },
            {
                "value":
                {
                    "chat_type": "chat_type_google_meet",
                    "chat_username": "zizu"
                }
            }
        ],
        "social_group":
        [
            {
                "value":
                {
                    "social_type": "social_type_facebook",
                    "social_url": "https://facebook.com/im/zizu"
                }
            }
        ],
        "job_title": "Account Manager ",
        "hire_date": "2021-10-01T00:00:00.000Z",
        "start_date": "2021-10-08T00:00:00.000Z",
        "legal_entity": "e697173f-5853-48c0-8eb4-b9c67ca11a93",
        "department": "3ff4d641",
        "reports_to": "2fce",
        "employment_group":
        [
            {
                "value":
                {
                    "employment_effective_date": "2021-10-08T00:00:00.000Z",
                    "employment_status": "employement_type_full_time"
                }
            }
        ],
        "work_schedule": "5c6",
        "salary_group":
        [
            {
                "value":
                {
                    "salary_effective_date": "2021-10-08T00:00:00.000Z",
                    "salary_pay_type": "salary_pay_type_salary",
                    "salary_pay_rate":
                    {
                        "amount": 90000,
                        "currency": "USD",
                        "frequency": "year"
                    },
                    "salary_pay_schedule": "salary_pay_schedule_every_15_days",
                    "salary_overtime_status": "salary_overtime_status_exempt",
                    "salary_justification": "salary_justification_new_hire"
                }
            }
        ],
        "bank_details_group":
        {
            "bank_details_bank_name": "Sterling",
            "bank_details_iban": "STR123456789",
            "bank_details_account_number": "234434"
        },
        "social_security_number_group":
        {
            "social_security_number_number": "XI5542",
            "social_security_number_issue_date": "1992-05-05T00:00:00.000Z"
        },
        "national_identification_number_group":
        {
            "national_identification_number_number": "XI5542",
            "national_identification_number_issue_date": "1992-05-05T00:00:00.000Z"
        },
        "social_insurance_number_group":
        [
            {
                "value":
                {
                    "social_insurance_number_number": "XI5543",
                    "social_insurance_number_issue_date": "1992-05-05T00:00:00.000Z"
                }
            }
        ],
        "tax_identification_number_group":
        {
            "tax_identification_number_number": "IX444301",
            "tax_identification_number_issue_date": "1992-05-05T00:00:00.000Z"
        },
        "nationality": "GB",
        "citizenship":
        [
            {
                "value": "GB"
            }
        ],
        "passport_group":
        [
            {
                "value":
                {
                    "passport_country": "GB",
                    "passport_number": "XIPAS12345",
                    "passport_issue_date": "2005-05-05T00:00:00.000Z",
                    "passport_expiration_date": "2024-05-05T00:00:00.000Z"
                }
            }
        ],
        "education_group":
        [
            {
                "value":
                {
                    "education_start_date": "2004-09-01T00:00:00.000Z",
                    "education_end_date": "2005-09-01T00:00:00.000Z",
                    "education_degree": "MSc",
                    "education_field_of_study": "Marketing",
                    "education_school": "UMIST"
                }
            }
        ],
        "work_experience_group":
        [
            {
                "value":
                {
                    "work_experience_start_date": "2008-05-01T00:00:00.000Z",
                    "work_experience_end_date": "2019-05-01T00:00:00.000Z",
                    "work_experience_job_title": "Marketing Associate",
                    "work_experience_company": "Tesco"
                }
            }
        ],
        "skills":
        [
            {
                "value": "MS Office"
            }
        ],
        "language":
        [
            {
                "value": "Hebrew"
            }
        ],
        "contact_group":
        [
            {
                "value":
                {
                    "contact_name": "Svetlana Doe",
                    "contact_relationship": "contact_relationship_type_mother",
                    "contact_phone": "[phone]",
                    "contact_email": "[email protected]",
                    "contact_country": "GB"
                }
            }
        ]
    }
}

The request body for creating a new employee has the following fields:

key	type	description
state	string	The state of the employee. Available values should be draft or published. If the employee is already published (has finished the onboarding process) then this value should be published. If there is the need to create an employee and then start the onboarding process, the state should be draft.
employee	employee	Employee keys and values are described in the /employees/:id section.

For custom field example please refer to the /employees/:id PATCH endpoint.