NetSuite – Connection Guide

Connect to NetSuite

This guide will walk you through the process of setting up NetSuite User Roles to get Access Tokens using Token-Based Authentication. Access tokens are used to authenticate requests to NetSuite APIs, which enables you to integrate NetSuite with other applications.

By following these steps, you can grant specific NetSuite User Roles access to generate Access Tokens and use them to access NetSuite APIs securely.

Steps — bundle path (recommended):

1. Install the Apideck Integration bundle
2. Assign the role to a new user
3. Create access tokens — select Apideck Unify as Application and Role
4. Find your Account ID
5. Configure the connection — only 3 fields needed (Account ID, Token ID, Token Secret)

Steps — manual path (existing customers or restricted accounts):

1. Create the role manually
2. Assign the role to a new user
3. Create an application (consumer key & secret)
4. Create access tokens
5. Find your Account ID
6. Configure the connection — all 5 fields needed

Info: This guide assumes you have a basic understanding of NetSuite and its interface.

Recommended: install the Apideck Integration bundle

Apideck publishes a NetSuite SuiteBundle that ships a pre-built least-privilege Apideck Unify role with exactly the 32 permissions the connector needs, plus an Apideck Unify Integration Record pre-configured for Token-Based Authentication. Installing the bundle takes about a minute and replaces the manual role build described in the "Alternative" section below.

For the full step-by-step walkthrough with screenshots, see the dedicated Apideck Integration Connectivity Bundle Setup Guide.

Quick summary:

1. Go to Customization → SuiteBundler → Search & Install Bundles, search for bundle ID 705521 and click Install.
2. Create a dedicated integration user and assign the Apideck Unify role to them.
3. Create an Access Token — select Apideck Unify as both the Application and Role.
4. In Vault, enter only 3 fields: Account ID, Token ID, Token Secret. Leave Consumer Key and Consumer Secret blank.

The full list of 32 permissions installed by the bundle is in the Bundle Setup Guide.

The bundle is unmanaged, so once installed you can inspect the role at Setup → Users/Roles → Manage Roles and add extra permissions if your account uses features outside the standard Apideck accounting scope.

Bundle updates: When Apideck publishes a new bundle version, apply it from Customization → SuiteBundler → Installed Bundles. New permissions are added automatically. Any permissions you added manually to the role — such as bank feed permissions or Tax Details Tab for SuiteTax (UK, EU, and other VAT regions) — will be removed by the update and must be re-added manually afterwards.

Alternative: create the role manually

Use this path only if your NetSuite account policy blocks installing unmanaged bundles, or if you need permissions beyond what the bundle ships. The bundle is the recommended default — see the previous section.

To grant access to the Netsuite, you need to create a user role to get Access Tokens using Token-Based Authentication

1. User Roles to get Access Tokens using Token-Based Authentication:

2. Log in to your NetSuite account as an administrator.

3. Go to Setup > Users/Roles > Manage Roles.

4. Click on the 'New' button to create a new role. Give the role a name (e.g. Integration Role).

5. Under the 'Permissions' tab, select the appropriate permissions that you want to grant to this role. Note that the role must have the necessary permissions to perform the tasks that the integration will be used for.

   We recommend to review the permission levels for the various sections:

   For "Transactions","Lists" we recommend to set the permission to "View" to allow reading data and "Full" to allow creating and/or modifying data. For "Lists","Currencies" we recommend to set the permission to "View" to allow reading data and "Full" to allow creating and/or modifying data. For "Setup", the only option is "None" or "Full", please set it to "Full" to grant access to the Netsuite instance.

   For more details about the Netsuite permission levels, please refer to the Access Levels page in NetSuite Help Center.

   Important for Projects Functionality: To enable customer-to-project mapping and full project management features, ensure the following permissions are granted:

   • Lists > Projects: Required for accessing job/project records
   • Lists > Customers: Required for customer-project relationship mapping

   Important for Financial Reports (Profit & Loss, Balance Sheet): These reports use the SOAP getPostingTransactionSummary API which only requires "Financial Statements" permission. Ensure the following permission is granted:

   • Reports > Financial Statements: View access required for financial report queries
   • Lists > Accounts: View access for chart of accounts data (used for account name enrichment)

   Important for filtered list calls (SuiteQL access): any list call with a filter[*] parameter (e.g. filter[updated_since], filter[id_since]) on invoices, bills, or credit-notes is routed through NetSuite's REST/SuiteQL endpoint instead of SOAP. SuiteQL has its own access checks on every table touched by the query (the transaction table plus the customer JOIN), so on top of the standard Setup permissions the role must include:

   PERMISSION	AREA	LEVEL
   SuiteAnalytics Workbook	Reports	Edit
   Find Transaction	Transactions	View
   Invoice / Bill / Credit Memo	Transactions	View (per resource used)
   Customers	Lists	View

   The address subrecords joined into the invoice list (transactionBillingAddress, transactionShippingAddress) inherit access from the parent transaction record — there is no separate Lists > Address permission to grant.

   If a permission is missing, NetSuite does not say which one in a single response. Each missing permission produces a distinct symptom:

   What's missing	Symptom on filtered list calls
   SuiteAnalytics Workbook	400 Bad Request — Invalid search query. Your current role does not have permission to perform this action.
   Find Transaction	400 Bad Request — Invalid search query. Search error occurred: Record 'transaction' was not found.
   Customers	400 Bad Request — Invalid search query. Search error occurred: Record 'customer' was not found.
   Invoice / Bill / Credit Memo (per type)	200 OK with data: [] — query succeeds but every row of the corresponding type is silently filtered out, so the integration looks healthy while returning nothing

   The Setup permissions REST Web Services, SOAP Web Services and Log in using Access Tokens are needed for any Apideck connection (Apideck validates the connection through a SOAP call before any SuiteQL request runs); they are listed in the Setup table further below. Non-filter list calls and GET /accounting/{resource}/{id} calls go through SOAP and don't require SuiteAnalytics Workbook or Find Transaction.

   See Syncing large NetSuite transaction datasets for why filtered list calls are the recommended path for large datasets.

   Transactions

   TRANSACTIONS PERMISSION	LEVEL
   Access Payment Audit Log	View/Full
   Audit Trail	View/Full
   Automated Cash Application	View/Full
   Bill Purchase Orders	View/Full
   Bills	View/Full
   Calculate Time	View/Full
   Cash Sale	View/Full
   Cash Sale Refund	View/Full
   Check	View/Full
   Credit Card	View/Full
   Credit Card Refund	View/Full
   Credit Memo	View/Full
   Credit Returns	View/Full
   Customer Deposit	View/Full
   Customer Payment	View/Full
   Customer Refund	View/Full
   Deposit	View/Full
   Deposit Application	View/Full
   Edit Forecast	View/Full
   Enter Opening Balances	View/Full
   Enter Vendor Credits	View/Full
   Estimate	View/Full
   Expense Report	View/Full
   Finance Charge	View/Full
   Find Transaction	View/Full
   Fulfill Orders	View/Full
   Generate Price Lists	View/Full
   Generate Statements	View/Full
   Import Online Banking File	View/Full
   Invoice	View/Full
   Invoice Approval	View/Full
   Invoice Sales Orders	View/Full
   Item Fulfillment	View/Full
   Item Receipt	View/Full
   Make Journal Entry	View/Full
   Matching Rules for Online Banking	View/Full
   Opportunity	View/Full
   Pay Bills	View/Full
   Payments	View/Full
   Pay Sales Tax	View/Full
   Post Vendor Bill Variances	View/Full
   Posting Period on Transactions	View/Full
   Purchase Order	View/Full
   Receive Order	View/Full
   Receive Returns	View/Full
   Reconcile	Edit
   Refund Returns	View/Full
   Return Auth. Approval	View/Full
   Return Authorization	View/Full
   Sales Order	View/Full
   Sales Order Approval	View/Full
   Set Up Budgets	View/Full
   Statement Charge	View/Full
   System Journal	View/Full
   Timer	View/Full
   Time Entry	View/Full
   Time Tracking	View/Full
   Track Time	View/Full
   Transfer Funds	View/Full
   Vendor Bill Approval	View/Full
   Vendor Payment Approval	View/Full
   Vendor Return Auth. Approval	View/Full
   Vendor Return Authorization	View/Full
   Vendor Returns	View/Full
   View Gateway Asynchronous Notifications	View/Full
   View Payment Events	View/Full

   Reports

   REPORTS PERMISSIONS	LEVEL
   SuiteAnalytics Workbook	Edit
   Financial Statements	View

   List

   LISTS PERMISSIONS	LEVEL
   Accounts	View/Full
   Classes	View/Full
   Companies	View/Full
   Contacts	View/Full
   Currency	View/Full
   Customers	View/Full
   Documents and Files	View/Full
   Departments	View/Full
   Items	View/Full
   Locations	View/Full
   Projects	View/Full
   Subsidiaries	View/Full
   Tax Details Tab	Full
   Tax Records	View/Full
   Vendors	View/Full

   Important for Invoice Items writes: The Lists → Currency permission (View) is required for POST /accounting/invoice-items and PATCH /accounting/invoice-items/{id}. The connector resolves the currency ISO code to a NetSuite internal ID via an internal currenciesAll call during every write. Without this permission that call is denied, the currency cannot be resolved, and the write returns a 400 error with a message indicating the currency could not be resolved. Grant View access at minimum; Full is required if you also create or modify currencies.

   If you cannot grant this permission, supply the NetSuite internal currency id directly via pass_through, which bypasses the lookup entirely:

   "pass_through": [{ "service_id": "netsuite", "extend_object": { "currency_id": "1" } }]

   You can set any other record field the same way using listAcct:-prefixed keys in compact-XML shape (e.g. "listAcct:isTaxable": { "_text": "true" }). Any other extend_object key (e.g. a bare currency) is rejected with a clear error, because for SOAP connectors it would serialize outside the request envelope and break the request — use currency_id, a listAcct: key, or pass_through.extend_paths with a full JSONPath instead.

   Important for per-line tax on expenses (SuiteTax): The Lists → Tax Details Tab permission is required for POST /accounting/expenses and PATCH /accounting/expenses/{id} whenever a line carries line_items[].tax_rate and the connection has SuiteTax enabled.

   Expenses post to a NetSuite Credit Card Charge, which is a SuiteTax-only record. The legacy per-line taxCode field is a no-op there, so the connector applies each line's tax code by writing a tax-details override block on the record instead. NetSuite's tax engine refuses that block unless the role holds this permission.

   Without it the write fails as a tax-engine error rather than a permission error, so the message does not obviously point at a role setting:

   Unable to save the transaction due to an error being reported by the tax calculation
   engine: A User Error Has Occurred: Permission Violation: You need the
   'Lists -> Tax Details Tab' permission to access this page.
   

   Grant Full. Unlike most Lists permissions this is not a View/Full pair: it is only consulted when writing the tax-details block, so View adds nothing — reading an expense's per-line tax_rate works without this permission at all. Full is also the level confirmed working in practice.

   This is separate from Lists → Tax Records, which covers the tax code and tax type records themselves; both are needed.

   If you are narrowing an existing role's permissions, keep this one. Removing it does not surface until an expense is created with per-line tax rates, and the failure above gives no hint that a permission was removed.

   Each line must also send both tax_rate.id and tax_rate.rate for per-line tax to apply — see the expenses gotchas.

   Setup

   SETUP PERMISSIONS	LEVEL
   Accounting Lists	Full
   Accounting Management	Full
   Deleted Records	Full
   Log in using Access Tokens	Full
   Other Lists	Full
   REST Web Services	Full
   SOAP Web Services	Full

   Note: Financial reports (Profit & Loss, Balance Sheet) use the SOAP getPostingTransactionSummary API which only requires the Financial Statements permission under Reports. This is a less restrictive permission than SuiteQL which requires "SuiteAnalytics Workbook". Without Financial Statements permission, these endpoints will return 401 Unauthorized errors.

Assign a user to the role

It is recommended that you create a separate user for this purpose instead of assigning the role to an existing user. It helps with better tracking and auditing operations.

1. Click Lists > Employees > New

2. Enter the employee details (e.g. Integration User), and email address.

3. Click Access tab

   • select Give Access.

   • Enable Manually Assign or Change Password and specify a password.

4. Under Roles, select the appropriate role from the dropdown and click Add.

   • Bundle path: select Apideck Unify (installed by the bundle)
   • Manual path: select the role you created (e.g. Integration Role)

   

Create an Application

Bundle path users: skip this section. The bundle installs the Apideck Unify Integration Record which provides the Consumer Key and Secret automatically. You do not need to create your own application — continue to Create access tokens.

Once the role is set up, you can follow these steps to generate the consumer Key & Secret:

1. Log in to your NetSuite account with a user who has been assigned the role (e.g Integration Role) that has access.

2. Go to Setup > Integrations > Manage integrations.

   

3. Click the 'New' button to create a new integration or select an existing integration that you want to use.

   • Name: Enter a meaningful name (for example, Integration App)
   • Authentication: Under the 'Authentication' section,
     • Check 'Token-Based Authentication'
     • Check 'TBA: Authorization Flow' (leave Callback URL blank)
   • OAuth 2.0: Leave all OAuth 2.0 options unchecked — Apideck uses Token-Based Authentication only

   Click the 'Save' button to save the changes.

4. Once saved, the Consumer Key and Consumer Secret will be generated.

   💡 REMARK: Copy the "Consumer Key" and the "Consumer secret". You can not access this information once you exit this screen.

Create Access tokens

Create a New Access Token with the Role just created.

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

2. Click the 'New' button to create a new Access token

3. Complete the form

   

   • Select the "Application name":

     • Bundle path: select Apideck Unify (installed by the bundle)
     • Manual path: select the application you created in the previous step (e.g. Integration App)

   • Select the "User", which we created in the previous steps (e.g. Integration User)

   • Select the "Role":

     • Bundle path: select Apideck Unify
     • Manual path: select the role you created (e.g. Integration Role)

   • Give the token a recognizable "token name", for example Integration Token

   • Click the 'Save' button to save the changes.

4- Once saved, the Account Token ID and Secret will be generated.

💡 REMARK: Copy the "Token Id" and the "Token secret". You can not access this information once you exit this screen.

Find your Account ID

1. Go to Setup > Company > Company Information

2. Copy the Account ID

Configure the Netsuite connection

Bundle path — only 3 fields are required:

Field	Where to find it
Account ID	Setup → Company → Company Information
Token ID	Generated when you created the access token
Token Secret	Generated when you created the access token

Leave Consumer Key and Consumer Secret blank — Apideck fills these automatically from the Apideck Unify Integration Record installed by the bundle.

Manual path — all 5 fields are required:

Field	Where to find it
Account ID	Setup → Company → Company Information
Consumer Key	Generated when you saved the Integration Record
Consumer Secret	Generated when you saved the Integration Record
Token ID	Generated when you created the access token
Token Secret	Generated when you created the access token

Bank Feeds (optional)

If you want to push bank statements into NetSuite's Match Bank Data workflow through the Unify bank-feed-statements endpoint, a small amount of extra setup is needed on top of the standard connection above.

At a glance:

1. Install the Apideck Bank Feed bundle in your NetSuite account. Your Apideck contact will share the bundle ID and installation instructions.

2. Install the NetSuite Bank Statement Parsers SuiteApp (bundle ID 293699, published by Oracle NetSuite, free). This provides the CSV parser that the Apideck bundle feeds into. Install it from Customization → SuiteBundler → Search & Install Bundles.

3. Create a Format Profile (Setup → Accounting → Financial Institution → Format Profiles) linking the Apideck connectivity plug-in to the NetSuite bank accounts you want to feed.

4. Provide two extra connection fields in the Apideck Vault for your NetSuite connection:

   • Bank Feed RESTlet Script ID
   • Bank Feed RESTlet Deploy ID

   You can find both under Customization → Scripting → Scripts → Apideck Bank Feed RESTlet, on the Deployments tab. Each row's External URL contains script=<numeric_id> and deploy=<numeric_id> — those are the values to paste into the Vault.

The full walkthrough — including the extra role permissions you must add to the Apideck Unify role, Format Profile field mapping and formatting preferences, account linking, day-to-day operations and troubleshooting — is in the dedicated Apideck Bank Feed for NetSuite setup guide (see Prerequisites → Role permissions). You only need that guide if you intend to use the bank-feed-statements endpoint; regular NetSuite integrations don't require any of these steps.