POST
/
api
/
hris
/
v1
/
employees
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": "<any>",
  "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": [
    "<any>"
  ],
  "department": "Engineering",
  "division": "Bangalore Division",
  "work_email": "kunal@bindbee.dev",
  "personal_email": "kunaltyagi77@gmail.com",
  "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": "<any>",
  "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.

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

The employee's work email.

Example:

"kunal@bindbee.dev"

personal_email
string | null

The employee's personal email.

Example:

"kunaltyagi77@gmail.com"

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

The employee's home address.

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

The employee's work address.

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

UUID of the employee's manager

Example:

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

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

additional_attributes
object | null

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

The custom fields related to the model

Example:
{ "customTshirtSize": "XXL" }

Response

200
application/json
Successful Response
success
boolean
required
data
string
required
error
object | null