Browse Business Software Categories

A
B
C
D
E
F
H
I
M
N
P
R
S
W
Close  

API Management

ERP

IT Management

NetSuite API Guide: SuiteTalk REST, SOAP and RESTlets With Authentication Setup

Sherman Hsieh
Share This Post!
Published
NetSuite API Guide: SuiteTalk REST, SOAP and RESTlets With Authentication Setup

Last updated: November 3, 2026 · Independent guide · We do not sell rankings or coverage.

The NetSuite API is three interfaces: SuiteTalk REST web services for records and SuiteQL queries, SuiteTalk SOAP web services for older integrations, and RESTlets, which are custom SuiteScript endpoints you deploy. Oracle now tells you to build every new integration on REST web services with OAuth 2.0, and its published plan removes SOAP entirely in the 2028.2 release. Below you will find which interface fits which job, the full OAuth 2.0 setup, the concurrency limits and a working first request.

How we researched this

Every step, menu path and limit comes from Oracle’s NetSuite Applications Online Help, checked on November 3, 2026; Oracle’s help pages show no revision date. We also read the top-ranking guides for “netsuite api”, mostly published by companies that sell integration products, which rarely give the concurrency table, the full client credentials setup or the exact error codes.

Before you start

  • Administrator access to enable features and map certificates. The OAuth 2.0 Authorized Applications Management permission, which lets a user set up the client credentials flow, requires two-factor authentication (Oracle, Set Up OAuth 2.0 Roles).
  • A dedicated integration user and custom role. Oracle states that using the Administrator role for web services integrations “is not preferred for security reasons” (Oracle, REST Web Services Prerequisites and Setup).
  • A sandbox, set up separately. Client credentials mappings are not copied between accounts, and a sandbox refresh clears them (Oracle, OAuth 2.0 Client Credentials Setup).
  • OpenSSL and Python to create a certificate and sign a JSON Web Token (JWT).

REST, SOAP or RESTlet: which one to use

Oracle’s SOAP removal FAQ says that from the 2026.1 release all newly built integrations should use REST web services with OAuth 2.0. From 2027.1 you cannot build new integrations with token-based authentication (TBA) or SOAP, from 2027.2 only the last SOAP endpoint (2025.2) is supported, and in 2028.2 all SOAP endpoints are disabled (Oracle, SOAP Removal Plans FAQ).

Interface Best for Authentication Status
SuiteTalk REST web services System-to-system record create, read, update and delete; SuiteQL queries; no server-side code OAuth 2.0, TBA Oracle’s default for new builds
RESTlets Custom logic, several operations in one call, gaps REST cannot cover OAuth 2.0, TBA (user credentials not allowed for new RESTlets; Oracle) Supported; you write and deploy the script
SuiteTalk SOAP web services Maintaining existing integrations only TBA (OAuth 2.0 not available) No new builds from 2027.1; removed in 2028.2

Oracle says a RESTlet can “handle all actions for a business flow in one call,” while REST web services need “no coding and script deployment” (Oracle, RESTlets vs. Other NetSuite Integration Options). A RESTlet can use up to 5,000 governance units per script and 10 MB per string of input or output (Oracle, RESTlet Governance and Security). Start with REST and add a RESTlet only when a flow needs custom logic in one call.

Step 1: Enable the features

Go to Setup > Company > Enable Features and open the SuiteCloud subtab.

  1. In the SuiteTalk (Web Services) section, check REST Web Services and accept the SuiteCloud Terms of Service (Oracle).
  2. In the Manage Authentication section, check OAuth 2.0 (Oracle, Enable the OAuth 2.0 Feature). Check Token-based Authentication in the same section only if you maintain TBA integrations (Oracle, Enable the Token-based Authentication Feature).
  3. If you will call RESTlets with OAuth 2.0, check both Client SuiteScript and Server SuiteScript in the SuiteScript section.
  4. Enable SuiteAnalytics Workbook on the Analytics subtab, which Oracle lists as a REST web services prerequisite. Click Save.

Step 2: Create the integration role

Go to Setup > Users/Roles > User Management > Manage Roles, create or customize a role, and on the Permissions subtab add these on the Setup list (Oracle; Oracle, Set Up OAuth 2.0 Roles):

  • REST Web Services at Full.
  • Log in using OAuth 2.0 Access Tokens for OAuth 2.0, or Log in using Access Tokens for TBA.
  • SuiteAnalytics Workbook at Edit, on the Reports list.
  • The record permissions the integration needs, such as Customers.

Assign the role to the integration user. Every token or certificate inherits exactly what this role can see and do.

Step 3: Create the integration record

Go to Setup > Integration > Manage Integrations > New. Enter a name, leave State as Enabled, and on the Authentication subtab (Oracle, Create Integration Records for Applications to Use OAuth 2.0):

  • Check Client Credentials (Machine to Machine) Grant for server-to-server work, or Authorization Code Grant if a person approves access (this needs a redirect URI that uses https:// or a custom URL scheme).
  • Under OAuth 2.0 scopes, check REST Web Services, RESTlets or both.
  • Click Save and copy the client ID and secret. Oracle shows them only once.

Step 4: Create the certificate and map it (OAuth 2.0 client credentials)

For client credentials, your application signs a JWT with a private key and NetSuite checks it against a public certificate you upload. Oracle accepts x.509 certificates in .cer, .pem or .crt format with RSA keys of 3072 or 4096 bits or EC keys of 256, 384 or 521 bits, and caps validity at two years (Oracle, Certificate Conditions). Oracle’s example for an EC key:

openssl req -new -x509 -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -pkeyopt ec_param_enc:named_curve -nodes -days 365 -out public.pem -keyout private.pem

Then go to Setup > Integration > Manage Authentication > OAuth 2.0 Client Credentials (M2M) Setup, click Create New, choose the entity (your integration user), the role from Step 2 and the application, upload public.pem, and save (Oracle, OAuth 2.0 Client Credentials Setup). Copy the Certificate ID the mapping generates. You can have five active certificates per integration, entity and role combination.

Step 5: Token-based authentication (existing integrations only)

For an existing TBA integration, check Token-based Authentication on the integration record to get a consumer key and secret. Then go to Setup > Users/Roles > Access Tokens > New, pick the application, user and role, and save. NetSuite shows the token ID and token secret once; if you lose them you must create a new token (Oracle, Setting Up Token-Based Authentication). A user with only Access Token Management can create tokens for others but cannot log in with them (Oracle, Set Up Token-based Authentication Roles).

Step 6: Find your account domain

Open Setup > Company > Setup Tasks > Company Information, Company URLs subtab. REST calls use https://<account ID>.suitetalk.api.netsuite.com/services/rest/, followed by record/v1 or query/v1. Oracle recommends keeping it configurable (Oracle, REST Web Services URL Schema and Account-Specific URLs).

Step 7: Get a token and make your first request

The JWT header carries alg (PS256 to PS512 or ES256 to ES512) and kid (the Certificate ID). The payload carries iss (your client ID), scope, aud (the token endpoint), iat, and an exp under 60 minutes after iat (Oracle, The Request Token Structure). This Python example uses PyJWT and requests.

import time, jwt, requests

ACCOUNT = "1234567"            # from Company URLs
CLIENT_ID = "your-client-id"   # from the integration record
CERT_ID = "your-certificate-id"  # from the M2M mapping
BASE = "https://" + ACCOUNT + ".suitetalk.api.netsuite.com/services/rest"
TOKEN_URL = BASE + "/auth/oauth2/v1/token"

now = int(time.time())
assertion = jwt.encode(
    {"iss": CLIENT_ID, "scope": "rest_webservices", "aud": TOKEN_URL,
     "iat": now, "exp": now + 3000},
    open("private.pem").read(), algorithm="ES256",
    headers={"typ": "JWT", "kid": CERT_ID})

tok = requests.post(TOKEN_URL, data={
    "grant_type": "client_credentials",
    "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
    "client_assertion": assertion}).json()
headers = {"Authorization": "Bearer " + tok["access_token"]}

# Read one customer, only three fields
r = requests.get(BASE + "/record/v1/customer/107?fields=companyName,email,entityId", headers=headers)
print(r.status_code, r.json())

# SuiteQL query with a bound parameter
q = requests.post(BASE + "/query/v1/suiteql?limit=100&offset=0",
    headers={**headers, "Prefer": "transient"},
    json={"q": "SELECT id, companyname FROM customer WHERE id > ?", "params": ["0"]})
print(q.json()["totalResults"], q.json()["hasMore"])

The access token is valid for 60 minutes, after which you request a new one (Oracle, POST Request to the Token Endpoint). The fields parameter limits body fields but cannot select sublist fields (Oracle, Getting a Record Instance). SuiteQL needs the Prefer: transient header (Oracle, Executing SuiteQL Queries Through REST Web Services). If your team already reports from NetSuite saved searches, expect to rewrite them as SuiteQL rather than reuse them.

The default page is 1,000 results, the offset must be divisible by the limit, and hasMore says whether another page exists. A query can return at most 100,000 results, or 1,000,000 with SuiteAnalytics Connect (Oracle, Collection Paging).

Step 8: Check the REST API Browser and set concurrency

The REST API Browser is Oracle’s OpenAPI 3.0 reference for the record API, published per release (currently 2026.1). It lists records, sublists, supported operations, request parameters, response and error structures, and field types (Oracle, The REST API Browser).

If one integration needs reserved capacity, go to Setup > Integration > Integration Management > Integration Governance and open it to set its Concurrency Limit; a minimum unallocated limit of one stays reserved for integrations without a defined limit (Oracle, Concurrency Limit per Integration).

Concurrency and governance limits

NetSuite governs concurrent requests rather than publishing a per-minute rate, and the account limit covers web services and RESTlet requests combined (Oracle, Web Services and RESTlet Concurrency Governance). The base limit depends on your service tier, and each SuiteCloud Plus license adds 10 (Oracle, Concurrency Governance Limits Based on Service Tiers; Oracle, Enabling Web Services Concurrent Users with SuiteCloud Plus).

Service tier (contracts from June 2020) Base concurrent requests With one SuiteCloud Plus license
Standard 5 15
Premium 15 25
Enterprise 20 30
Ultimate 20 30

Legacy tiers run from 5 to 20. Development and partner accounts are fixed at five. Every integration in the account, including iPaaS connectors, draws from the same pool.

Common errors and how to fix them

Error Where Likely cause Fix
401 INVALID_LOGIN REST Invalid login token Check Setup > Users/Roles > User Management > View Login Audit Trail, as the error text itself advises
invalid_grant Token endpoint Expired access token Request a fresh token; confirm the Certificate ID and mapping in the target account
400 INVALID_CONTENT REST Invalid field value, such as an item ID that does not exist Read o:errorPath in the response to find the field
404 NONEXISTENT_ID REST Record does not exist Check the internal ID, record type and subsidiary access
429 CONCURRENCY_LIMIT_EXCEEDED REST Too many requests in flight across the account Retry with backoff; queue requests; allocate per-integration limits
400 SSS_REQUEST_LIMIT_EXCEEDED RESTlet Concurrency limit exceeded Same as above
WS_REQUEST_BLOCKED SOAP with TBA ExceededConcurrentRequestLimitFault Same as above

The invalid_grant cause comes from Oracle, POST Request to the Token Endpoint; REST codes and response fields from Oracle, Error Handling in REST Web Services; RESTlet and SOAP concurrency codes from Oracle, Errors Related to Concurrency Violations. Log the whole o:errorDetails array, not only the status.

Two mistakes cause many first-day failures: building on the Administrator role, and expecting a production certificate mapping to work in sandbox. Also, do not retry a timed-out write blindly; check for the record by external ID first, because the write may have succeeded.

Limitations of the native APIs

  • No published request rate. Throughput depends on request duration and on every other integration in the account.
  • Coverage gaps. Oracle tells you to use RESTlets where REST cannot be used (Oracle).
  • SuiteQL caps. Large extracts need date-sliced queries or SuiteAnalytics Connect.
  • Certificate upkeep. Certificates last two years at most, per environment.
  • No retry layer. You build queuing, backoff and logging yourself.

When companies add a third-party integration platform

Companies add an integration platform when they connect several systems and do not want to maintain tokens, paging and retries in code. Workato’s NetSuite REST connector supports OAuth 2.0 client credentials and authorization code grant (Workato documentation), and Celigo documents how to set each NetSuite connection’s concurrency to fit your account’s allowance (Celigo documentation). Both companies sell these products. They share the same concurrency pool. See our guides to ERP data integration and QuickBooks to NetSuite migration.

Related guides

Frequently asked questions

Does NetSuite have a REST API?

Yes. SuiteTalk REST web services handle record operations and SuiteQL queries in JSON. Oracle recommends it, with OAuth 2.0, for new integrations from 2026.1.

Is NetSuite SOAP being deprecated?

Yes. Oracle says no new SOAP integrations can be built from 2027.1, and all SOAP endpoints are disabled in 2028.2. Existing SOAP integrations must move to REST or RESTlets before then.

Should I use token-based authentication or OAuth 2.0?

Use OAuth 2.0. New integrations cannot use TBA from 2027.1. Oracle requires OAuth 2.0 only for new integrations and says you should consider moving existing REST integrations off TBA.

What is the NetSuite API rate limit?

NetSuite limits concurrent requests per account and publishes no per-minute rate: 5 to 20 by service tier, plus 10 per SuiteCloud Plus license. Exceeding it returns 429 CONCURRENCY_LIMIT_EXCEEDED on REST.

How long does a NetSuite OAuth 2.0 access token last?

Sixty minutes. The token endpoint returns expires_in of 3600, and once the token expires you sign a new JWT and request another one.

Sources

Sherman Hsieh

CEO & Editor-in-Chief, Business-Software.com
Independent analysis of enterprise software — ERP, CRM and more
Sherman Hsieh is the founder, CEO, and editor-in-chief of Business-Software.com. He leads the site's independent, buyer-focused coverage of ERP, CRM, and other business systems, including vendor-neutral comparisons, pricing analysis, and implementation guidance. Before founding Business-Software.com, Sherman was an executive at Siebel ...

Users Who Read This Article Also Read