What it does

The createEmpWithJson call creates a new employee or updates an existing one, matched by the employee number (empno), in a single JSON request. If the company has no employee with that number, a new employee is created; if it has one, only the fields you send are updated. Use it to create and update employees from a payroll, HR or recruiting system without typing them in by hand.

What this guide covers

Who can call it, the endpoint and request format, every field and its rules, create versus update, the response and error messages, examples, known pitfalls, a troubleshooting FAQ and a quick reference. The same call is documented in Hebrew in "הוספת עובד JSON API".

Quick start

Get the username and password of a manager user in the system (not a regular employee).
Build a JSON object with u, p, empno and the fields you want to set.
Add "pending_employee": 0, otherwise the employee is set to pending approval.
POST it to https://412.co.il/index.php/api/createEmpWithJson.
Check status, action (insert or update) and skipped_fields in the response.

1. Who can call it

User type	Can call it
Company admin	Yes
Department manager / shift schedule manager	Yes. Any user type other than "employee" is accepted
Regular employee	No. Response: "no authenticated."

The employee is created or updated in the company of the authenticating user. You cannot target another company.

2. Endpoint and request format

Item	Value
URL	https://412.co.il/index.php/api/createEmpWithJson
Method	POST
Body	JSON, sent with a JSON Content-Type header
Authentication	Manager username and password in the fields u and p inside the JSON body (not in headers). Both keys are lowercase

All parameters, including the credentials, go in one JSON object. The only required fields are u, p and empno. Minimal request:

{
  "u": "manager_user",
  "p": "manager_password",
  "empno": "1234",
  "fname": "Dana",
  "lname": "Cohen",
  "pending_employee": 0
}

Fields that take several values (departments, roles, places, schedules) take one comma-separated string, for example "dept": "Sales,Support". Values are matched against the exact name or item code as defined in the system.

3. Fields

A field with an invalid value is skipped and reported in skipped_fields; the other fields are still saved. Only errors in empno, username and password fail the whole request.

Field	Required	Description and rules
u	Yes	Manager username
p	Yes	Manager password
empno	Yes	Employee number (ID number). Digits only; leading zeros are removed (0123 is saved as 123). Decides create versus update
fname	No	First name. For an existing employee an empty value does not erase the name
lname	No	Last name. For an existing employee an empty value does not erase the name
status	No	1 = active, 2 = inactive. A new employee without it is active. Any other value is skipped
pending_employee	No	1 = pending approval, 0 = regular employee. Default on every request: 1
email	No	A valid address not used by another employee in the company
phone	No	Exactly 10 digits, no dashes or spaces
address	No	Hebrew or Latin letters, digits, spaces and commas only
birthday	No	YYYY-MM-DD, a date in the past
start_work_date	No	YYYY-MM-DD. Set on the employee's latest employment period
end_work_date	No	YYYY-MM-DD. Set on the employee's latest employment period
dept	No	Department names, comma-separated. Replaces all current departments
dept_code	No	Department codes. Added to dept when both are sent
role	No	Role names. Not together with role_code
role_code	No	Role codes. Skipped when sent together with role
shift_role	No	Shift role names
place	No	Place (location) names
place_code	No	Place codes. Added to place
default_place	No	The place code of the default place (not its name)
required_gps_location_to_make_record	No	1 = GPS location required to clock in, 0 = not required
store	No	Shift schedule (branch) names
expense_code	No	Expense type codes (030 and 30 count as the same). Enables expenses for the employee
agreement	No	Work agreement name. See "Known pitfalls"
shift_agreement	No	Shift agreement name
soft_block_date	No	YYYY-MM-DD
salary_number	No	The employee's number in the payroll system
comment	No	Free-text comment
username	No	Login username for the employee. Must be unique across the whole system
password	No	Login password. Required with username for a new employee

Field names use underscores exactly as listed (for example role_code, shift_role, default_place, start_work_date). A name with spaces is ignored.

4. Create versus update

A new employee gets the company defaults from the "ערכי ברירת מחדל לעובד" (employee default values) screen, opened from the employee list. An existing employee changes only in the fields you send.

Topic	New employee	Existing employee
Fields not sent	Company defaults: schedules, places, shift roles, departments, GPS, NFC, salary period and work agreement	Unchanged
status	Active if not sent	Changes only if sent
pending_employee	Pending if not sent	Pending if not sent
Empty fname / lname	Saved empty	Current name kept
Departments	From the request, else the company default	If sent, replace all current departments
Work agreement	From the request or the default, effective from the 1st of the current month	Not replaced if the employee already has one
Login (username + password)	A login is created	The current login is updated, only when both fields are sent

5. Response

The response is always JSON with status. Check status in the body, not only the HTTP status code.

Success

{
  "status": true,
  "action": "insert",
  "message": "Employee created successfully",
  "data": {
    "empId": 5821,
    "empNo": "1234",
    "updated_fields": ["fname", "lname", "status", "pending_employee", "dept"],
    "skipped_fields": { "email": "Invalid email format" }
  }
}

Field	Meaning
action	insert = new employee created, update = existing employee updated
message	"Employee created successfully" or "Employee updated successfully"
data.empId	The employee's internal ID in the system
data.empNo	The employee number as saved
data.updated_fields	Fields that were saved, including fields filled from the company defaults
data.skipped_fields	Fields that were not saved, with the reason. The request still succeeded

Failure

Nothing is saved.

{ "status": false, "errors": { "empno": "empno is required" } }

6. Examples

Create an active employee with an app login

{
  "u": "manager_user",
  "p": "manager_password",
  "empno": "1234",
  "fname": "Dana",
  "lname": "Cohen",
  "start_work_date": "2026-10-01",
  "dept": "Sales",
  "role_code": "10",
  "place_code": "TLV01",
  "default_place": "TLV01",
  "agreement": "Hourly agreement",
  "salary_number": "88123",
  "status": 1,
  "pending_employee": 0,
  "username": "dana.cohen",
  "password": "Initial2026"
}

Update an existing employee: end of employment

{
  "u": "manager_user",
  "p": "manager_password",
  "empno": "1234",
  "end_work_date": "2026-12-31",
  "status": 2,
  "pending_employee": 0
}

curl (version 7.82 or later; --json sends a POST with a JSON content type)

curl --json '{"u":"manager_user","p":"manager_password","empno":"1234","fname":"Dana","pending_employee":0}' "https://412.co.il/index.php/api/createEmpWithJson"

7. Known pitfalls

Pending by default: every request without pending_employee sets the employee to pending approval, including an existing, already approved employee. Send "pending_employee": 0 on every request unless the employee should wait for approval.
Work agreement of an existing employee: if the employee already has a work agreement, the call does not replace it, even though agreement appears in updated_fields. Change the agreement in the employee card in the system.
Agreement start date: there is no date field. An agreement set through the call is effective from the 1st of the month in which the request was sent.
Lists replace, they don't add: sending dept or dept_code removes all of the employee's current departments. The same applies to roles, places and schedules. Always send the full list.
One wrong value drops the whole field: in role, role_code, shift_role and store, if one name in the list does not exist, the whole field is skipped. In dept and place only the wrong value is skipped and the rest is saved.
Duplicate employee number: if the company has two employees with the same empno, the request fails. Fix the duplicate in the system first.

Error messages

Keys in errors (the request failed and nothing was saved):

Key	Message	What to do
auth	"no authenticated" (u and p missing) or "no authenticated." (wrong credentials, or a non-manager user)	Check u and p inside the JSON body and use a manager user
auth / json	"Invalid JSON data: …"	The body is not valid JSON. Check quotes, trailing commas and UTF-8 encoding
empno	"empno is required"	Add empno
empno	"empno must be numeric and cannot start with '0'."	Send digits only
empno	"EmpNo is duplicated"	Two employees in the company have this number. Fix the duplicate in the system
username	"username … already exists."	The username is taken. Choose another
username	"username is required when a password is set"	Send username together with password
password	"password is required when a username is set for a new employee"	For a new employee send password too
db / exception	Server error	The whole operation was rolled back. Retry, and contact support if it repeats

Messages in skipped_fields (the request succeeded, the field was not saved):

Field	Message
dept / dept_code	"Department … does not exist"
role / role_code	"Role … does not exist" / "Role code … does not exist" / "cant send role and role code together"
shift_role	"Shift role … does not exist"
place / place_code / default_place	"Place … does not exist" / "Place code … does not exist" / "default_place … does not exist"
store	"Store … does not exist"
expense_code	"Expense code … does not exist"
agreement / shift_agreement	"Agreement … does not exist" / "Shift agreement … does not exist"
email	"Invalid email format" / "Email is duplicated"
phone	"phone must be a 10-digit number."
address	"Address must not contain special characters"
birthday	"birthday must be a valid date in YYYY-mm-dd format" / "birthday must be a date in the past."
status	"status must be 1 (active) or 2 (inactive)."
start_work_date / end_work_date / soft_block_date	"… must be a valid date in YYYY-mm-dd format."

FAQ and troubleshooting

❓ I get "no authenticated."

Wrong username or password, or the user is a regular employee. Put u and p inside the JSON body, not in headers, and use a manager user.

❓ The employee was created but is pending approval

"pending_employee": 0 was not sent; the default is pending. Send the request again with 0, or approve the employee in the system.

❓ I updated an approved employee and it went back to pending

Same cause: every request without pending_employee sets the employee to pending. Add "pending_employee": 0 to every update.

❓ The request succeeded but a field was not saved

Look for the field in skipped_fields in the response; the reason is there, for example a department that does not exist or a phone that is not 10 digits.

❓ I sent a new department and the employee lost the old ones

dept replaces all departments. Send the full comma-separated list.

❓ I sent a new work agreement for an existing employee and nothing changed

The call does not replace an existing agreement. Change it in the employee card in the system.

❓ "default_place … does not exist" although the place exists

default_place takes the place code, not the name.

❓ One wrong role in the list and none of the roles were saved

In role, role_code, shift_role and store one wrong value drops the whole field. Fix the name or item code and send again.

❓ "username … already exists."

The username is used by another employee, possibly in another company: usernames are unique across the whole system. Choose another one.

❓ The employee number lost its leading zero

Leading zeros in empno are removed. 0123 is saved as 123, and any request with 0123 updates employee 123.

❓ Is there a "Draft" status (3)?

No. status accepts only 1 (active) and 2 (inactive). For a pending employee use pending_employee: 1.

❓ Is dept required for a new employee?

No. A new employee without dept gets the company's default departments, if any are set.

❓ How do I delete an employee through the call?

The call does not delete employees. To end employment send "status": 2 and end_work_date.

❓ How do I know whether an employee was created or updated?

From action in the response: insert for a new employee, update for an existing one.

Glossary

empno - the employee number (ID number) the call uses to decide between create and update.
Pending employee - an employee who was created and not yet approved in the system.
skipped_fields - fields that were not saved, with the reason.
updated_fields - fields that were saved.
Company defaults - the settings a new employee gets when a field is not sent.

Quick reference

Goal	How	Effect
Create an employee	POST with a new empno	New employee with the company defaults
Update an employee	POST with an existing empno	Only the sent fields change
Keep the employee approved	"pending_employee": 0	Not moved to pending
End employment	"status": 2 and end_work_date	Employee becomes inactive
Give an app login	username and password	A login is created or updated

הוספת עובד JSON API
API להוספת עובד חדש
api לקבלת רשימת עובדים
שאלות ותשובות בנושא API

מאמרים קשורים

Developer Guide: Create/Update Employee API