Sync Employee functions (REST)
The personal information should always be included in the create and subsequent updates and the values are compared against the existing record to decide whether to update or not. For the other groups they will only be validated and updated if they are included in the request. So as an example you may specify the tax details in the first create and then never submit them again so you would not include the tax group.
Personal Information
The personal information should always be included in the create and subsequent updates and the values are compared against the existing record to decide whether to update or not.
| Request Field | Description | NetSuite ID | Memo |
|---|---|---|---|
| id | Netsuite Internal Id | internalid | if set query will be treated as an update |
| salutation | Salutation (Mr, Mrs etc) | salutation | |
| firstname | First name of employee | firstname | |
| lastname | Last name of employee | lastname | |
| jobtitle | Position Title / Job Title | custentity_pr_position_title, title | field will be compared against existing job titles and will be added if not found (e.g Junior Developer). Also sets the standard field Job Title |
| will also be populated into email for payslip field | |||
| gender | gender | gender | m or f (note: if M or F is sent the field will be set to lower case) |
| phone | phone number | phone | |
| mobilephone | mobile number | mobilephone | |
| hiredate | date of start of employment | hiredate | |
| birthdate | date of birth | birthdate | |
| subsidiary | subsidiary | subsidiary | NetSuite One World Only |
| department | department | department | internal id of the netsuite department |
| classification | classification | classification | internalid of the netsuite classification |
| location | location | location | internalid of the netsuite location |
| address.address1 | first line of residential address | addressbook.addr1 | |
| address.address2 | second line of residential address | addressbook.addr2 | |
| address.address3 | third line of residential address | addressbook.addr3 | |
| address.city | city | city | Sydney, Melbourne, etc |
| address.state | state | state | NSW, QLD, SA, NT, TAS, VIC, WA |
| address.zip | postcode | zip | 2046 |
| address.country | country | country | should be set to AU |
The following example shows a request to create a new employee passing basic personal details.
Example Employee Sync Request
{
"action" : "function",
"function" : "syncemployee",
"data" : {
"externalid": "REST-SAMPLE-1",
"salutation": "Miss",
"firstname": "Example",
"lastname": "Person",
"jobtitle": "REST Integration Specialist",
"email": "example@infinetcloud.com",
"gender": "f",
"phone": "09123456",
"mobilephone": "0339195534",
"hiredate": "2021-01-01",
"birthdate": "1980-10-12",
"subsidiary": "2",
"address": {
"address1": "Unit 3",
"address2": "2 Queens Park Circuit",
"address3": "Five Dock",
"city": "Sydney",
"state": "NSW",
"zip": "2046",
"country": "AU"
}
}
}
Bank Detail Information
The bank details default to setting the bank details for payroll associated to the employee record
| Request Field | Description | NetSuite ID | Memo |
|---|---|---|---|
| bankaccount.name | Bank Account Name | custentity_eft_bnk_acct_name | Account Name |
| bankaccount.accountnumber | Bank Account Number | custentity_eft_bnk_acct_no | Account Number |
| bankaccount.bsbnumber | Bank Account BSB | custentity_eft_bsbno | Account BSB |
| bankaccount.paymentdescription | Bank Account Description | custentity_eft_bnk_acct_desc | Description that will appear in payee's statement normally Salary, Wages etc. If not specified will default to "Salary" |
{
"action" : "function",
"function" : "syncemployee",
"data" : {
"externalid": "REST-SAMPLE-1",
"bankaccount" : {
"name" : "Example Bank",
"accountnumber" : "12345678",
"bsbnumber": "123456",
"paymentdescription": "My Salary"
}
}
}
Tax Information
The tax section is used to specify the employees TFN and tax scale. The REST interface currently does not support methods of specifying details for a TFN declaration however the filter information associated to the tax scale is backfilled onto the employee record.
| Request Field | Description | NetSuite ID | Memo |
|---|---|---|---|
| tfn | The employees tax file number | custentity_pr_tfn | The tax field number is mandatory if not known it should be populated with a default (000000000 or 111111111) |
| taxscale | The text description of a tax scale | custentity_employee_tax_scale | If specified this will attempt to match a tax scale by name e.g "No tax-free threshold (1a) with HELP debt". Note: tax scale names can change in new tax years |
| taxscaleid | The netsuite id of a tax scale (e.g. 1) | custentity_employee_tax_scale | If specified the tax scale with this internal id will be set onto the employee record. Note: the internalid of a tax scale could be different in each account. |
Changes associated with STP Version 2 may change the way tax scales work, and you should expect the need to make changes associated with this in the near future.
// tax scales can be looked up using the list function
{
"action": "list",
"recordtype": "taxscale"
}
// Example 1: Setting tax scale by exact name
{"data" : {
"tax" : {
"tfn" : "12345678",
"taxscale" : "No tax-free threshold (1a) with HELP debt"
}
}}
// Example 2: Setting tax scale by internal id from lookup
{"data" : {
"tax" : {
"tfn" : "12345678",
"taxscaleid" : "15"
}
}}
Payroll Information
The payroll information will be used to configure the details of how the basic details of the employee pay
| Request Field | Description | Netsuite ID | Memo |
|---|---|---|---|
| country | Pay country | custentity_pr_country | AU |
| paytype | Pay type for this employee | custentity_pay_type | SALARY or WAGE |
| payrollid | Employees's payroll reference | custentity_pr_payroll_id | ID of employee for payroll purposes |
| payfrequency | Pay frequency for this employee | custentity_pay_freq | WEEKLY or FORTNIGHTLY or MONTHLY |
| state | The payroll state the employee is taxed within (this can be different to the residential address). Should only be set for AU. If country is NZ or UK state should be left blank and default from payroll config. | custentity_employee_payroll_state | Supports NSW, QLD, SA, NT, TAS, VIC, WA |
workingweek | specifies the employee working week pattern, if set the ordinaryhoursperweek will default from this. On create the workingweek will automatically set from the default working week set in payroll config if not entered. | custentity_pr_working_week | specify an internalid of a working week (lookup using { "action" : "list", "recordtype" : "workingweek" }) |
ordinaryhoursperweek | Enter the number of ordinary hours for an employees normal working week. This field will populate the number of normal time hours for a waged employee and forms the basis for a number of basic payroll calculations such as overtime and accrued annual leave. Note: Working Week is typically the master of this field and where possible should be used instead. Ensure you verify expected behaviour in account before using this field. | custentity_pr_standard_week | Set to 0 if employee is pay from netsuite time |
| payfromtime | Wages Employees only. Check this box if the employee is paid based on time logged in NetSuite. The employee will need to be wages and have a pay component of 0 hours with an hourly rate complete. | custentity_pr_pay_time | true or false |
| accrueleavefromtime | Waged Employees Only - Check this box if the employee accrues leave based on the number of hours paid on the payslip (normal time and paid holiday time, does not include overtime) and NOT based on their standard working week. Do not check if salaried. | custentity_pr_accrue_leave_hours | true or false |
| emailforpayslips | The email address used for sending payslips | custentity_pr_email_for_payslips | If empty this will default to the email specified on the employee body |
| employmentstatus | The employees employment status | custentity_employment_status | FULLTIME, CASUAL, CONTRACTOR, DIRECTOR, LABOURHIRE, NONPAYROLL, PARTTIME, TEMPORARY, TERMINATED |
Note: On create of the employee record payroll fields will be defaulted from the payroll configuration record before the specific fields are specified
{
"action" : "function",
"function" : "syncemployee",
"data" : {
"externalid": "REST-SAMPLE-1",
"payroll" : {
"employmentstatus": "CASUAL",
"country" : "AU",
"state" : "QLD",
"paytype": "SALARY",
"payrollid": "REST-SAMPLE-1",
"payfrequency": "WEEKLY",
"payfromtime": "F",
"accrueleavefromtime": "F",
"ordinaryhoursperweek" : "16",
"emailforpayslips": "person@gmail.com"
}
}
}
An example of a full submission include bank detail, superfund, tax and payroll is shown below:
Example Request
{
"action": "function",
"function" : "syncemployee",
"data": {
"salutation": "Mr",
"firstname": "Test",
"lastname": "Person",
"email": "test@infinetcloud.com",
"hiredate": "2013-05-05",
"birthdate": "1976-01-12",
"subsidiary": "2",
"address": {
"address1": "2 Kings Park Circuit",
"address2": "Five Dock",
"address3": "Somewhere",
"city": "Sydney",
"state": "NSW",
"zip": "2046",
"country": "AU"
},
"bankaccount" : {
"name" : "Example Bank",
"accountnumber" : "12345678",
"bsbnumber": "123456",
"paymentdescription": "My Salary"
}
"tax": {
"tfn" : "12345678",
"taxscale" : "No tax-free threshold (1a) with HELP debt"
},
"payroll" : {
"employmentstatus": "CASUAL",
"country" : "AU",
"state" : "QLD",
"paytype": "SALARY",
"payrollid": "REST-SAMPLE-1",
"payfrequency": "WEEKLY",
"payfromtime": "F",
"accrueleavefromtime": "F",
"workingweek" : "7"
"ordinaryhoursperweek" : "16",
"emailforpayslips": "person@gmail.com"
}
}