REST Sample Requests
GET Examples
//GET Request: employee record ID 63 &recordtype=employee&id=63 //GET Response: { success: true, data: { id: '63', externalid: 'other_ref', firstname: 'Wilbur', lastname: 'Torres' email: 'wilbur@example.com' } } // Get employee record external id other_ref &recordtype=employee&externalid=other_ref //GET Response: { success: true, data: { id: '63', externalid: 'other_ref', firstname: 'Wilbur', lastname: 'Torres' email: 'wilbur@example.com' } } Â // Get list of classifications &action=list&recordtype=classification //GET Response: { success: true, data: [ {id: 1, externalid: '', name: 'Sales', isinactive: false} {id: 2, externalid: '', name: 'Operations', isinactive: false} {id: 3, externalid: '', name: 'Support',isinactive: false} ] } Â // Get timeentries for employee id 6 between Jan 1st 2014 and Feb 1st 2014 inclusive &action=search&searchtype=employeeTimeInPeriod&employee=6&startdate=2014-01-01&enddate=2014-02-01 //GET Response: { success: true, data: [ {id: 123, employee: 6, date: '2014-01-02'}, {id: 124, employee: 6, date: '2014-01-03'}, {id: 125, employee: 6, date: '2014-01-04'} ] } // Get all payslip PDFs action=list&recordtype=payslippdf // Get payslip PDFs modified since a certain date action=list&recordtype=payslippdf&updated=2018-06-29 // Get payslip PDFs modified since a certain date/time action=list&recordtype=payslippdf&updated=2018-06-29T17:25:22 // NOT Supported Currently generic search facility { action: 'search', recordtype: 'timeentry', filters: [], }
Employee Request | |
---|---|
Request { "action": "list", "recordtype": "employee" } | Response { "success":true, "data":[ {"inactive":"F", "id":"324", "externalid":"", "salutation":"", "firstname":"Captain", "lastname":"Oblivious", "jobtitleid":"", "email":"captoblivious@example.com", "gender":"m", "phone":"", "mobilephone":"", "hiredate":"2011-04-04", "birthdate":"1987-04-22", "releasedate":"2013-11-01", "maritalstatus":"", "subsidiary":"1", "department":"15", "classification":"2", "location":""} ]} |
DELETE Examples
//DELETE Request: delete timeentry record id 204 &recordtype=timeentry&id=204 //DELETE Request: delete timeentry record external id other_ref &recordtype=timeentry&externalid=other_ref
POST Examples
// All get and delete requests can be replicated as post e.g. { action: 'get', recordtype: 'employee', id: '63' } { action: 'delete', recordtype: 'timeentry', id: '63' } //POST Request: Create a new time entry record // employee, payrate, hours and date are mandatory other fields can be optionally set. { action: 'create', recordtype: 'timeentry', data: { employee: 5, payrateid: 23, hours: 5.5, date: '2014-01-12' } } //POST Request: Create multiple time entry records { action: 'create', recordtype: 'timeentry', data: [{ employee: 5, payrateid: 23, hours: 2, date: '2014-01-13' }, { employee: 5, payrateid: 24, hours: 6, date: '2014-01-14' } ] } // POST Request: Search // NOT SUPPORTED CURRENTLY { action: 'search', recordtype: 'timentry', filters : [['isinactive','is','T'], 'and', ['firstname','contains','paul'] ], columns : [ ['field.join'], ['field.join','sum'] ] }
Pay Sub Type Lookup
Pay Sub type Request | |
---|---|
Request { "action": "list", "recordtype": "paysubtype" } | Response {"success":true, "data":[ {"inactive":"T","id":"103","externalid":"","name":"48/52 Bought Leave","showintimeentry":"T"},{"inactive":"F","id":"407","externalid":"","name":"ACC Unpaid Leave","showintimeentry":"T"} ]} |
Department List Request | |
---|---|
Request { "action": "list", "recordtype": "department" } | {"success":true, "data":[ {"inactive":"T","id":"1","externalid":"","namenohierarchy":"Cost of Acquisition"},{"inactive":"F","id":"11","externalid":"","namenohierarchy":"Education"}] } |
Classification List Request | |
---|---|
Request { "action": "list", "recordtype": "classification" } | Response {"success":true, "data":[ {"inactive":"T","id":"1","externalid":"","namenohierarchy":"All Products"},{"inactive":"F","id":"20","externalid":"","namenohierarchy":"API - Development"},{"inactive":"F","id":"1010","externalid":"","namenohierarchy":"API - Partner"} ]} |
Location List Request | |
---|---|
Request  { "action": "list", "recordtype": "location" } | Response {"success":true, "data":[ {"inactive":"T","id":"9","externalid":"","namenohierarchy":"Australia"},{"inactive":"F","id":"35","externalid":"","namenohierarchy":"248 Burwood Rd - Melbourne"},{"inactive":"F","id":"36","externalid":"","namenohierarchy":"3/6 Elizabeth St - Melbourne"} ]} |
 Working Week Request | |
---|---|
Request { "action": "list", "recordtype": "workingweek" } | Response { "success":true, "data":[ {"inactive":"F","id":"79","externalid":"","name":"10 hrs 2|2|2|2|2|0|0", "sunday":"0","monday":"2","tuesday":"2","wednesday":"2","thursday":"2","friday":"2","saturday":"0","isrostered":"T"},{"inactive":"F","id":"77","externalid":"","name":"12 hrs 4|4|4|0|0|0|0", "sunday":"0","monday":"4","tuesday":"4","wednesday":"4","thursday":"0","friday":"0","saturday":"0","isrostered":"F"} ]} |
Additional Examples
Setting Up and Employee To Be Paid By Wages
The default behaviour of the REST interface is to use NetSuite Payroll Configuration to default employees as a salaried employee. This means the system automatically defaults the following fields (employmentstatus: FULLTIME, paytype: SALARY). To configure a waged employee either a new hire or to change an employee from salaried to wages the following fields need to be specified (the example below is assuming an update and creating a normal time pay component).
var syncRequest = { "action" : "function", "function" : "syncemployee", "data" : { "id" : "14211", "payroll" : { "paytype" : "WAGES", "payfromtime" : true }, "component" : [ { "startdate": "2015-01-01", "subtype" : "27", "uom" : "HOUR", "rate" : "20.15", "frequency" : "MONTHLY" } ] } }
The pay component for normal time requires a unit of measure (uom), the employee's hourly rate (rate), a quantity (default number of hours for the period), and the amount (rate * quantity).
Adding Timing To Netsuite To Represent Time Off
Employee leave requests entered in External HR System will need to be translated into the hours of a given leave type and a create request made to create the timeentry records in NetSuite. Each time entry should comprise of 4 fields. Note: Usually 21 is internal id of Annual Leave, 22 internalid of sick leave paid.
Request | Response |
---|---|
Adding Time var timeRequest = { "action" : "create", "recordtype" : "timeentry", "data" : { "employee" : "14211", "date" : "2015-11-03", "paysubtype" : "21", "hours" : "16" } } | Response {"success":true, "data":{"success":true}, "id":"48223", "processms":"576"} |
data as array or object
The data block in the request can be specified either as a single object, or an array of objects
Making Adjustments
As there is no workday reference on the time generated updates can't be made, so instead a change will consist of two time entry additions; the first to represent the negation of the previous request that is being changed, and a second to represent the updated record. Below is an example to negate the previous request and replace it with 8 hours of paid sick leave.
Request | Response |
---|---|
Time Request var timeRequest = { "action" : "create", "recordtype" : "timeentry", "data" : [{ "employee" : "14211", "date" : "2015-11-03", "paysubtype" : "21", "hours" : "-16" }, { "employee" : "14211", "date" : "2015-11-03", "paysubtype" : "22", "hours" : "8" }] } | Response {"success":true, "data":[ {"success":true,"id":"48221"}, {"success":true,"id":"48222"} ], "processms":"697"} |
Updating Leave Balances Where Accrual Is Managed Externally
If leave balances are maintained externally the totals can be updated into payroll in one of two ways:
- Using the syncEmployee function in the payroll block
- Using a newly exposed bulkUpdate function
Note: Whilst you can submit balance updates using syncEmployee, the overhead and additional business logic makes it less efficient and much slower to do so.
Bulk Updates
The bulk update action has two advantages over the syncEmployee function, it allows multiple employees to be submitted in the same request, and it performs no business or record level script resulting in less overhead and better performance. The bulk update is currently only supports the employee record and the update of leave balance fields:
Field In JSON Request Object | Map To NetSuite Employee Field |
---|---|
annualbalance | custentity_pr_annual_leave_accrued |
annualavailable | custentity_pr_annual_leave_available |
personalbalance | custentity_pr_personal_leave_accrued |
personalavailable | custentity_pr_personal_leave_available |
longservicebalance | custentity_pr_lsl_accrued |
longserviceavailable | custentity_pr_lsl_available |
alternatebalance | custentity_pr_alt_leave_balance |
inlieubalance | custentity_pr_time_in_lieu_accrued |
An example request and response is listed below, containing updates for two employees. One or more fields must be specified but it is not mandatory to submit all.
Request | Response |
---|---|
Bulk Update Request {"action":"function", "function":"bulkupdate", "recordtype":"employee", "data":[ {"id": "15857", "inlieubalance" : 15,"alternatebalance": 25}, {"id": "15856", "annualbalance" : 12} ]}Â | Bulk Update Response {"success":true, "data":[ {"success":true,"id":"15857"}, {"success":true,"id":"15856"} ],"processms":"6745"} |
Note: The Update of the employees work schedule (working week) cannot be updated using the bulk update as it is reliant on other actions