Cadbury

How to deploy a RESTlet and call its external URL in NetSuite

Create a RESTlet script record from an uploaded file, use Save and Deploy, release the deployment to an audience role, copy its External URL and call it from a REST client with OAuth 1.0 token-based authentication.

Published 7 min read Watch the walkthrough

The quick answer

Go to Customization > Scripting > Scripts > New, pick your RESTlet file and click Create Script Record. Name it and choose Save and Deploy. On the deployment set Status to Released, select the token user's role in the Audience subtab and save. Copy the External URL from the saved deployment and call it from your REST client with OAuth 1.0, HMAC-SHA256 and your token credentials.

The example is a RESTlet file named income_summary_restlet.js at Alderbrook Trading Co. Tomas Verhagen, an administrator, deploys it so an integration user can call it. The company, names, keys and account number are fictional example data, and the REST client is a generic stand-in for Postman or another API client.

Before you start

The RESTlet file must already be in the File Cabinet and its header must declare the script type with @NScriptType Restlet. Token-based authentication has to be set up before you can call the endpoint: turn on Token-Based Authentication under Setup > Company > Enable Features (SuiteCloud subtab), create an integration record with Token-Based Authentication checked, and create an access token for the user and role from Manage Access Tokens in the Settings portlet. The consumer secret and the token secret are shown once, so copy them when NetSuite displays them. NetSuite favors OAuth 2.0 for new integrations, so check whether your release still lets you create new token-based integration records.

The role the token belongs to needs the permission to log in using access tokens and the permissions for every record the RESTlet reads. A Web Services Only role cannot call a RESTlet.

01. Create the script record from the file

Go to Customization > Scripting > Scripts > New. In Script File choose income_summary_restlet.js and click Create Script Record.

Choose the RESTlet file, then click Create Script Record.

NetSuite reads the script type and API version from the file's header. The new form shows Type RESTlet and API Version 2.1, and it lists a GET, POST, DELETE and PUT function checkbox for the entry points the file exports. Only POST Function is ticked because this file exports only post.

The file's header sets the type and API version, and only POST Function is ticked.

02. Name the script and choose Save and Deploy

Enter the Name Income Summary API and the ID _income_summary_api. An ID that starts with an underscore is saved with its prefix, so the script becomes customscript_income_summary_api. The script ID and the deployment ID are separate values, so read each one from its saved record before you use it. Open the Save menu and click Save and Deploy.

Save and Deploy saves the script and opens a new deployment for it.

You can also click Deploy Script on a saved script, or add a deployment on its Deployments subtab.

03. Release the deployment to a role

The Script Deployment form opens with the script's name as the Title and Status set to Testing. Enter the ID _income_summary_api and change Status to Released. A RESTlet deployment in Testing can be run only by the script owner, so a call that authenticates as another user fails even when that user's role is in the audience. Leave Deployed ticked and Log Level at Debug.

Status is changed from Testing to Released before an integration user calls the RESTlet.

In the Audience subtab select the role the access token's user logs in with. Here that is Integration Reporter, under Internal roles. A role that is not in the audience gets an insufficient-permission error even when the OAuth signature is valid. Click Save.

The audience names the role that the access token's user logs in with.

04. Copy the External URL

The saved deployment shows two addresses. URL is the relative path for use inside NetSuite. External URL is the full address for a program outside NetSuite, on the account's restlets.api.netsuite.com domain, ending in the script and deploy parameters. Copy the External URL instead of building the host name yourself, because sandbox accounts format the host differently from the realm.

The saved deployment shows the URL and the External URL.

05. Call the RESTlet from a REST client

In the REST client set the method to POST and paste the External URL. On the Authorization tab choose OAuth 1.0, set the signature method to HMAC-SHA256 and enter the consumer key and secret from the integration record, the token ID in Access Token, the token secret, and the account ID as Realm. In a sandbox the host uses a hyphen, for example 1234567-sb1, while the realm uses an uppercase underscore form, 1234567_SB1.

OAuth 1.0 with HMAC-SHA256 and the five credential values.

On the Headers tab set Content-Type to application/json and click Send. The client shows 200 OK and the income summary. With text/plain the RESTlet would receive the body as a string instead of an object, so reading requestBody.requestedBy would fail.

A 200 response returns the income summary the RESTlet builds.

You're done when:

  • the script record is a RESTlet whose function checkboxes match what the file exports;
  • the deployment is Deployed, Released, and its audience includes the role of the access token's user;
  • you copied the External URL, not the relative URL;
  • the call returns 200 with the RESTlet's JSON.

Common questions

Why does my RESTlet call fail even though the credentials are right?

Check the deployment before the code. A deployment left in Testing can be run only by the script owner, and an audience that omits the role of the token's user gives an insufficient-permission error. Set Status to Released and add the role under Internal roles.

What is the difference between URL and External URL?

URL is the relative path used inside NetSuite. External URL is the full address on the account's restlets.api.netsuite.com domain for a program outside NetSuite, such as a REST client or another system. Use the External URL for external calls.

What do INVALID_LOGIN_ATTEMPT and insufficient permission mean?

A 401 with INVALID_LOGIN_ATTEMPT usually points at the credentials, the realm, the URL or the client clock. Insufficient permission points at the deployment status, the audience or the role's permissions.

Do I type the full script ID?

You can type an ID that starts with an underscore, such as _income_summary_api, and the saved record shows the full ID with its prefix. The script and the deployment have separate IDs, so read each one from its saved record before you use it in an integration.

Why is only the POST function ticked?

NetSuite lists a checkbox for GET, POST, DELETE and PUT and ticks the ones the file exports. This file exports only post, so a GET request would not be handled.

Which realm do I use for a sandbox?

Use the account ID with an uppercase underscore suffix, for example 1234567_SB1. The host name uses a hyphen, for example 1234567-sb1. Copy the External URL from the sandbox's own deployment.

Should I use token-based authentication for a new integration?

NetSuite favors OAuth 2.0 for new integrations. Check whether your release still lets you create new token-based integration records. Existing token-based integrations keep working as they are.