NetSuite RESTlet API: Build Custom Integrations

Most teams running NetSuite reach a point where the system needs to talk to something else, whether that is an online store, a customer database, a shipping tool, or a finance app. The NetSuite REST API is how that connection happens. It gives developers a clean way to read and write NetSuite records over standard web requests, so data moves between systems without anyone copying it by hand.

This guide explains what the NetSuite REST API is, how it differs from RESTlets and the older SOAP service, how to set up authentication, and how to work with records and queries. It also covers practical topics like rate limits, security, and when an integration platform makes more sense than building everything yourself.

What is the NetSuite REST API?

The NetSuite REST API, known inside NetSuite as SuiteTalk REST Web Services, is a JSON based interface for working with your NetSuite account over standard HTTP methods. You send a request, you get a structured response, and you work with records the same way you would with most modern web services.

With it, you can create and update records, read data, run queries, and move between related records using links in the response. Because it returns JSON and follows familiar REST patterns, it tends to be quicker to pick up than the XML based SOAP service, especially for web and mobile projects.

SuiteTalk REST Web Services, RESTlets, and SOAP

These three names get mixed up often, so it helps to separate them clearly.

• SuiteTalk REST Web Services is the standard REST API. You authenticate, call documented endpoints, and work with records through create, read, update, and delete operations. There is nothing to script or deploy.
• A RESTlet is a custom endpoint you build yourself in SuiteScript when you need logic the standard API does not offer.
• SuiteTalk SOAP Web Services is the original XML based option. It is still used for certain bulk jobs and older integrations.

In short, the standard REST API covers most everyday needs, and RESTlets fill the gaps when you need something custom. Both can run side by side in the same project.

Why teams connect NetSuite with other tools

NetSuite usually sits at the center of finance and operations. The value grows when the records inside it stay in step with the other tools a business runs on every day. Without a connection, staff end up retyping orders, customers, and inventory across systems, which wastes time and invites mistakes.

Where built in features fall short

NetSuite ships with import tools and saved searches, and they work well for one off tasks. They start to strain once you need data to sync continuously, react to events as they happen, or follow custom business rules. That is the point where an API based connection earns its keep.

What an API adds to daily workflows

An API turns manual steps into automatic ones. New customers created on a website can appear in NetSuite without a re entry step. Orders can flow into NetSuite the moment they are placed. Stock levels can update across channels as sales happen. The result is fewer duplicate entries and data that stays consistent across the tools your team relies on.

What is a RESTlet in NetSuite?

A RESTlet is a script you write in SuiteScript that behaves like a custom REST endpoint. External applications call it to send and receive data in JSON, and you decide exactly what it does. Because you control the logic, a RESTlet can do things the standard API does not expose, such as combining several updates behind a single call.

How RESTlets work

You write the RESTlet in SuiteScript, deploy it inside NetSuite, and then call it from your application using the same authentication methods the REST API supports. The script receives the request, runs your logic, and returns a response. RESTlets accept and return JSON, which keeps them easy to work with from web and mobile apps.

When to use a RESTlet instead of the standard API

Start with the standard REST API. If documented endpoints already cover the records and actions you need, there is no reason to build and maintain a script. Reach for a RESTlet when you need custom logic, a tailored payload, or an operation the standard API does not include. Many production setups use both, with the standard API handling routine record sync and RESTlets handling the few steps that need special treatment.

How to set up the NetSuite REST API

Setting up access follows a short sequence inside NetSuite. The steps below describe the common path using Token-Based Authentication.

1. Create a user role with permission to access REST Web Services, then assign it to the user that will run the integration.
2. Create an integration record to obtain the consumer key and consumer secret.
3.  Issue an access token to obtain the token ID and token secret.
4. Use those credentials to sign each request your application sends.

Choosing an authentication method

NetSuite supports two methods for the REST API. Token-Based Authentication is built on OAuth 1.0a and is a common choice for connections that run between servers, since its tokens do not expire on a short cycle. OAuth 2.0 suits flows where a person signs in and grants access. Pick the one that matches how your integration runs, then keep the credentials stored safely.

Test the connection with Postman

Before wiring the API into your application, many developers test calls in Postman. NetSuite documents how to set this up, and it lets you confirm that your signatures, headers, and payloads are correct outside of your own code. A working Postman collection also makes a handy reference for the rest of the team.

A simple request example

Here is a plain example using the standard record endpoint. To read a customer, send an authenticated GET request to the customer endpoint with your account ID in the base address and a JSON content type header. The base address follows a steady pattern that includes your account ID, the rest service path, and the record type. To create a customer, send a POST to the customer endpoint with a JSON body that holds the company name, email, and phone. The response returns the new record and a link you can follow to load it in full, which is the link based navigation the REST API uses throughout.

Working with records and queries

Create, read, update, and delete records

The core of the REST API is record handling. You can create new records such as customers, sales orders, and invoices, read existing ones, update fields, and delete records when needed. These four actions, create, read, update, and delete, cover the bulk of what most integrations do day to day.

Run queries with SuiteQL

For anything beyond a single record lookup, the REST API gives you SuiteQL, a query language with a SQL style syntax. SuiteQL lets you filter, sort, join, and page through records using one endpoint, which is far more efficient than pulling records one at a time. It is the right tool when you need filtered datasets, reporting extracts, or reads across several record types at once.

Saved searches through the API

Teams that already rely on saved searches often want that data available to outside systems. You can surface saved search results through the API so existing search logic feeds your integration, which saves you from rebuilding the same filters in code. Where a saved search is not a fit, SuiteQL gives you a flexible alternative.

Using the REST API Browser and Records Catalog

NetSuite publishes two reference tools that are worth knowing before you build. The REST API Browser documents every supported record, field, and endpoint, and the Records Catalog shows which records you can use in queries. Treat these as your source of truth for NetSuite REST API documentation, and check them to confirm a record is available before you write code against it.

Handling rate limits, concurrency, and pagination

NetSuite controls API traffic with concurrency limits, which cap how many requests run at the same time rather than how many you send per minute. The exact limit depends on your account and license, so confirm the current figure in NetSuite’s documentation. Build your integration to respect that limit, add retry logic with a backoff delay when requests are refused, and use the API’s paging features to move through large result sets in order. Planning for these points early keeps the integration steady as data volumes grow.

Keeping the integration secure

A connection into your finance system deserves careful handling. A few practices help keep things tidy.

• Use a role with only the permissions the integration actually needs, rather than a broad admin role.
• Store tokens and keys in a secure location, not in plain text inside application code.
• Send all traffic over encrypted connections and review access tokens on a regular schedule.

Data protection rules such as GDPR and CCPA shape how customer information should be handled, and frameworks like SOC 2 give teams a structure for assessing controls. Keep these in mind when you design how data moves and where it is stored, and align the integration with your own organization’s policies.

NetSuite REST API vs SOAP: how to choose

The standard REST API, RESTlets, and the SOAP service each suit different jobs. The table below compares them at a glance so you can match the option to the task.

Common ways teams use the NetSuite REST API

Once the connection is in place, the same patterns show up again and again across businesses.

• Keeping customer records in step between a CRM such as Salesforce and NetSuite, so updates in one place appear in the other.
• Syncing orders, payments, and inventory between an online store and NetSuite, so stock and sales stay accurate across channels.
• Creating sales orders and invoices automatically from another system, which removes a manual entry step.
• Feeding NetSuite data into reporting and analytics tools so teams work from current numbers.

Each of these starts with the same building blocks covered above, namely authentication, record actions, and queries.

When to use an integration platform like APPSeCONNECT

Building directly against the API works well when you have developer time and a small number of connections to maintain. The effort adds up once you support many systems, each with its own authentication, data shapes, and quirks, along with ongoing maintenance as those systems change.

An integration platform such as APPSeCONNECT sits between NetSuite and your other tools and manages those connections for you. It handles the authentication, maps fields between systems, and keeps data flowing on a schedule or in response to events, often without custom code. For teams that want connected systems without owning every line of integration code, this is a practical middle path. The right choice depends on your in house resources, the number of systems involved, and how much you want to maintain over time.

Closing thought

The NetSuite REST API gives you a dependable way to connect NetSuite with the rest of your stack. Start with the standard REST Web Services for everyday record sync and queries, add RESTlets where you need custom logic, and lean on the REST API Browser to confirm what each record supports. Whether you build the connection yourself or use an integration platform, the goal is the same, namely accurate data that moves on its own so your team can spend time on the work that matters.

Frequently Asked Questions

What is the difference between the NetSuite REST API and a RESTlet?

The NetSuite REST API, or SuiteTalk REST Web Services, is a standard interface with documented endpoints and no scripting. A RESTlet is a custom endpoint you build in SuiteScript when you need logic the standard API does not provide.

How does the NetSuite REST API handle rate limits?

NetSuite uses concurrency limits that cap simultaneous requests rather than requests per minute. The exact number depends on your account and license, so check NetSuite’s documentation, and add retry logic with a backoff delay plus paging for large result sets.

Can I use OAuth 2.0 with the NetSuite REST API?

Yes. The REST API supports OAuth 2.0, though Token-Based Authentication is common for connections that run between servers because its tokens do not expire on a short cycle.

Where can I find the NetSuite REST API documentation?

NetSuite publishes the REST API Browser and the Records Catalog, which list supported records, fields, and endpoints. These are the reference points to confirm what is available before you build.

Can the REST API create a sales order?

Yes. You can create sales orders, invoices, customers, and other records through the standard record endpoints, which makes order automation one of the most common uses of the API.