Skip to navigation
API ReferenceStaff

Update Staff

Updates an existing staff member, including bank details and branch/department assignment. Shared rules: see Writing Data.

  • Partial update: only the fields you send change, and fields can’t be cleared. Send salarybox_id plus at least one other field. notify_staff is not accepted.
  • phone_number and dial_code can be sent alone. Changing the phone number changes the number the staff member logs in with.
  • branch_names replaces the staff member’s branches (must not be empty). department_names replaces their departments; [] removes all.
  • custom_fields changes only the fields you name.
  • employee_id must be unique in the company, ignoring upper/lower case.
  • Bank details can’t be changed once the bank account or UPI is verified. Changing them clears the confirmation; bank_details_confirmed: true confirms and false removes it.
  • Editing a verified ID (PAN, UAN, Aadhaar, driving licence, voter ID, permanent address) marks that verification as no longer current.
  • The old aadhaar_number and employee_code keys are rejected.

Custom role needs: staff_details:edit, plus bank_account:edit if any bank field or bank_details_confirmed is sent. The staff member must be in your My Team scope.

Authentication

AuthorizationApi-Key

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

Request

This endpoint expects an object.
salarybox_idstringRequired1-50 characters
SalaryBox ID of the staff member to update.
namestringOptionalformat: "^[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_numberstringOptionalformat: "^[0-9]+$"<=15 characters

Digits only, up to 15; must not already be used by another staff member. With dial_code 91: 10 digits starting with 6, 7, 8 or 9. Other codes: 4-15 digits valid for that country. Changing it changes the number the staff member logs in with.

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

Country dial code without +, for example 91. Must be a known country code.

branch_nameslist of stringsOptional

Exact branch names from List Branches (not empty, no repeats). Replaces the staff member’s current branches.

department_nameslist of stringsOptional

Exact department names from List Departments (no repeats). Replaces the current departments; [] removes all.

employee_idstringOptional1-200 characters

Unique in the company, ignoring upper/lower case.

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. Editing it marks an earlier verification as no longer current.
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). Editing it marks an earlier verification as no longer current.

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

12 digits, starting with 2-9. Editing it marks an earlier verification as no longer current.

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

12 digits, starting with 1-9. Editing it marks an earlier verification as no longer current.

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). Editing it marks an earlier verification as no longer current.

voter_idstringOptional

3 letters then 7 digits, for example ABC1234567 (upper-cased for you). Editing it marks an earlier verification as no longer current.

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 (account number and IFSC must be sent or already on file); false removes the confirmation.

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"}. Only the named fields change. Must not be empty.

Response

The staff member was updated.
messagestring
statusboolean
dataobject

Errors

400
Bad Request Error
403
Forbidden Error
404
Not Found Error
500
Internal Server Error