Connecting to REST interface

The REST webservice is only accessible via HTTPS and can be authenticated either by email / password credentials or using OAuth Token Based Authentication. For initial testing username and password credentials can be used, you should switch to using OAuth Tokens for production usage.

Request Details Needed For Accessing Sandbox
URL:https://rest.sandbox.netsuite.com/app/site/hosting/restlet.nl?script=385&deploy=1
HTTP Headers:

Content-Typeapplication/json 
Authorization: NLAuth nlauth_account=<NSACCOUNTID>, nlauth_email=person@example.com, nlauth_signature=*******, nlauth_role=1000

HTTP MethodPOST
HTTP Body Request

{
"action": "function",
"function": "getinfo"
}

Note: ******* should be replaced with the current password in plaintext

Sample Requests


GET Examples

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 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

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).


Waged Employee Request
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.


RequestResponse
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.

RequestResponse
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:

  1. Using the syncEmployee function in the payroll block
  2. 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 ObjectMap To NetSuite Employee Field
annualbalancecustentity_pr_annual_leave_accrued
annualavailablecustentity_pr_annual_leave_available
personalbalancecustentity_pr_personal_leave_accrued
personalavailablecustentity_pr_personal_leave_available
longservicebalancecustentity_pr_lsl_accrued
longserviceavailablecustentity_pr_lsl_available
alternatebalancecustentity_pr_alt_leave_balance
inlieubalancecustentity_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.

RequestResponse
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

  • No labels