Create Employee - Bindbee Docs

POST

api

hris

employees

Create Employee

curl --request POST \
  --url https://api.bindbee.dev/api/hris/v1/employees \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-connector-token: <x-connector-token>' \
  --data '
{
  "employee_number": "1",
  "company": "018af1fe-1250-772d-87c5-6f725a579e8a",
  "first_name": "Kunal",
  "middle_name": "Christopher",
  "last_name": "Tyagi",
  "preferred_name": "Dark Knight",
  "display_full_name": "Kunal Tyagi",
  "username": "kunaltyagi",
  "designation": "Chief Technology Officer",
  "groups": [
    "<unknown>"
  ],
  "department": "Engineering",
  "division": "Bangalore Division",
  "work_email": "[email protected]",
  "personal_email": "[email protected]",
  "mobile_phone_number": "+1234567890",
  "home_phone_number": "+1234567890",
  "country_code": "+91",
  "home_location": {
    "city": "London",
    "country": "UK",
    "location": "UK-HO-London",
    "name": "UK-HO-London",
    "postal_code": "56273",
    "state": "LND",
    "street_1": "1011",
    "street_2": "Lane number 4, Golden Villa"
  },
  "work_location": {
    "city": "London",
    "country": "UK",
    "location": "UK-HO-London",
    "name": "UK-HO-London",
    "postal_code": "56273",
    "state": "LND",
    "street_1": "1011",
    "street_2": "Lane number 4, Golden Villa"
  },
  "manager": "550e8400-e29b-41d4-a716-446655440000",
  "pay_group": "018af1fe-1250-77c5-9fcd-4bca1e4568f4",
  "ssn": "1234567890",
  "gender": "MALE",
  "ethnicity": "ASIAN_OR_INDIAN_SUBCONTINENT",
  "marital_status": "SINGLE",
  "date_of_birth": "1986-10-27T00:00:00Z",
  "start_date": "2023-03-05T00:00:00Z",
  "remote_created_at": "2023-03-01T00:00:00Z",
  "employment_status": "INACTIVE",
  "termination_date": "2023-06-05T00:00:00Z",
  "avatar": "http://alturl.com/h2h8m",
  "payroll_run_calendar": "018af1fe-1250-77c5-9fcd-4bca1e4568f4",
  "additional_attributes": {
    "contract_end_date": "2025-12-31T00:00:00",
    "emergency_contact": "John Doe - +1-234-567-8901",
    "employee_type": "Contract",
    "language_proficiency": "English, French",
    "marital_status": "Married",
    "performance_rating": "Excellent",
    "previous_employer": "TechCorp"
  },
  "custom_fields": {
    "customTshirtSize": "XXL"
  }
}
'

{
  "success": true,
  "data": "<string>",
  "error": {}
}

To create an employee in HRIS, you first need to fetch the request body structure that HRIS expects. This structure varies based on the HRIS provider (e.g., BambooHR, ADP, Workday). The request body consists of three parts:

Model Keys: Standard attributes required for all employees.
Additional Attributes: Specific fields required by the chosen HRIS.
Custom Fields: Extra metadata for specific implementations.

Note: Some attributes may have allowed_values, meaning only specific values are permitted based on the customer’s HRIS configuration. Ensure you check for these constraints before submitting the request.

Step 1: Fetch the Required Request Body

Before calling the Create Employee API, you need to get the request structure using the Meta Create Employee API.

Step 2: Create an Employee

Once you have the request body structure, use the Create Employee API to send the request.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

x-connector-token

string

required

Body

application/json

employee_number

string | null

The employee's number that appears in the third-party integration's UI.

Example:

"1"

company

any | null

The ID of the employee's company.

Example:

"018af1fe-1250-772d-87c5-6f725a579e8a"

first_name

string | null

The employee's first name.

Example:

"Kunal"

middle_name

string | null

The employee's middle name.

Example:

"Christopher"

last_name

string | null

The employee's last name.

Example:

"Tyagi"

preferred_name

string | null

The employee's preferred first name.

Example:

"Dark Knight"

display_full_name

string | null

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.

Example:

"Kunal Tyagi"

username

string | null

The employee's username that appears in the remote UI.

Example:

"kunaltyagi"

designation

string | null

The employee's current designation/title

Example:

"Chief Technology Officer"

groups

any[] | null

The IDs of the groups that the employee belongs to.

department

string | null

The employee's department

Example:

"Engineering"

division

string | null

The employee's division

Example:

"Bangalore Division"

work_email

string<email> | null

The employee's work email.

Example:

"[email protected]"

personal_email

string<email> | null

The employee's personal email.

Example:

"[email protected]"

mobile_phone_number

string | null

The employee's mobile phone number.

Example:

"+1234567890"

home_phone_number

string | null

The employee's home phone number.

Example:

"+1234567890"

country_code

string | null

The employee's country code

Example:

"+91"

home_location

HrisAddress · object

The employee's home address.

Show child attributes

home_location.name

string | null

Name of the location

Example:

"UK-HO-London"

home_location.location

string | null

Location

Example:

"UK-HO-London"

home_location.street_1

string | null

Street 1

Example:

"1011"

home_location.street_2

string | null

Street 2

Example:

"Lane number 4, Golden Villa"

home_location.city

string | null

City

Example:

"London"

home_location.state

string | null

State

Example:

"LND"

home_location.postal_code

string | null

Postal Code

Example:

"56273"

home_location.country

string | null

Country

Example:

"UK"

Example:

{
  "city": "London",
  "country": "UK",
  "location": "UK-HO-London",
  "name": "UK-HO-London",
  "postal_code": "56273",
  "state": "LND",
  "street_1": "1011",
  "street_2": "Lane number 4, Golden Villa"
}

work_location

HrisAddress · object

The employee's work address.

Show child attributes

work_location.name

string | null

Name of the location

Example:

"UK-HO-London"

work_location.location

string | null

Location

Example:

"UK-HO-London"

work_location.street_1

string | null

Street 1

Example:

"1011"

work_location.street_2

string | null

Street 2

Example:

"Lane number 4, Golden Villa"

work_location.city

string | null

City

Example:

"London"

work_location.state

string | null

State

Example:

"LND"

work_location.postal_code

string | null

Postal Code

Example:

"56273"

work_location.country

string | null

Country

Example:

"UK"

Example:

{
  "city": "London",
  "country": "UK",
  "location": "UK-HO-London",
  "name": "UK-HO-London",
  "postal_code": "56273",
  "state": "LND",
  "street_1": "1011",
  "street_2": "Lane number 4, Golden Villa"
}

manager

string<uuid> | null

UUID of the employee's manager

Example:

"550e8400-e29b-41d4-a716-446655440000"

pay_group

string<uuid> | null

The employee's pay group

Example:

"018af1fe-1250-77c5-9fcd-4bca1e4568f4"

ssn

string | null

The employee's social security number.

Example:

"1234567890"

gender

string | null

The employee's gender.

Example:

"MALE"

ethnicity

string | null

The employee's ethnicity.

Example:

"ASIAN_OR_INDIAN_SUBCONTINENT"

marital_status

string | null

The employee's filing status as related to marital status

Example:

"SINGLE"

date_of_birth

string | null

The employee's date of birth.

Example:

"1986-10-27T00:00:00Z"

start_date

string | null

The date that the employee started working. If an employee was rehired, the most recent start date will be returned.

Example:

"2023-03-05T00:00:00Z"

remote_created_at

string | null

When the third party's employee was created.

Example:

"2023-03-01T00:00:00Z"

employment_status

string | null

The employment status of the employee. Possible values include: ACTIVE, PENDING, INACTIVE, or - in cases where there is no clear mapping - the original value passed through.

Example:

"INACTIVE"

termination_date

string | null

The employee's termination date.

Example:

"2023-06-05T00:00:00Z"

avatar

string | null

The URL of the employee's avatar image.

Example:

"http://alturl.com/h2h8m"

payroll_run_calendar

any | null

The employee's payroll calendar

Example:

"018af1fe-1250-77c5-9fcd-4bca1e4568f4"

additional_attributes

Additional Attributes · object

Fields related to models other than employee Model

Example:

{
  "contract_end_date": "2025-12-31T00:00:00",
  "emergency_contact": "John Doe - +1-234-567-8901",
  "employee_type": "Contract",
  "language_proficiency": "English, French",
  "marital_status": "Married",
  "performance_rating": "Excellent",
  "previous_employer": "TechCorp"
}

custom_fields

Custom Fields · object

The custom fields related to the model

Example:

{ "customTshirtSize": "XXL" }

Response

Successful Response

success

boolean

required

data

string

required

error

Error · object

Get Employee By IdReturns an Employee object with the given id.

⌘I

Create Employee

curl --request POST \
  --url https://api.bindbee.dev/api/hris/v1/employees \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-connector-token: <x-connector-token>' \
  --data '
{
  "employee_number": "1",
  "company": "018af1fe-1250-772d-87c5-6f725a579e8a",
  "first_name": "Kunal",
  "middle_name": "Christopher",
  "last_name": "Tyagi",
  "preferred_name": "Dark Knight",
  "display_full_name": "Kunal Tyagi",
  "username": "kunaltyagi",
  "designation": "Chief Technology Officer",
  "groups": [
    "<unknown>"
  ],
  "department": "Engineering",
  "division": "Bangalore Division",
  "work_email": "[email protected]",
  "personal_email": "[email protected]",
  "mobile_phone_number": "+1234567890",
  "home_phone_number": "+1234567890",
  "country_code": "+91",
  "home_location": {
    "city": "London",
    "country": "UK",
    "location": "UK-HO-London",
    "name": "UK-HO-London",
    "postal_code": "56273",
    "state": "LND",
    "street_1": "1011",
    "street_2": "Lane number 4, Golden Villa"
  },
  "work_location": {
    "city": "London",
    "country": "UK",
    "location": "UK-HO-London",
    "name": "UK-HO-London",
    "postal_code": "56273",
    "state": "LND",
    "street_1": "1011",
    "street_2": "Lane number 4, Golden Villa"
  },
  "manager": "550e8400-e29b-41d4-a716-446655440000",
  "pay_group": "018af1fe-1250-77c5-9fcd-4bca1e4568f4",
  "ssn": "1234567890",
  "gender": "MALE",
  "ethnicity": "ASIAN_OR_INDIAN_SUBCONTINENT",
  "marital_status": "SINGLE",
  "date_of_birth": "1986-10-27T00:00:00Z",
  "start_date": "2023-03-05T00:00:00Z",
  "remote_created_at": "2023-03-01T00:00:00Z",
  "employment_status": "INACTIVE",
  "termination_date": "2023-06-05T00:00:00Z",
  "avatar": "http://alturl.com/h2h8m",
  "payroll_run_calendar": "018af1fe-1250-77c5-9fcd-4bca1e4568f4",
  "additional_attributes": {
    "contract_end_date": "2025-12-31T00:00:00",
    "emergency_contact": "John Doe - +1-234-567-8901",
    "employee_type": "Contract",
    "language_proficiency": "English, French",
    "marital_status": "Married",
    "performance_rating": "Excellent",
    "previous_employer": "TechCorp"
  },
  "custom_fields": {
    "customTshirtSize": "XXL"
  }
}
'

{
  "success": true,
  "data": "<string>",
  "error": {}
}

Unified Models

​Step 1: Fetch the Required Request Body

​Step 2: Create an Employee

Authorizations

Headers

Body

Response

Step 1: Fetch the Required Request Body

Step 2: Create an Employee