NetSuite REST API: Complete Developer Guide (2026)

NetSuite REST API: the modern way to integrate

NetSuite provides two APIs for external integration: the legacy SOAP-based web services and the newer REST API (officially called SuiteTalk REST Web Services). The REST API is the recommended approach for new integrations — it's simpler, more performant, and better documented.

TL;DR: The NetSuite REST API provides RESTful CRUD operations on all standard and custom record types, SuiteQL for SQL-like queries, and JSON payloads. Authentication uses OAuth 2.0 (or OAuth 1.0 / Token-Based Authentication for backward compatibility). The REST API browser at https://{accountId}.suitetalk.api.netsuite.com/rest/platform/v1/metadata-catalog provides interactive documentation for all available record types and fields. Rate limits apply — 10 concurrent requests per account for REST API, with additional throttling at high volumes.

Authentication

Token-Based Authentication (TBA)

The most common authentication method for server-to-server integrations:

1. Create an integration record: Setup > Integration > Manage Integrations > New

   • Enable Token-Based Authentication
   • Record the Consumer Key and Consumer Secret

2. Create a token: Setup > Users/Roles > Access Tokens > New

   • Select the application (integration record)
   • Select the user and role
   • Record the Token ID and Token Secret

3. Sign requests: Use OAuth 1.0 signature with:

   • Consumer Key + Consumer Secret (application level)
   • Token ID + Token Secret (user level)
   • Account ID
   • Nonce and timestamp

Each request includes an Authorization header with the OAuth 1.0 signature.

OAuth 2.0

For web applications and scenarios requiring delegated authorization:

1. Register the application: Create an integration record with OAuth 2.0 enabled
2. Authorization flow: User is redirected to NetSuite login, grants access, and receives an authorization code
3. Token exchange: Exchange the authorization code for access and refresh tokens
4. API requests: Include the access token in the Authorization header as a Bearer token
5. Token refresh: Access tokens expire — use the refresh token to obtain new ones

OAuth 2.0 is preferred for applications where users authenticate interactively, while TBA is preferred for background integrations.

Making API requests

Base URL

https://{accountId}.suitetalk.api.netsuite.com/services/rest/

Replace {accountId} with your NetSuite account ID (e.g., 1234567 or 1234567_SB1 for sandbox).

Record operations (CRUD)

Create a record (POST):

POST /services/rest/record/v1/customer
Content-Type: application/json

{
  "companyName": "Acme Corp",
  "email": "info@acme.com",
  "subsidiary": {"id": "1"}
}

Read a record (GET):

GET /services/rest/record/v1/customer/123

Returns JSON with all accessible fields for the record.

Update a record (PATCH):

PATCH /services/rest/record/v1/customer/123
Content-Type: application/json

{
  "phone": "555-0123",
  "email": "new@acme.com"
}

PATCH updates only the specified fields. PUT replaces the entire record.

Delete a record (DELETE):

DELETE /services/rest/record/v1/customer/123

Sublists (line items)

Records with sublists (e.g., sales order lines, vendor bill lines) include nested arrays:

{
  "entity": {"id": "123"},
  "item": {
    "items": [
      {
        "item": {"id": "456"},
        "quantity": 10,
        "rate": 25.00
      },
      {
        "item": {"id": "789"},
        "quantity": 5,
        "rate": 50.00
      }
    ]
  }
}

Filtering and querying records

List records with filters:

GET /services/rest/record/v1/customer?q=companyName CONTAIN "Acme"

Pagination:

GET /services/rest/record/v1/customer?limit=100&offset=0

Default page size is 1000 records. Use limit and offset for pagination through large result sets.

SuiteQL

SuiteQL is NetSuite's SQL-like query language, accessible through the REST API. It's the most powerful way to extract data.

Endpoint:

POST /services/rest/query/v1/suiteql
Content-Type: application/json
Prefer: transient

{
  "q": "SELECT id, companyname, email FROM customer WHERE datecreated > '2026-01-01'"
}

SuiteQL capabilities

• JOIN across related tables
• Aggregate functions (SUM, COUNT, AVG, MAX, MIN)
• GROUP BY and HAVING
• Subqueries
• Built-in functions (TO_DATE, NVL, CASE)

Example queries

Top 10 customers by revenue:

SELECT
  c.companyname,
  SUM(tl.netamount) as total_revenue
FROM transaction t
JOIN transactionline tl ON t.id = tl.transaction
JOIN customer c ON t.entity = c.id
WHERE t.type = 'CustInvc'
  AND t.trandate >= '2026-01-01'
GROUP BY c.companyname
ORDER BY total_revenue DESC
FETCH FIRST 10 ROWS ONLY

Open purchase orders by vendor:

SELECT
  v.companyname as vendor,
  COUNT(t.id) as open_pos,
  SUM(t.foreigntotal) as total_amount
FROM transaction t
JOIN vendor v ON t.entity = v.id
WHERE t.type = 'PurchOrd'
  AND t.status = 'PurchOrd:B'
GROUP BY v.companyname
ORDER BY total_amount DESC

SuiteQL vs. saved searches

SuiteQL is more flexible than saved searches for complex queries:

• JOINs across any tables (saved searches have limited join paths)
• Subqueries and CTEs
• Union queries
• Better performance on large data sets
• Programmatic access through the API

Saved searches are better for:

• Scheduled reports and email alerts
• Dashboard portlets
• User-facing interfaces where non-developers need to modify criteria

REST API Browser

The REST API browser is your interactive documentation:

https://{accountId}.suitetalk.api.netsuite.com/rest/platform/v1/metadata-catalog

For each record type, it shows:

• All available fields with data types
• Required vs. optional fields
• Sublist structures
• Available operations (GET, POST, PATCH, DELETE)
• Field-level help text

Use the browser to explore record schemas before writing integration code. It's more reliable than documentation sites because it reflects your actual NetSuite configuration, including custom fields and custom record types.

RESTlets vs. REST API

NetSuite has two REST-related features that are often confused:

REST API (SuiteTalk REST): The standard API for CRUD operations on records. No custom code required. Works with any standard or custom record type.

RESTlets: Custom SuiteScript endpoints that you write and deploy. RESTlets are SuiteScript 2.x scripts that handle HTTP requests and can execute any business logic — not just CRUD operations.

When to use REST API: Standard operations — create records, read records, update records, query data with SuiteQL.

When to use RESTlets: Custom business logic — calculate pricing, validate data against custom rules, execute workflows, aggregate data across multiple record types in a single API call, or any operation that doesn't map to a simple CRUD action.

Rate limits and performance

Concurrency limits

• REST API: 10 concurrent requests per account (can be increased with additional licenses)
• RESTlets: Shared concurrency with REST API
• SuiteQL: Counted within REST API concurrency

Request throttling

NetSuite throttles requests when you exceed limits:

• HTTP 429 (Too Many Requests) response
• Retry-After header indicates when to retry

Performance tips

Use SuiteQL for bulk reads. A single SuiteQL query returning 1,000 records is much faster than 1,000 individual GET requests.

Use PATCH, not PUT. PATCH updates only the fields you specify. PUT replaces the entire record, which is slower and riskier.

Batch operations. For creating or updating multiple records, consider the REST API's batch endpoint or process records in parallel (within concurrency limits).

Minimize round trips. Use expandSubResources=true to include sublists in a single GET request instead of fetching the record and then each sublist separately.

Cache the metadata catalog. Don't query the metadata catalog on every request — cache it and refresh periodically.

REST API vs. SOAP API

Recommendation: Use the REST API for all new integrations. Use SOAP only if you're maintaining an existing integration that was built on SOAP, or if you need a specific feature only available in SOAP (increasingly rare).