Skip to navigation
API ReferenceStaff

Add Staff

Adds a new staff member to your company. Shared rules: see Writing Data.

  • Only name and phone_number are required.
  • If branch_names is left out, the staff member joins the company’s main branch (its oldest branch, the one created at signup). If the company has no branch at all, branch_names returns 400.
  • department_names is optional; empty or left out means no department.
  • If Auto employee ID is on, leave employee_id out (sending it returns 400). Otherwise it must be unique in the company, ignoring upper/lower case.
  • A phone number already used in the company is rejected. Non-Indian numbers are not allowed on an Indian (INR) plan.
  • notify_staff: true sends the WhatsApp app invite (live environment only; default false).
  • bank_details_confirmed: true needs the account number and IFSC code.
  • When the plan’s staff limit is reached the request fails with 400.
  • The old usage, branch_name and department_name keys are rejected.

Custom role needs: staff_details:edit, plus bank_account:edit if any bank field or bank_details_confirmed is sent. It can only add staff to its own branches and departments.

Authentication

AuthorizationApi-Key

Format: “Api-Key {api-key}”

Request

This endpoint expects an object.
namestringRequiredformat: "^[a-zA-Z][a-zA-Z .]*$"2-150 characters

2–150 characters: letters, spaces or dots; must start with a letter. Extra spaces around it are trimmed.

phone_numberstringRequiredformat: "^[0-9]+$"<=15 characters

Digits only, up to 15; must not already be used in the company. With dial_code 91: 10 digits starting with 6, 7, 8 or 9. Other codes: 4-15 digits valid for that country (not allowed on an Indian (INR) plan).

dial_codestringOptionalformat: "^[0-9]{1,4}$"1-4 characters

Country dial code without +, for example 91 (the default). Must be a known country code.

branch_nameslist of stringsOptional

Exact branch names from List Branches (not empty, no repeats). If left out, the staff member joins the main branch.

department_nameslist of stringsOptional

Exact department names from List Departments (no repeats). Leave out or send [] for none.

employee_idstringOptional1-200 characters

Unique in the company, ignoring upper/lower case. Leave out if Auto employee ID is on.

job_titlestringOptional1-150 characters
Up to 150 characters.
joining_datedateOptional

YYYY-MM-DD, between 1950-01-01 and one year from today.

date_of_birthdateOptional

YYYY-MM-DD; the staff member must be 16 to 100 years old.

emailstringOptionalformat: "email"<=200 characters
Official email address.
personal_emailstringOptionalformat: "email"<=200 characters
Personal email address.
current_addressstringOptional1-500 characters
permanent_addressstringOptional1-500 characters
Up to 500 characters.
genderenumOptional
Allowed values:
blood_groupenumOptional
employee_typeenumOptional
marital_statusenumOptional
Allowed values:
panstringOptionalformat: "^[A-Za-z]{5}[0-9]{4}[A-Za-z]$"

Format ABCDE1234F (upper-cased for you).

aadhaarstringOptionalformat: "^[2-9][0-9]{11}$"

12 digits, starting with 2-9.

uanstringOptionalformat: "^[1-9][0-9]{11}$"

12 digits, starting with 1-9.

pf_numberstringOptional<=22 characters

Standard PF number, for example MHBAN00000640000000125 (upper-cased for you).

esi_numberstringOptionalformat: "^[0-9]{10}$"
Exactly 10 digits.
driving_licensestringOptional

2 letters then 13 digits, for example MH1420110012345 (upper-cased for you).

voter_idstringOptional

3 letters then 7 digits, for example ABC1234567 (upper-cased for you).

bank_namestringOptional1-200 characters

Custom-role keys need bank_account:edit to send any bank field.

bank_account_numberstringOptionalformat: "^[0-9]{8,18}$"
8 to 18 digits.
ifsc_codestringOptional

Format HDFC0001234 (upper-cased for you).

account_holder_namestringOptional1-255 characters
bank_details_confirmedbooleanOptional

true confirms the bank details as the API key’s user; needs the account number and IFSC code.

custom_fieldsmap from strings to stringsOptional

Custom field name (exact, from List Custom Fields) mapped to a text value of 1-200 characters, for example {"Blood Donor": "Yes"}. Must not be empty.

notify_staffbooleanOptionalDefaults to false

true sends the WhatsApp app invite (live environment only). Default false.

Response

The staff member was created.
messagestring
statusboolean
dataobject

Errors

400
Bad Request Error
403
Forbidden Error
500
Internal Server Error