Third-party integration setup

This page explains how to configure NetSuite for third-party integrations using SOAP web services, REST web services, and token-based authentication (TBA).

After completing this setup, you will have:

An integration role
An integration user
An integration application (client ID and client secret)
An access token and token secret
An account ID
The required credentials to connect any external application

Prerequisites

NetSuite account ID
Administrator login
Access to setup menu

Configure NetSuite for third-party integrations

To configure your NetSuite environment for integration, you must first enable the necessary SuiteCloud features.

Go to Setup > Company > Enable Features.

Under SuiteCloud, enable the following features:
1. SOAP Web Services
2. REST Web Services
3. Token-Based Authentication (TBA)
4. OAuth 2.0 (if your account supports OAuth 2.0)
Click Save.

Go to Setup > Users/Roles > Manage Roles > New. For Role Name, enter a name for the role, such as NetSuite API Integration Role.

Configure the following recommended settings:
1. Subsidiary Access: All
2. Two Factor Authentication: Not Required
3. Web Services Only Role: No
4. Allow Cross Subsidiary Record Viewing: Enabled if required by your use case.
Click Save.

After creating the role, search for the created role and assign the following permissions required for SOAP and REST APIs.

Click Edit.
Under Permissions > Transactions, set the following permissions to Full.
Under Permissions > Reports, set the following permissions as shown in the image.
Under Permissions > Lists, set the following permissions as shown in the table.
Accounts
Full
Address List in Search
Full
Bins
Full
Classes
Full
Companies
Full
Contacts
Full
Customers
Full
Departments
Full
Documents and Files
Full
Email Template
Full
Employee Record
Full
Employee Social Security Numbers
Full
Employees
Full
Events
Full
Export Lists (Create)
Full
Generic Resources
Full
Gift Certificate
Full
Integration Applications
Full
Internal Publisher
Full
Item Collection
Full
Items
Full
Key Access
Full
Locations
Full
Media Folders
Full
Notes Tab
Full
Perform Search
Full
Publish Search
Full
Record Custom Field
Full
Resource
Full
Store Content Items
Full
Store Tabs
Full
Subsidiaries
Full
Tasks
Full
Track Messages
Full
Vendors
Full
Contact-Subsidiary Relationship
View
Entity-Subsidiary Relationship
View
Financial History
View
Sent Email
View
Undelivered Emails
View
Bulk Processing Submissions
View
Under Permissions > Setup, set the following permissions as shown in the table.
Access Token Management
Full
Accounting Lists
Full
Allow JS / HTML Uploads
Full
Backup Your Data
Full
CRM Lists
Full
Company Information
Full
Control SuiteScript and Workflow Triggers in Web Services Request
Full
Control SuiteScript and Workflow Triggers per CSV Import
Full
Custom Body Fields
Full
Custom Column Fields
Full
Custom Entity Fields
Full
Custom Fields
Full
Custom Item Fields
Full
Custom Item Number Fields
Full
Custom Lists
Full
Custom PDF Layouts
Full
Custom Sublist
Full
Custom Subtabs
Full
Custom Transaction Fields
Full
Enable Features
Full
Export as IIF
Full
Integration Application
Full
Key Management
Full
Log in using Access Tokens
Full
Log in using OAuth 2.0 Access Tokens
Full
Manage Custom Permissions
Full
Manage Users
Full
OAuth 2.0 Authorized Applications Management
Full
Online Custom Record Form
Full
Other Custom Fields
Full
Other Lists
Full
Publish Dashboards
Full
Publish Employee List
Full
REST Web Services
Full
SOAP Web Services
Full
SuiteScript
Full
User Access Tokens
Full
View SOAP Web Services Logs
Full
Secrets Management
Full
Records Catalog
View
Click Save.

Go to Lists > Employees > Employees > New.

In the CUSTOM FORM menu, select Ramsey Employee Form.
Enter the user details, such as API Integration.
For Role, select the integration role that you created, such as NetSuite API Integration Role.
If you use NetSuite OneWorld, complete the following fields before you save the employee record:
These values depend on your NetSuite account configuration. Select them from the available menus. Do not create new values or hardcode them.
Field
Value
Subsidiary
Select an active subsidiary. For example, select the primary subsidiary or the subsidiary where the integration operates.
Default Currency
Select the base or default currency associated with the selected subsidiary. For example, select INR, USD, or GBP.
Click Save.

Go to Setup > Integration > Manage Integrations > New.

Enter a name for your application, such as My Integration.
Select Token Based Authentication.
Click Save.
If you use only Token-Based Authentication (TBA) (OAuth 1.0), enable Token-Based Authentication. OAuth 2.0 is optional and isn't required to generate a Consumer Key and Secret, or a Token ID and Secret.
If you enable OAuth 2.0, you must provide at least one valid Redirect URI before you save the Integration record.

NetSuite generates a Consumer Key and a Consumer Secret, which you must store securely because NetSuite displays the secret only once.

Go to Setup > Users/Roles > Access Tokens > New.

Select the Application, User, and Role that you created in the preceding steps.
Enter the Token Name.
Click Save.

NetSuite generates a Token ID and a Token Secret, which you must store securely because NetSuite displays the secret only once.

Go to Setup > Integration > SOAP Web Services Preferences

Locate the ACCOUNT ID field and copy the value, for example, 123579.

After you complete the setup, you have the following credentials: an account ID, a consumer key, a consumer secret, a token ID, and a token secret.

Verify Credentials and Test

After completing the setup, you use OAuth 1.0 token-based authentication (HMAC-SHA256) for both SOAP and REST endpoints.

To authenticate, include the following HTTP header in your requests:

Authorization

OAuth
realm="ACCOUNT_ID",
oauth_consumer_key="...",
oauth_token="...",
oauth_signature_method="HMAC-SHA256",
oauth_timestamp="...",
oauth_nonce="...",
oauth_version="1.0",
oauth_signature="..."

You can test your endpoints using a tool like Postman. The base URL for the REST API is:

https://ACCOUNT_ID.suitetalk.api.netsuite.com

The base URL for the SOAP endpoint is:

https://ACCOUNT_ID.suitetalk.api.netsuite.com/services/NetSuitePort_2025_1
//Replace the version according to your NetSuite account.

The expected response for a successful test is 200 OK.

Test the following endpoints:

GET /services/rest/record/v1/customer?limit=1
GET /services/rest/record/v1/employee?limit=1
GET /services/rest/record/v1/vendor?limit=1
GET /services/rest/record/v1/metadata-catalog

Troubleshoot Common Errors

If you encounter issues during testing, review the following common errors:

Error

Possible Causes

INVALID_LOGIN_ATTEMPT

Wrong consumer key, wrong consumer secret, wrong token, wrong token secret, wrong account ID, wrong signature, wrong timestamp, or wrong nonce

INSUFFICIENT_PERMISSION

Missing role permissions, REST web services permissions, SOAP web services permissions, or record permissions

INVALID_SIGNATURE

Incorrect signature base string, incorrect signature method, consumer secret mismatch, or token secret mismatch

Security Best Practices

To maintain the security of your integration, follow these best practices:

Never hardcode credentials in your source code.
Store all secrets in a secure vault or encrypted configuration.
Create a dedicated integration user; don't use an administrator account.
Rotate consumer secrets and token secrets periodically.
Grant only the minimum permissions required for your integration.
Audit API access regularly using NetSuite logs.

PreviousNetSuite REST

NextNetSuite

Last updated 1 month ago