NetSuite provides powerful integration capabilities through its SuiteTalk REST Web Services, allowing developers to seamlessly interact with NetSuite data using modern RESTful APIs. To make it easier to explore and test these APIs, NetSuite offers a ready-to-use Postman collection containing sample requests for various API endpoints.
In this blog, we’ll walk through how to download and import the official NetSuite REST API Postman collection, and then explore how to use it for your integrations.
Importance of SuiteTalk in the NetSuite Ecosystem
SuiteTalk plays a central role in enabling system-to-system communication within the NetSuite ecosystem.
It acts as the integration layer that allows both internal and external applications to perform operations on NetSuite records programmatically.
One of the best examples of its importance is its use in NetSuite MCP (Model Context Protocol).
The MCP leverages SuiteTalk APIs extensively to perform CRUD (Create, Read, Update) operations across entities such as:
- Sales Orders
- Invoices
- Customer Payments
- Vendors
- Purchase Orders
- and many more.
Through SuiteTalk, NetSuite MCP ensures smooth synchronization of transactions and data between multiple subsidiaries, systems, and integration layers all while maintaining NetSuite’s built-in governance and security model.
In short, SuiteTalk is the backbone of automation and integration inside NetSuite, used not just by external developers, but by NetSuite’s own internal products and enterprise connectors.
Downloading the Postman Collection:
To get started, you’ll need to download the NetSuite REST API Sample Requests package from the SuiteCloud Tools page.
Navigate to:
https://<accountID>.app.netsuite.com/app/external/integration/integrationDownloadPage.nl
- Replace <accountID> with your NetSuite account ID.
- Make sure your NetSuite role has the REST Web Services permission assigned.
Without this permission, the download page may not be accessible. - On the SuiteCloud Tools page, locate the entry named NetSuite REST API Sample Requests (as shown in the screenshot below).
- Download the file NetSuiteRestApiSampleRequests.zip.
Importing the Postman Collection:
- Once you’ve downloaded the collection, follow these steps to import it into Postman:
Unzip the downloaded archive.
Inside, you’ll find a folder containing various sample request files. - Open the Postman application on your system.
- Click Import in the top menu.
After selecting the NetSuiteRestApiSampleRequests Folder , Netsuite Rest Api Tutorial and Netsuite Rest Api Environment Template will be populated, select both and click on Import button.
- from the requests folder inside the extracted archive.
- After importing, navigate to the Collections tab in the left panel of Postman.
You’ll now see a new collection titled NetSuite REST API Tutorial.
This collection includes categorized folders such as:
- 0 Test
- 1 Metadata
- 2 Record CRUD
- 3 Sublist CRUD
- 4 Subrecord CRUD
- 5 External Id
- 6 Filtering
- 7 Query
- 8 Failure Processing
To set the credential values in Postman, you first need to generate authentication details in NetSuite. All the necessary steps and details are explained in this blog:
Getting Started With NetSuite Rest API’s
Let’s cover some of requests from the folder:
Folder 0 Test
The 0 Test folder contains a simple request designed to verify your REST connection setup with NetSuite.
- Request URL: {{REST_SERVICES}}/*
- HTTP Method: GET
- Expected Response: 204 No Content
A 204 response code indicates that your request was successful and your authentication credentials, headers, and environment variables are all configured correctly.
This is the ideal starting point to ensure your REST integration is working before proceeding with other API calls.
Folder 1: Meta Data, Example 1.1 Metadata Options for salesorder
The Metadata folder contains requests to retrieve metadata information about NetSuite record types.
These metadata endpoints help you understand the structure, available fields, and supported operations for each record.
- Request URL: {{REST_SERVICES}}/record/v1/metadata-catalog/salesorder
- HTTP Method: GET
You can use this endpoint for any supported record type, such as customer, item, or invoice, by replacing salesorder in the URL.
Example Output:
{
"name": "salesorder",
"links": [
{
"rel": "canonical",
"href": "https://tstdrv1234567.suitetalk.api.netsuite.com/services/rest/record/v1/metadata-catalog/salesorder",
"mediaType": "application/json"
},
{
"rel": "alternate",
"href": "https://tstdrv1234567.suitetalk.api.netsuite.com/services/rest/record/v1/metadata-catalog/salesorder",
"mediaType": "application/swagger+json"
},
{
"rel": "alternate",
"href": "https://tstdrv1234567.suitetalk.api.netsuite.com/services/rest/record/v1/metadata-catalog/salesorder",
"mediaType": "application/schema+json"
},
{
"rel": "describes",
"href": "https://tstdrv1234567.suitetalk.api.netsuite.com/services/rest/record/v1/salesorder",
"mediaType": "application/schema+json"
}
]
}This response provides links to various metadata representations, including JSON, Swagger, and schema formats, which can be used to explore record definitions programmatically or within your integration tools.
Example 1.2 JSON Schema for salesorder
- Request URL: {{REST_SERVICES}}/record/v1/metadata-catalog/salesorder
- HTTP Method: GET
This endpoint provides the JSON schema for the specified record type in this case, salesorder.
The returned schema includes complete metadata details for the record, such as:
- Standard body fields (e.g., entity, trandate, total, etc.)
- Custom body fields defined in your account
- Line-level fields, including any custom column fields added to the item sublist
This metadata is extremely useful for understanding the record structure programmatically, validating payloads, and dynamically generating data models when building SuiteTalk REST integrations.
Example Create an Inventory Item
- Request URL: {{REST_SERVICES}}/record/v1/inventoryitem
HTTP Method: POST
This request is used to create a new inventory item in NetSuite using the SuiteTalk REST API.
Request Body:
{
"itemid": "Test ITEM",
"displayName": "F3 Test ITem",
"custitem_f3_flag": true,
"price": {
"items": [
{
"currencyPage": {
"id": "1"
},
"priceLevel": {
"id": "1"
},
"quantity": {
"value": 5
},
"price": 25.5
}
]
}
}This payload defines key properties for the new inventory item, including:
- itemid The internal name of the item.
- displayName The display name shown in NetSuite UI.
- custitem_f3_flag Example of a custom body field.
- price.items Nested structure specifying price levels, quantity breaks, and currency.
When the request is successful, NetSuite returns a 201 Created response with the internal ID and URI of the newly created inventory item.
Example Get Customer Records
- Request URL (List): {{REST_SERVICES}}/record/v1/customer
HTTP Method: GET
This request retrieves a list of customer records from NetSuite.
By default, it returns a paginated list containing customer details such as internal ID, entity ID, company name, email, and more.
To fetch a single customer record, simply append the customer’s internal ID to the endpoint:
- Request URL (Single Record):
{{REST_SERVICES}}/record/v1/customer/19179
This returns the complete JSON representation of that specific customer, including standard fields, address information, and any associated custom fields defined in your NetSuite account.
Example 2.3 Update Customer
- Request URL: {{REST_SERVICES}}/record/v1/customer/10165
HTTP Method: PATCH
This request updates an existing customer record in NetSuite.
The PATCH method allows you to modify only the fields you specify, without affecting other data on the record.
Request Body:
{
"companyName": "Folio3 Software"
}
In this example, the customer with internal ID 10165 will have its Company Name updated to “Folio3 Software”.
A successful response returns 204 No Content, indicating that the update was applied successfully.
Folder 4 Subrecord CRUD
🏠 Example Get Customer Addresses
- Request URL: {{REST_SERVICES}}/record/v1/customer/{{lastCustomer}}/addressBook?expandSubResources=true
- HTTP Method: GET
This request retrieves the address subrecord associated with a specific customer.
By including the query parameter expandSubResources=true, the response expands the nested addressBook subresource, returning detailed address information for each entry.
The output includes:
- Address internal IDs
- Default shipping and billing flags
- Complete address details (country, city, state, zip, etc.)
- Any custom fields defined in the address record
This endpoint is particularly useful when you need to fetch customer address book details programmatically for integrations such as shipping, invoicing, or CRM synchronization.
✏️ Example 4.3 Update ZIP on Customer Address
- Request URL: {{REST_SERVICES}}/record/v1/customer/{{lastCustomer}}
- HTTP Method: PATCH
This request updates a specific address subrecord within a customer’s address book.
Using the PATCH method, you can modify only the desired field in this case, the ZIP code without altering other address details.
Request Body:
{
"addressBook": {
"items": [
{
"internalId": {{firstAddress}},
"addressBookAddress": {
"zip": "10005"
}
}
]
}
}Here’s what happens in this example:
- {{firstAddress}} is the internal ID of the specific address being updated.
- The nested addressBookAddress object updates the ZIP code to “10005”.
A successful response returns 204 No Content, confirming that the address ZIP code was updated successfully in the customer’s address subrecord.
Folder 7 Query
🧾 Example 7.1 Unapproved Invoices
- Request URL: {{REST_SERVICES}}/query/v1/suiteql?limit=50
- HTTP Method: POST
This request executes a SuiteQL query to retrieve unapproved invoices from the NetSuite transaction table.
The limit parameter restricts the number of returned results to fifty records.
Request Body:
{
"q": "SELECT id, status, type FROM transaction WHERE type = 'CustInvc' and status = 'D'"
}
This query selects:
- Id: Internal ID of the transaction
- Status: Current status code (‘D’ indicates Unapproved)
- Type: Transaction type (CustInvc = Customer Invoice)
Example Response:
{
"count": 2,
"hasMore": true,
"items": [
{
"links": [],
"id": "27948",
"status": "D",
"type": "CustInvc"
},
{
"links": [],
"id": "27957",
"status": "D",
"type": "CustInvc"
}
],
"offset": 0,
"totalResults": 5
}
The response shows the retrieved unapproved invoices, including their internal IDs and transaction types.
You can adjust the SQL query as needed to filter records by additional conditions, join related tables, or expand the dataset for reporting and automation.
Frequently Asked Questions (FAQ)
1. What is the recommended authentication method for NetSuite integrations?
OAuth 2.0 is the preferred authentication method. You should consider using OAuth 2.0 instead of TBA whenever possible.
2. What happens to access tokens when a NetSuite employee is marked inactive?
If an employee is marked as inactive, then all the access tokens generated using that user will expire. You will need to regenerate them all again if you plan to mark the user active again.
3. How should the Realm header be formatted when using Token-Based Authentication (TBA)?
Realm header in TBA (OAuth 1.0) is required and needs to be in a format, hyphen replaced with underscore and all chars in caps, e.g. ❌: 1234567-sb1, ✅: 1234567_SB1
4. How do I work with lot-numbered and serialized items using NetSuite Inventory & Assembly REST endpoints?
Inventory & Assembly Endpoints for Lot‑Numbered & Serialized Items
1. Base Endpoints
- Inventory: /services/rest/record/v1/inventoryitem
- Assembly: /services/rest/record/v1/assemblyitem
2. Tracking Flags
- Serialized: “isserialitem”: “T”
- Lot‑numbered: “islotitem”: “T”
3. View JSON Schema
Accept: application/schema+json
4. Fetch a Specific Item
GET https://{ACCOUNT_ID}.suitetalk.api.netsuite.com/services/rest/record/v1/inventoryitem/{ITEM_ID}
Accept: application/json
5. Key Finding
Lot‑numbered and serialized behavior both live on the unified inventoryitem/assemblyitem endpoints, controlled by the islotitem and isserialitem flags—no separate REST record types required.
5. Why does the default Postman User-Agent cause errors with RESTlets and Suitelets?
It is observed that using the Postman default `User-Agent` header PostmanRuntime/x.y.z errors out when using with RESTlet or Suitelet. Good practice is always to use a proper header, such as Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36
6. Why should I use the Prefer: transient or Prefer: respond-async headers in SuiteQL and REST requests?
When executing a SuiteQL or REST request, set Prefer: transient in the header to guarantee fresh non-cached results; you may also add Prefer: respond-async if you want the request processed asynchronously.
7. Why can’t I perform delete operations using the current MCP tools?
Currently available MCP tools don’t support the delete operation. For that, you need to build and deploy custom tools manually.
8. How should I structure JSON payloads when sending data via SuiteTalk REST in NetSuite?
Use the structure defined in the metadata catalog exposed by SuiteTalk REST. If a field is a simple scalar (string, number, boolean), supply its value directly. If a field references another record, provide an object with id (or externalId when supported). If the record includes nested data (sublists or subrecords), embed objects or arrays under the parent field exactly as defined in the schema. Custom fields follow the same logic based on their defined type.
You can refer to the official NetSuite REST API Browser documentation for full details.
9. How can I use NetSuite REST services to discover domains and validate user credentials?
You can use the DataCenterUrls REST Service to dynamically discover the correct domains. Helpful when third-party apps want to dynamically retrieve account-specific Web Services (SOAP / REST) and RESTlets URLs without hardcoding.
Sample Req [❌: 123456-sb1, ✅: 123456_sb1]
GET https://rest.netsuite.com/rest/datacenterurls?account=<ACCOUNT_ID>&c=<ACCOUNT_ID>
Sample Res
{
"webservicesDomain": "https://<ACC_ID>.suitetalk.api.netsuite.com",
"restDomain": "https://<ACC_ID>.restlets.api.netsuite.com",
"systemDomain": "https://<ACC_ID>.app.netsuite.com"
}
You can use the REST Roles Service to validate email and password. Helps to validate user credentials from the custom web or mobile app.
Note: Using the REST roles service is not an authentication method. Accessing the REST roles service is not considered a login. This service only returns the list of roles for a user, but does not log the user in.
Sample Req [❌: 123456-sb1, ✅: 123456_SB1]
GET https://rest.netsuite.com/rest/roles
Header
Authorization: NLAuth nlauth_account=<ACC_ID>, nlauth_email=<ACC_EMAIL>, nlauth_signature=<ACC_PASS>
Sample Res
[
{
"account": {
"internalId": "<ACC_ID>",
"name": "<ACC_NAME>",
"type": "SANDBOX"
},
"role": {
"internalId": 3,
"name": "Administrator"
},
"dataCenterURLs": {
"webservicesDomain": "https://<ACC_ID>.suitetalk.api.netsuite.com",
"restDomain": "https://<ACC_ID>.restlets.api.netsuite.com",
"systemDomain": "https://<ACC_ID>.app.netsuite.com"
}
}
]
Related Reads:
Before exploring advanced custom AI integrations, ensure you’ve completed the essential setup steps covered in our previous guides:
1. A Complete Setup Guide for NetSuite AI Connector
2. A Development Guide to Build Custom Tools for NetSuite AI Connector
3. A Setup Guide for NetSuite AI Connector with Postman: API Integration Tutorial
4. Dual API Integration: Using NetSuite MCP Tools with OpenAI and Anthropic
5. Connecting MCP with ChatGPT: A Complete Guide
6. IDE Integration Guide for NetSuite MCP Tools in Cursor & VS Code
7. NetSuite MCP Challenge: Implementation Case Study & Results
Together, these resources form a solid foundation walking you through everything from initial configuration and authentication to advanced deployment so you can integrate AI with NetSuite smoothly and without any issues.
