# NetSuite REST

NetSuite REST enables companies to manage all key business processes within a single online system. 

> **Warning:** **CRITICAL v5.0 UPDATE - BREAKING CHANGES**: Version 5.0 introduces significant authentication changes that require immediate action:- **Authentication Method Changed**: OAuth 2.0 Authorization Grant has been replaced with OAuth 2.0 Client Credentials with JWT-based assertion
> - **Field Renamed**: The authentication field `company` has been renamed to `account_id` for clarity
> - **Certificate ID and Private Key Required**: You must now provide the Certificate ID from your NetSuite M2M integration and the corresponding Private Key for JWT authentication
> - **Migration Required**: Existing v3.x and v4.0 authentications will not work with v5.0. You must create new authentication credentials and update all workflows.See the Migration Guides below for detailed instructions:- [Migration from v3.x to v5.0](#migration-from-v3-x-to-v5-0)
> - [Migration from v4.0 to v5.0](#migration-from-v4-0-to-v5-0)

## Overview

Companies use NetSuite REST for enterprise resource planning (ERP) and to manage inventory, track their financials, host e-commerce stores and maintain customer relationship management (CRM) systems. This flexible platform can be applied to a range of business applications.

> **Info:** **PLEASE NOTE**: Make sure before continuing that you are using the correct NetSuite API. We have a separate page for the [NetSuite SOAP](https://tray.ai/documentation/connectors/service/netsuite-soap) connector as there are several differences and they cannot be used interchangeably.

## **API Information**

The Base URL used for the NetSuite REST connector is **https\://{account-id}.suitetalk.api.netsuite.com**. More information can be found on their main API documentation (**v1.0**) at the NetSuite REST documentation site.

> **Info:** **Version 5.0 Authentication**: This version uses OAuth 2.0 Client Credentials with JWT-based assertion (Machine-to-Machine authentication). For setup instructions, refer to NetSuite's [OAuth 2.0 Client Credentials with Certificate-Based Authentication](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_162686838198.html#subsect_162686947286) documentation.

## Authentication

> **Warning:** **Version 5.0 uses OAuth 2.0 Client Credentials with JWT-based assertion** (Machine-to-Machine authentication). If you're upgrading from a previous version, see the migration guides below:- [Migration from v3.x to v5.0](#migration-from-v3-x-to-v5-0)
> - [Migration from v4.0 to v5.0](#migration-from-v4-0-to-v5-0)

### Migration from v3.x to v5.0

If you're upgrading from version 3.x directly to 5.0, here's what has changed:

| **v3.x Field**  | **v5.0 Field**            | **Change**                                                        |
| --------------- | ------------------------- | ----------------------------------------------------------------- |
| Account ID      | Account ID                | ✅ **Same** - still required                                       |
| Consumer Key    | Client ID                 | ✅ **Same** - terminology updated                                  |
| Consumer Secret | Client Secret             | ✅ **Same** - terminology updated                                  |
| Token ID        | ❌ **Removed**             | No longer needed - replaced by certificate-based auth             |
| Token Secret    | ❌ **Removed**             | No longer needed - replaced by certificate-based auth             |
| N/A             | Certificate ID            | ✅ **New Required** - Certificate ID from NetSuite M2M integration |
| N/A             | Certificate (Private Key) | ✅ **New Required** - Private key for JWT authentication           |

**Key differences from v3.x:**

* **Authentication method completely changed**: v3.x used Token-Based Authentication (TBA) with Token ID and Token Secret. v5.0 uses OAuth 2.0 Client Credentials with JWT-based assertion (Machine-to-Machine authentication).
* **No more token management**: You no longer need to create and manage access tokens in NetSuite. The connector handles authentication automatically using certificates.
* **Certificate-based security**: Instead of tokens, you now use a public/private key pair for secure authentication.

**What you need to do:**

1. **Enable new features in NetSuite**
   * Enable OAuth 2.0 Client Credentials with Certificate-Based Authentication (in addition to existing OAuth 2.0)
   * This is a new feature that may not have been enabled for v3.x users

2. **Generate certificate key pair**
   * Create a public/private key pair following NetSuite's [Certificate Generation Guide](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/subsect_162755332391.html)
   * Keep your private key secure - you'll need it for Tray.io authentication

3. **Create M2M integration in NetSuite**
   * Go to **Setup** → **Integration** → **OAuth 2.0 Client Credentials (M2M) Setup**
   * Create a new Client Credentials Mapping with your public key
   * Create an Integration record to get your Client ID, Client Secret, and Certificate ID
   * See [M2M Setup Guide](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_162686838198.html#subsect_162686947286) for detailed instructions

4. **Create new v5.0 authentication in Tray.io**
   * Navigate to the NetSuite connector authentication settings
   * Create new authentication with v5.0
   * Enter **Account ID** (same value as v3.x)
   * Enter **Client ID** and **Client Secret** from your new M2M integration
   * Enter the **Certificate ID** from your M2M integration
   * Provide your **Private Key** for JWT authentication

5. **Update existing workflows**
   * Update all workflows to use the new v5.0 of the connector with new authentication
   * Test each workflow to ensure connectivity
   * No operation changes required - inputs and outputs remain the same

> **Info:** **Note for v3.x users**: Your existing Token ID and Token Secret from NetSuite are no longer used. You can keep them for any legacy integrations, but they won't work with the v5.0 connector.

### Migration from v4.0 to v5.0

If you're upgrading from version 4.0 to 5.0, here's what has changed:

| **v4.0 Field**                  | **v5.0 Field**           | **Change**                                                        |
| ------------------------------- | ------------------------ | ----------------------------------------------------------------- |
| Company                         | Account ID               | ✅ **Renamed** - same value, clearer name                          |
| Consumer Key / Client Id        | Client ID                | ✅ **Same** - terminology updated                                  |
| Consumer Secret / Client Secret | Client Secret            | ✅ **Same** - terminology updated                                  |
| N/A                             | Certificate ID           | ✅ **New Required** - Certificate ID from NetSuite M2M integration |
| N/A                             | Certificate(Private Key) | ✅ **New Required** - Private key for JWT authentication           |

**What you need to do:**

1. **Set up M2M authentication in NetSuite**
   * Enable OAuth 2.0 Client Credentials with Certificate-Based Authentication
   * Generate public/private key pair (see [Certificate Generation Guide](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/subsect_162755332391.html))
   * Create M2M integration in NetSuite (see [M2M Setup Guide](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_162686838198.html#subsect_162686947286))

2. **Create new v5.0 authentication in Tray.io**
   * Navigate to the NetSuite connector authentication settings
   * Create new authentication with v5.0
   * Enter **Account ID** (previously called "company")
   * Enter **Client ID** and **Client Secret** from your NetSuite M2M integration
   * Enter the **Certificate ID** from your NetSuite M2M integration
   * Provide your **Private Key** for JWT authentication

3. **Update existing workflows**
   * Update all workflows to use the new v5.0 of the connector
   * Test each workflow to ensure connectivity
   * No operation changes required - inputs and outputs remain the same

### Prerequisites

To use NetSuite REST web services with version 5.0, you must enable:

* **REST Web Services** - Allow REST API access
* **OAuth 2.0** - Enable OAuth authentication
* **OAuth 2.0 Client Credentials with Certificate-Based Authentication (M2M)** - Required for v5.0
* **SuiteAnalytics** - Enable analytics features

Additionally, the integration must have the required permissions assigned. For detailed setup instructions, refer to NetSuite's [OAuth 2.0 Client Credentials with Certificate-Based Authentication guide](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_162686838198.html#subsect_162686947286).

If you already have your features and permissions set up, please move straight to **Stage 3:** [Creation](#stage-3-create).

### Stage 1: Enable Features

This accordion guides you through the process of **enabling REST Web Services, OAuth 2.0 authentication, and SuiteAnalytics** for NetSuite REST API authentication integration with Tray.io.

### 1 - Navigate to Enable Features

First sign into your Netsuite account. On the top menu bar you will see an option for **Setup**.
Click on it and in the newly displaying menu select **Company**. Another sub-menu will appear called "Setup Tasks" where you can then choose\*\* Enable Features\*\*.
![ntsw-rest-auth-pq-1](https://tray.ai/documentation/images/connectors/service/netsuite-rest/74CZstWbpzr9E2vCezSWCG_ntsw-rest-auth-pq-1.png)

### 2 - Switch to SuiteCloud

As you will **automatically land on the Company tab** please make sure that you **switch to the SuiteCloud tab** tab instead.
You will know you have switched to the correct tab as the sub-heading will change from \*\*Classifications \*\*to **SuiteBuilder**.
![ntsw-rest-auth-pq-0102](https://tray.ai/documentation/images/connectors/service/netsuite-rest/3g9nZoUwR4xtVLdy63ZvKS_Group%205.png)

### 3 - Enable REST Web Services

Under the **SuiteTalk (Web Services)** section, ensure that **REST WEB SERVICES** is checked.

> **Info:** **Required for REST Connector**: The REST WEB SERVICES feature must be enabled to use the NetSuite REST connector. This allows you to use REST-based programming interfaces to integrate external systems with NetSuite.

Make sure the checkbox next to **REST WEB SERVICES** is checked.
![netsuite-rest-web-services](https://tray.ai/documentation/images/connectors/service/netsuite-rest/netsuite-rest-webservices.png)

### 4 - Enable OAuth 2.0 and Client Credentials

Keep scrolling through the other sub headings until you see **Manage Authentication**.
**Check the option for OAuth 2.0**. Note that in order to use this feature you must accept the SuiteCloud Terms of Service.

Additionally, enable **OAuth 2.0 Client Credentials with Certificate-Based Authentication** for M2M (Machine-to-Machine) authentication required by v5.0.

> **Info:** **OAuth 2.0 Client Credentials Required**: The NetSuite REST connector v5.0 requires OAuth 2.0 Client Credentials with JWT-based assertion. This enables secure Machine-to-Machine authentication using certificates.

Once you agree, your OAuth 2.0 authentication will be enabled.
![ntsw-rest-auth-pq-2](https://tray.ai/documentation/images/connectors/service/netsuite-rest/netsuite-oauth2.jpg)

### 5 - Switch to Analytics

Scroll back up and select the **Analytics** tab from the **Enable Features menu** options. It should be located alongside the SuiteCloud tab options.
The sub-heading will change to **Dashboards**.
If it does not then you have likely scrolled too far up. The main page header also has an  Analytics tab. Please DOUBLE CHECK which Analytics tab you are using.
![ntsw-rest-auth-pq-004](https://tray.ai/documentation/images/connectors/service/netsuite-rest/2VGLyAF5xheZDavpQNZlnL_ntsw-rest-auth-pq-004.png)

### 6 - Select SuiteAnalytics

Scroll down to the **SuiteAnalytics Workbook** sub-heading and check the **SUITEANALYTICS WORKBOOK** option.
![ntsw-rest-auth-pq-5](https://tray.ai/documentation/images/connectors/service/netsuite-rest/1Ag2j5oqZvLI08tY3NsKVF_ntsw-rest-auth-pq-5.png)

### 7 - Save your changes

Scroll back to the top and under **Enable Features** click the button **Save**.
![ntsw-rest-auth-pq-3](https://tray.ai/documentation/images/connectors/service/netsuite-rest/2cmDd2CGrao5SxvAfQFKc4_ntsw-rest-auth-pq-3.png)

### Stage 2: Enable Permissions

This accordion guides you through the process of\*\* setting the permissions required\*\* for the respective features enabled in the previous section.

### 1 - Choose (or create) your role

In the main menu bar at the top of the UI select the **Setup** tab. Click on it and in the newly displaying menu select **Users/Roles**.
Another sub-menu will appear called "User Management" where you can then choose\*\* Manage Roles\*\*.
Either create a **New** role or \*\*Search \*\*and edit an existing one that you wish to enable permissions for.

> **Info:** **PLEASE NOTE**: Note that if you create a new role the setup will be entirely dependant on your use case so we cannot advise you on the process here.

![ntsw-rest-auth-pq-6](https://tray.ai/documentation/images/connectors/service/netsuite-rest/6YlAEq8vjuYexWc9matFqw_ntsw-rest-auth-pq-6.png)

### 2 - Permissions bar

On the main Role page click the \*\*Edit \*\*button.
Make sure that you have \*\*ACCESSIBLE SUBSIDIARIES: All checked \*\*(found within the section heading "Subsidiary Restrictions").
Then scroll to the bottom and select the **Permissions** tab.
![ntsw-rest-auth-pq-7](https://tray.ai/documentation/images/connectors/service/netsuite-rest/4D6zVBFIhNWsS6W0e3ulg6_ntsw-rest-auth-pq-7.png)

### 3 - Add your Permissions

Within the **Permissions** tab select the drop down **Setup**.
Add permissions. **You will need the following as a base line minimum**:

* Log in using OAuth 2.0 Access Tokens: FULL
* **REST** Web Services: FULL

> **Info:** **v5.0 Permission Requirements**: For OAuth 2.0 Client Credentials with JWT, ensure you have:* "Log in using OAuth 2.0 Access Tokens" permission enabled (FULL access)
> * Permissions for certificate-based authentication
> * Any additional permissions required for the specific operations you'll use (Lists, Transactions, etc.)

Then it is a case of adding any other permissions that you will need for your own personal use case.
![ntsw-rest-auth-pq-8](https://tray.ai/documentation/images/connectors/service/netsuite-rest/user-permissions.jpg)

### Stage 3: Create

This section begins and ends in the Tray.io builder so **please have your workflow space set up before continuing**.

### 1 - Choose the correct NetSuite connector

You **must** \*\*make sure you are using Netsuite REST connector \*\*before proceeding.
![ns-rest-v](https://tray.ai/documentation/images/connectors/service/netsuite-rest/1nBbyqxIYdtAsTe8yTwnUe_ntsw-rest-auth-create-choice.png)

### 2 - Setup authentication credentials

Select the **Auth tab** and click the **New authentication** button.
Name your authentication in a way that will quickly identify it within a potentially large list.
In this case it would be **good to specify that this authentication is for v5.0 REST NetSuite with M2M** only.

> **Info:** **Version 5.0 M2M Authentication**: Version 5.0 uses OAuth 2.0 Client Credentials with JWT-based assertion. You must provide the Certificate ID from your NetSuite M2M integration and the corresponding Private Key for secure Machine-to-Machine authentication.

The authentication form requires the following fields:

* **Account ID** (required) - Previously called "company" in v4.0
* **Client ID** (required) - From your NetSuite M2M integration
* **Client Secret** (required) - From your NetSuite M2M integration
* **Certificate ID** (required) - Certificate ID from your NetSuite M2M integration
* **Private Key** (required) - Private key for JWT authentication

> **Warning:** **Important for v4.0 users**:* The "company" field has been renamed to "Account ID"
> * You must generate a certificate and provide both the Certificate ID and Private Key
> * You need to create a new M2M integration in NetSuite (see [M2M Setup Guide](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_162686838198.html#subsect_162686947286))
> * Existing v4.0 authentications will not work with v5.0

![ntsw-rest-auth-cre-1](https://tray.ai/documentation/images/connectors/service/netsuite-rest/netsuite-rest-auth.png)

### 3 - Get Account ID

### 1 - Head to Company Information

Within NetSuite head to the **Setup** tab. Click on **Company** and in the 'Setup Tasks' category click on **Company Information**.
![nswt-rest-auth-cre-2](https://tray.ai/documentation/images/connectors/service/netsuite-rest/3BJm5sdRpP2utOVwDtDBAx_nswt-rest-auth-cre-2.png)

### 2 - Locate Account ID

This will take you to the **Company Information** page.
At the bottom of the right hand column you will find your **Account ID**.
This is the value you'll use for the **Account ID** field in your Tray.io authentication.
![nswt-rest-acc-id](https://tray.ai/documentation/images/connectors/service/netsuite-rest/1zEGcgKfnOlVYumThUmqIO_nswt-rest-acc-id.png)

### 4 - Generate Certificate for JWT Authentication

Before creating your M2M integration, you must generate a public/private key pair (certificate) for JWT authentication.

Follow NetSuite's [Certificate Generation Guide](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/subsect_162755332391.html) to create your certificate. You will need:

* **Private Key**: Keep this secure - you'll upload it to Tray.io
* **Public Key**: Upload this to your NetSuite M2M integration

The certificate should be RSA 2048-bit or higher for security.

> **Info:** **Certificate Security**: Never share your private key. Store it securely and only upload it to authorized systems like Tray.io.

### 5 - Create M2M Integration and Get Client Credentials

### 1 - Navigate to OAuth 2.0 Client Credentials Setup

To get your **Client ID** and **Client Secret**, you need to create an **M2M Integration record** configured for OAuth 2.0 Client Credentials with JWT.

Go to **Setup** → **Integration** → **OAuth 2.0 Client Credentials (M2M) Setup**.

> **Info:** **M2M Configuration**: For v5.0, you must use OAuth 2.0 Client Credentials with Certificate-Based Authentication. Refer to NetSuite's [M2M Setup Guide](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_162686838198.html#subsect_162686947286) for detailed instructions.

![netsuite-m2m-setup-menu](https://tray.ai/documentation/images/connectors/service/netsuite-rest/netsuite-m2m-setup-menu.png)

### 2 - Create Integration Record

After creating the Client Credentials Mapping, you need to create an Integration record to get your Client ID and Client Secret.

Go to **Setup** → **Integration** → **Manage Integrations** → **New**.

Fill in the required information:

* **Name**: Give your integration a descriptive name (e.g., "Tray.io M2M Integration")
* **State**: Select **Enabled**
* **Authentication Type**: Select **OAuth 2.0** with **Client Credentials**
* Under **Allowed Scopes**, ensure **REST Web Services** is selected

Click **Save** and you will be redirected to a page where you will find your **Client ID**, **Client Secret**, and **Certificate ID**.

> **Warning:** **IMPORTANT!**:- The **Client Secret** will only be shown once. Save it securely for your Tray.io authentication.
> - Note the **Certificate ID** displayed - you'll need this for authentication in Tray.io

![netsuite-auth-step-5](https://tray.ai/documentation/images/connectors/service/netsuite-rest/netsuite-integration-permissions.png)

### 3 - Create Client Credentials Mapping

Click **New** to create a new Client Credentials Mapping. You'll need to configure:

* **Entity**: Select the entity/company for this integration
* **Role**: Select the role with appropriate permissions (configured in Stage 2)
* **Application**: Select the integration application (if applicable)
* **Certificate**: Upload the **public key** you generated in step 4

After uploading the certificate, click **Save**. NetSuite will generate a **Certificate ID** that you'll use in your Tray.io authentication.

![netsuite-client-credentials-mapping](https://tray.ai/documentation/images/connectors/service/netsuite-rest/netsuite-client-credentials-mapping.png)

### 6 - Complete your Tray.io Authentication

Once you have obtained all required credentials, add them to your Tray.io NetSuite authentication form:

* **Account ID**: Your NetSuite Account ID (from step 3) - Note: This was previously called "company" in v4.0
* **Client ID**: From your M2M integration (from step 5)
* **Client Secret**: From your M2M integration (from step 5)
* **Certificate ID**: From your M2M integration (from step 5)
* **Private Key**: Upload or paste your **private key** (generated in step 4)

Click the **Create authentication** button.
Your connector authentication setup should now be complete.

> **Info:** **Testing**: Run a simple operation (such as Get Governance Limits) to verify your authentication works correctly. This validates that your certificate and M2M integration are properly configured.

## Available Operations

> **Info:** **New in v5.0**: Three new operations have been added to enhance NetSuite integration capabilities:- **Get Currency Rate** - Retrieve currency exchange rates for multi-currency transactions
> - **Get Governance Limits** - Monitor API usage and concurrency limits to prevent rate limiting
> - **Get Item Availability** - Access real-time inventory availability informationSee detailed documentation for these operations below.

The examples below show one or two of the available connector operations in use.
Please see the [Full Operations Reference](#operationsFull) at the end of this page for details on all available operations for this connector.

## New Operations in v5.0

### Get Currency Rate

Retrieve currency exchange rate information for multi-currency transactions and financial reporting.

### Operation Details

**Method**: GET

**Endpoint**: `/services/rest/record/v1/currencyrate/{currency_rate_id}`

**Input Parameters**:

* `currency_rate_id` (required) - The ID of the currency rate record to retrieve

**Use Cases**:

1. **Multi-currency transaction processing** - Get exchange rates when processing transactions across different currencies
2. **Financial reporting with currency conversions** - Retrieve accurate exchange rates for financial reports and statements
3. **Real-time exchange rate monitoring** - Track currency fluctuations for pricing and forecasting

> **Info:** **Best Practice**: Cache currency rate data to reduce API calls, as exchange rates typically don't change within the same business day in NetSuite.

### Example Response

The operation returns a currency rate record with details including:

* Base currency and transaction currency codes
* Exchange rate value
* Effective date of the rate
* Rate type (e.g., current, historical, average)

Use this data to accurately convert amounts between currencies in your integrations.

### Get Governance Limits

Monitor API usage and concurrency limits to prevent rate limiting and optimize integration performance.

### Operation Details

**Method**: GET

**Endpoint**: `/services/rest/system/v1/governanceLimits`

**Input Parameters**: None required

**Use Cases**:

1. **Monitor API usage before rate limiting** - Check remaining API calls to avoid hitting governance limits
2. **Implement adaptive retry logic** - Adjust request frequency based on available concurrency
3. **Track integration performance metrics** - Monitor API consumption patterns for optimization

> **Info:** **Pro Tip**: Call this operation periodically during bulk data operations to ensure you don't exceed NetSuite's governance limits. This can help prevent workflow failures during high-volume data processing.

### What Gets Returned

The operation provides real-time information about:

* Remaining API calls in the current time window
* Maximum concurrent requests allowed
* Current concurrency usage
* Time until limit reset

Use this data to implement intelligent throttling and prevent 429 (Too Many Requests) errors.

### Implementation Example

A common pattern is to check governance limits before starting batch operations:

1. Call **Get Governance Limits** to check available capacity
2. Calculate optimal batch size based on remaining calls
3. Process batches with appropriate delays
4. Re-check limits periodically during long-running operations

This approach ensures reliable data processing without hitting rate limits.

### Get Item Availability

Access real-time inventory availability information for items in your NetSuite account.

### Operation Details

**Method**: GET

**Endpoint**: `/services/rest/record/v1/inventoryItem/{item_id}`

**Input Parameters**:

* `item_id` (required) - The ID of the inventory item to check availability for

**Use Cases**:

1. **Real-time inventory checks for orders** - Verify stock availability before confirming customer orders
2. **Stock level monitoring and alerts** - Track inventory levels and trigger reorder notifications
3. **E-commerce platform integration** - Sync inventory availability to online stores in real-time

> **Info:** **Integration Note**: This operation is particularly useful for e-commerce integrations where real-time stock visibility prevents overselling and improves customer experience.

### Response Data

The operation returns comprehensive inventory data including:

* Available quantity across all locations
* Location-specific inventory levels
* Reserved quantities
* On-order quantities
* Reorder point and preferred stock level

Use this data to make informed decisions about order fulfillment and inventory management.

### Best Practices

When working with inventory availability:

* **Cache strategically** - Balance freshness with API usage by caching availability data for short periods (e.g., 5-15 minutes)
* **Handle multi-location inventory** - Account for different availability across warehouses and locations
* **Consider reserved quantities** - Subtract reserved/committed inventory from available quantities for accurate stock counts
* **Implement fallback logic** - Have a plan for when availability cannot be determined (e.g., show "Contact us for availability")

## Notes on key operations

### Find record

### Find record

Please bear in mind that the **Find record** operation will **give you links to all the records** BUT **does not provide raw data**.
You will need to make a subsequent API call in order to get the record data actual, ie: **Get Record.**

### Find record

![nswt-rest-find-2](https://tray.ai/documentation/images/connectors/service/netsuite-rest/6H18o0jFsKsm3jV5bKUmdB_nswt-rest-find-2.png)
![nswt-rest-find-1](https://tray.ai/documentation/images/connectors/service/netsuite-rest/7apomEhmBi8oksgdaMb3eO_nswt-rest-find-1.png)

### Get record

![nswt-rest-find-4](https://tray.ai/documentation/images/connectors/service/netsuite-rest/16IDDnHdT9xqmOCtyAGSIR_nswt-rest-find-4.png)
![nswt-rest-find-3](https://tray.ai/documentation/images/connectors/service/netsuite-rest/5eYxonIbqIwlxm31rWVrEM_nswt-rest-find-3.png)

### Find record (& retrieve data)

In some cases you may need to be more efficient when retrieving your record data.
You can reduce the number of calls into a single step by making a **Raw HTTP Request** to the following API endpoint: `query.runSuiteQLPaged(options)`.
Note that the output will come back in a flat JSON format - which makes polling NetSuite more economical.
For more details check out the following [NetSuite Applications Suite](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_157960586441.html) link.

### Find record (with filtering)

This operation requires that **users align the fields data type with the correct comparator**.
For example `Strings` require `CONTAINS`, `IS`, etc but they will not work with `EQUAL TO`.
Before filtering you should check:

* What field 'types' you need to use.
  * An overview on how to use the [NetSuite REST API Browser](https://system.netsuite.com/help/helpcenter/en_US/APIs/REST_API_Browser/record/v1/2020.2/index.html#tag-account) can be found [here](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_157373386674.html).
* What filters work with said field 'types'.
  * Use the [Record collection filtering](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_1545222128.html) page to learn about the allowed filters.

### Create Record

> **Warning:** **IMPORTANT!**: It is **imperative to pay attention to the field requirements in the schema browser** when using this operation.
> A summary of what and why is below. See the [Creating a record instance](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_1545141395.html) API page for more details.

You **must be very precise** **when using this operation**. It is critical that you keep in mind the following points:

* All field references are correctly 'typed' - object / string / boolean, etc
* There are no missing fields
* Any field requirements match the schema

### 500

#### 500 status code

Incorrectly 'typing' your field references will most likely result in a `500 status code` error.
Therefore \*\*you have to be mindful of what 'type' of field is being referred to \*\*during setup.
For example; a sub-list of records would most likely be returned as an array of objects. An associated record would be an object with keys such as 'id' and 'name' etc.
Make sure to keep your 'types' in mind while using this operation.

### 400

#### 400 status code

If there are any required fields that are missing or minute schema errors users will most likely receive a `400` `status code` error.
This error will helpfully list the required missing fields and where the schema fault lies.
While this style of configuration is something users should expect it can be somewhat confusing as t**his will occur even if the field level error is minute**. Please triple check your setup before continuing.

### Execute SuiteQL (advanced query)

You execute SuiteQL queries by sending a `POST` request to the `suiteql resource` and specifying the query in the `request body` after the body parameter "`q`".
Check out the following links for more information:

* [Executing SuiteQL Queries](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_157909186990.html)
* [NetSuites SuiteQL Syntax and Examples](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_156257790831.html)

### Example

This string queries for the following field values in all customer records:

* `entityid`
* `firstname` 
* `lastname`
  By default, field values use the `RAW` field context.
  For more information, see [query.FieldContext](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_1552071599.html).

```sql
SELECT customer.entityid AS entityidRAW, customer.firstname AS firstnameRAW, customer.lastname AS lastnameRAW FROM customer
```

![ntst-rest-suiteql-raw](https://tray.ai/documentation/images/connectors/service/netsuite-rest/4voOebz5yNyzaCKJrLvZHG_ntst-rest-suiteql-raw.png)

### NetSuite Sales orders

There are 3 main points to be aware of when creating a NetSuite Sales order:

* Your associated NetSuite Role has the correct permissions.
  * "**NetSuite Role**" -> **Permissions** -> **Transactions**: Please make sure the following 3 permission sets are added and have `Level: Full` for each as a general rule.
  * Sales order
  * Sales order approval
  * Find Transaction
  * "**NetSuite Role**" -> **Permissions** -> **Lists**: Please make sure the following permission set is added and has `Level: Full` as a general rule.
  * Items
* It is possible to 'use' your item within a sales order.
  * For example you may be able to create a purchase order for an item but not be able to sell it. You may get unusual error messages as a result.
* The data being sent to NetSuite is being sent in the format it requires.
  * Please see the accordion step below for a clear demonstration.

### Sales orders

**How you decide to pull your data in will depend on the service you are pulling your data from**.
Please see the following link for more information on [NetSuite Sales Orders](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_159665260887.html).

```html
\{
  "key": "item",
  "value": \{
    "items": [
      \{
        "amount": 15000,
        "item": \{
          "id": "10"
        \},
        "billingschedule": \{
          "id": "1"
        \}
      \},
      \{
        "amount": 0,
        "item": \{
          "id": "13"
        \},
        "billingschedule": \{
          "id": "1"
        \}
      \}
    ]
  \}
\}
```

### Renaming fields

Any fields customers may have renamed within their NetSuite instance **will still display as their native name** **within any of the dropdown options available inside the Tray.io properties panel**.
The NetSuite UI may display your updated field name but what it is referring to in the NetSuite database will not have.
Look for your endpoint in the [REST API Browser](https://system.netsuite.com/help/helpcenter/en_US/APIs/REST_API_Browser/record/v1/2023.1/index.html#/definitions/) and under the **I\*\*\*\*nsert record** -> **Request body** select the clickable 'endpoint' link to see a list of **Fields**. This will display the native name for all the field references.

## Using the Raw HTTP Request ('Universal Operation')

As of **version 2.0** you can effectively create your own operations.
This is a very powerful feature which you can use if you need an endpoint that is not currently provided.

### URL reference

Note that your URL reference may vary if you are using a domain specific account.
The base format displayed below is standard when you select URL -> Endpoint from within the Raw HTTP Request operation's property panel.

***

**Base URL (**URL: Endpoint**)**: `https://[accountid].suitetalk.api.netsuite.com`
[Account-Specific URLs](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_1546938065.html): `https://[account_id].[domain_name].netsuite.com`

### Pathway parameters

You will need to include the following pathway parameters before your chosen endpoint.
These are based on the [Metadata pathway parameters.](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_1540810174.html)

***

**Path params**: `/services/rest/record/v1`

### Find your Endpoint

You will need to research your endpoint and the format it requires. The main Documentation overview can be found here: [REST Web Services Overview](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/chapter_1540391670.html).
To view all potential Metadata endpoints, you have two options:

### Make an API call to return the full list

Use the following endpoint in your original API request call and search through the returned payload for the endpoint you require:

***

**Path params**: `/services/rest/record/v1/metadata-catalog`

### Reference the available Endpoints catalog

If you intend to reference the following list of potential endpoints from the list below, note the warning before proceeding

> **Warning:** **IMPORTANT!**: While the above Endpoints link has a good list of examples you could potentially use, **please do not use the path parameters shown at the top of the **[](https://system.netsuite.com/help/helpcenter/en_US/APIs/REST_API_Browser/record/v1/2019.2/index.html)** page** - it will not work with your setup.
> **GOOD**: [](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_1540810174.html): `/services/rest/record/v1`
> **BAD**: [](https://system.netsuite.com/help/helpcenter/en_US/APIs/REST_API_Browser/record/v1/2019.2/index.html): `/rest/platform/v1/record`

***

**List of Endpoints**: [](https://system.netsuite.com/help/helpcenter/en_US/APIs/REST_API_Browser/record/v1/2019.2/index.html)\*\*\*\*

Please the example below for a full walkthrough.

### 1 - Example operation 'Find records: Customer'

Let's pretend that the **Find records** operation does not exist within our NetSuite REST connector's list of available operations and we wish to get a list of all available customers.
![nswt-rest-raw-step-1](https://tray.ai/documentation/images/connectors/service/netsuite-rest/1TNEGR0NuCbRDb8oM3Myf9_nswt-rest-raw-step-1.png)

### 2 - Navigate to the correct documentation page

Navigate to the NetSuite REST API documentation to find the endpoint and the parameters required to use it.
In this case the 'Find records' endpoint is a `GET` request called: `/customer` (as this is the record type we are searching for).
More details can be found [here](https://system.netsuite.com/help/helpcenter/en_US/APIs/REST_API_Browser/record/v1/2019.2/index.html).
![netsuite-get-url](https://tray.ai/documentation/images/connectors/service/netsuite-rest/921adf8c-6ac6c1bd_nswt-rest-raw-step-2.png)

### 3 - Add your endpoint to the Tray properties panel

Select the **Raw HTTP Request** operation from the dropdown options in the NetSuite REST property panel.
Having read through the API documentation page you now know what your method, endpoint and the details of your query parameters (should you wish to include one) are.
You can now test your operation with the following setup:
**Method**: `GET`
**Endpoint**: `/services/rest/record/v1/customer`
**Body type**: `none`
**End result**: `https://[[account_id]].netsuite.com/services/rest/record/v1/customer`
![netsuite-raw-http](https://tray.ai/documentation/images/connectors/service/netsuite-rest/921adf8c-c011041a_nswt-rest-raw-step-3.png)

## NetSuite REST templates

Please note that we have the following NetSuite REST templates available.
These will give you pre-configured best practice ways of working with NetSuite REST and integrating it with other connectors.

> **Info:** **PLEASE NOTE**: To help **avoid the most common user errors** we **strongly advise** you **read through** the **Authentication**, **Important notes** sections, etc, before applying any templates. Every service is unique and each has its own nuances you need to be aware of before proceeding.

## Further Info (REST & SOAP)

The following sections are mainly relevant to SOAP users however there is some cross over for our REST customers.
Please see the [NetSuite SOAP: Further Info](https://tray.ai/documentation/connectors/service/netsuite-soap/#further-info-rest--soap) section for references pertaining to:

* [Reverting XML schema](https://tray.ai/documentation/connectors/service/netsuite-soap/#reverting-xml-schema)
* [SuitTalk Guides](https://tray.ai/documentation/connectors/service/netsuite-soap/#suittalk-guides)
* [Appendix I: Namespace to Alias Mappings](https://tray.ai/documentation/connectors/service/netsuite-soap/#appendix-i-namespace-to-alias-mappings)
* [Appendix II: Further Documentation](https://tray.ai/documentation/connectors/service/netsuite-soap/#appendix-ii-further-documentation)