> For the complete documentation index, see [llms.txt](https://docs.mydbsync.com/cloud-workflow/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mydbsync.com/cloud-workflow/connectors/netsuite-rest/third-party-integration-setup.md).

# 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.

{% stepper %}
{% step %}
Go to **Setup > Company > Enable Features**.

<div align="left" data-with-frame="true"><figure><img src="/files/O1utPjAkoD1B8OWfxjCF" alt="" width="333"><figcaption></figcaption></figure></div>

1. 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)

   <div data-with-frame="true"><figure><img src="/files/YmX3PUZVtfqcxQjgCeod" alt=""><figcaption></figcaption></figure></div>
2. Click **Save**.
   {% endstep %}

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

<div align="left" data-with-frame="true"><figure><img src="/files/9yoJ6gNAVUSSGeXLB49d" alt="" width="330"><figcaption></figcaption></figure></div>

1. 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.<br>

      <div data-with-frame="true"><figure><img src="/files/OtH2CrFhGAh9m3cPIfHj" alt=""><figcaption></figcaption></figure></div>
2. Click **Save**.
   {% endstep %}

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

<div data-with-frame="true"><figure><img src="/files/7qSzozob3lhuWvIjmHQD" alt=""><figcaption></figcaption></figure></div>

1. Click **Edit**.
2. Under **Permissions** > **Transactions**, set the following permissions to **Full**.<br>

   <div data-with-frame="true"><figure><img src="/files/TEU7kAMg4ZQJVkHv4sVc" alt=""><figcaption></figcaption></figure></div>
3. Under **Permissions** > **Reports**, set the following permissions as shown in the image.<br>

   <div data-with-frame="true"><figure><img src="/files/ENSULpU8cuHapB6ffQek" alt=""><figcaption></figcaption></figure></div>
4. Under **Permissions** > **Lists**, set the following permissions as shown in the table.<br>

   <table data-header-hidden data-search="false"><thead><tr><th>Permission</th><th>Level</th></tr></thead><tbody><tr><td>Accounts</td><td>Full</td></tr><tr><td>Address List in Search</td><td>Full</td></tr><tr><td>Bins</td><td>Full</td></tr><tr><td>Classes</td><td>Full</td></tr><tr><td>Companies</td><td>Full</td></tr><tr><td>Contacts</td><td>Full</td></tr><tr><td>Customers</td><td>Full</td></tr><tr><td>Departments</td><td>Full</td></tr><tr><td>Documents and Files</td><td>Full</td></tr><tr><td>Email Template</td><td>Full</td></tr><tr><td>Employee Record</td><td>Full</td></tr><tr><td>Employee Social Security Numbers</td><td>Full</td></tr><tr><td>Employees</td><td>Full</td></tr><tr><td>Events</td><td>Full</td></tr><tr><td>Export Lists (Create)</td><td>Full</td></tr><tr><td>Generic Resources</td><td>Full</td></tr><tr><td>Gift Certificate</td><td>Full</td></tr><tr><td>Integration Applications</td><td>Full</td></tr><tr><td>Internal Publisher</td><td>Full</td></tr><tr><td>Item Collection</td><td>Full</td></tr><tr><td>Items</td><td>Full</td></tr><tr><td>Key Access</td><td>Full</td></tr><tr><td>Locations</td><td>Full</td></tr><tr><td>Media Folders</td><td>Full</td></tr><tr><td>Notes Tab</td><td>Full</td></tr><tr><td>Perform Search</td><td>Full</td></tr><tr><td>Publish Search</td><td>Full</td></tr><tr><td>Record Custom Field</td><td>Full</td></tr><tr><td>Resource</td><td>Full</td></tr><tr><td>Store Content Items</td><td>Full</td></tr><tr><td>Store Tabs</td><td>Full</td></tr><tr><td>Subsidiaries</td><td>Full</td></tr><tr><td>Tasks</td><td>Full</td></tr><tr><td>Track Messages</td><td>Full</td></tr><tr><td>Vendors</td><td>Full</td></tr><tr><td>Contact-Subsidiary Relationship</td><td>View</td></tr><tr><td>Entity-Subsidiary Relationship</td><td>View</td></tr><tr><td>Financial History</td><td>View</td></tr><tr><td>Sent Email</td><td>View</td></tr><tr><td>Undelivered Emails</td><td>View</td></tr><tr><td>Bulk Processing Submissions</td><td>View</td></tr></tbody></table>
5. Under **Permissions** > **Setup**, set the following permissions as shown in the table.<br>

   <table data-header-hidden data-search="false"><thead><tr><th>Permission</th><th>Level</th></tr></thead><tbody><tr><td>Access Token Management</td><td>Full</td></tr><tr><td>Accounting Lists</td><td>Full</td></tr><tr><td>Allow JS / HTML Uploads</td><td>Full</td></tr><tr><td>Backup Your Data</td><td>Full</td></tr><tr><td>CRM Lists</td><td>Full</td></tr><tr><td>Company Information</td><td>Full</td></tr><tr><td>Control SuiteScript and Workflow Triggers in Web Services Request</td><td>Full</td></tr><tr><td>Control SuiteScript and Workflow Triggers per CSV Import</td><td>Full</td></tr><tr><td>Custom Body Fields</td><td>Full</td></tr><tr><td>Custom Column Fields</td><td>Full</td></tr><tr><td>Custom Entity Fields</td><td>Full</td></tr><tr><td>Custom Fields</td><td>Full</td></tr><tr><td>Custom Item Fields</td><td>Full</td></tr><tr><td>Custom Item Number Fields</td><td>Full</td></tr><tr><td>Custom Lists</td><td>Full</td></tr><tr><td>Custom PDF Layouts</td><td>Full</td></tr><tr><td>Custom Sublist</td><td>Full</td></tr><tr><td>Custom Subtabs</td><td>Full</td></tr><tr><td>Custom Transaction Fields</td><td>Full</td></tr><tr><td>Enable Features</td><td>Full</td></tr><tr><td>Export as IIF</td><td>Full</td></tr><tr><td>Integration Application</td><td>Full</td></tr><tr><td>Key Management</td><td>Full</td></tr><tr><td>Log in using Access Tokens</td><td>Full</td></tr><tr><td>Log in using OAuth 2.0 Access Tokens</td><td>Full</td></tr><tr><td>Manage Custom Permissions</td><td>Full</td></tr><tr><td>Manage Users</td><td>Full</td></tr><tr><td>OAuth 2.0 Authorized Applications Management</td><td>Full</td></tr><tr><td>Online Custom Record Form</td><td>Full</td></tr><tr><td>Other Custom Fields</td><td>Full</td></tr><tr><td>Other Lists</td><td>Full</td></tr><tr><td>Publish Dashboards</td><td>Full</td></tr><tr><td>Publish Employee List</td><td>Full</td></tr><tr><td>REST Web Services</td><td>Full</td></tr><tr><td>SOAP Web Services</td><td>Full</td></tr><tr><td>SuiteScript</td><td>Full</td></tr><tr><td>User Access Tokens</td><td>Full</td></tr><tr><td>View SOAP Web Services Logs</td><td>Full</td></tr><tr><td>Secrets Management</td><td>Full</td></tr><tr><td>Records Catalog</td><td>View</td></tr></tbody></table>
6. Click **Save**.
   {% endstep %}

{% step %}
Go to **Lists > Employees > Employees > New**.

<div data-with-frame="true"><figure><img src="/files/Q8wppBVUvFcqPnwUv1Pb" alt=""><figcaption></figcaption></figure></div>

1. In the **CUSTOM FORM** menu, select **Ramsey Employee Form**.
2. Enter the user details, such as `API Integration`.
3. For **Role**, select the integration role that you created, such as `NetSuite API Integration Role`.
4. If you use NetSuite OneWorld, complete the following fields before you save the employee record:

   <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>These values depend on your NetSuite account configuration. Select them from the available menus. Do not create new values or hardcode them.</p></div>

   | **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.        |
5. Click **Save**.
   {% endstep %}

{% step %}
Go to **Setup > Integration > Manage Integrations > New**.

<div align="left" data-with-frame="true"><figure><img src="/files/Tp60EBLeiQiAKL61pIXh" alt="" width="301"><figcaption></figcaption></figure></div>

1. Enter a name for your application, such as `My Integration`.
2. Select **Token Based Authentication**.
3. Click **Save**.

   <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>If you use only <strong>Token-Based Authentication</strong> (TBA) (OAuth 1.0), enable <strong>Token-Based Authentication</strong>. OAuth 2.0 is optional and isn't required to generate a Consumer Key and Secret, or a Token ID and Secret.</p><p>If you enable <strong>OAuth 2.0</strong>, you must provide at least one valid <strong>Redirect UR</strong>I before you save the Integration record.</p></div>

   <div data-with-frame="true"><figure><img src="/files/Ktm8grEUyE1GKFaaXxoP" alt=""><figcaption></figcaption></figure></div>

{% hint style="success" %}
NetSuite generates a **Consumer Key** and a **Consumer Secret**, which you must store securely because NetSuite displays the secret only once.
{% endhint %}
{% endstep %}

{% step %}
Go to **Setup > Users/Roles > Access Tokens > New**.

<div align="left" data-with-frame="true"><figure><img src="/files/VIwNwx4BrUEH73rkWOo0" alt="" width="271"><figcaption></figcaption></figure></div>

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

{% hint style="warning" %}
NetSuite generates a **Token ID** and a **Token Secret**, which you must store securely because NetSuite displays the secret only once.
{% endhint %}
{% endstep %}

{% step %}
Go to **Setup > Integration > SOAP Web Services Preferences**

<div align="left" data-with-frame="true"><figure><img src="/files/ayipllGuq3IGLBKQykpk" alt="" width="305"><figcaption></figcaption></figure></div>

Locate the **ACCOUNT ID** field and copy the value, for example, `123579`.
{% endstep %}

{% step %}
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**.
{% endstep %}
{% endstepper %}

## 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:

```http
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:

```http
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.