NetSuite Connector Setup

Overview

The NetSuite connector extracts financial data -- GL journal entries, AR invoices, AP bills, accounts, subsidiaries, and more -- using the SuiteQL REST API. VersionForge supports two authentication modes: Token-Based Authentication (TBA) using OAuth 1.0a signatures, and Machine-to-Machine (M2M) using OAuth 2.0 client credentials.

TBA is the most common setup and the one we recommend for most implementations. M2M requires a certificate ID and is typically used in fully automated, headless environments.

Prerequisites

• A NetSuite account with Administrator or equivalent role access to create integrations
• SuiteQL analytics enabled on your account (Setup > Company > Enable Features > SuiteCloud > SuiteAnalytics Workbook)
• Your NetSuite Account ID (found under Setup > Company > Company Information)

Credential Fields

| Field | Required | Description | |-------|----------|-------------| | accountId | Yes | Your NetSuite account ID (e.g., 1234567 or TSTDRV1234567). Underscores in sandbox IDs are normalized automatically. | | clientId | Yes | Consumer key from your NetSuite integration record. | | clientSecret | Yes | Consumer secret from your NetSuite integration record. | | tokenId | TBA only | Token ID generated for your integration user. | | tokenSecret | TBA only | Token secret generated for your integration user. | | certificateId | M2M only | Certificate ID for OAuth 2.0 client credentials flow. |

Setup Steps

1. Create an Integration Record

   Navigate to Setup > Integration > Manage Integrations > New. Give it a descriptive name like "VersionForge Sync". Enable Token-Based Authentication under the Authentication section. Save the record and copy the Consumer Key and Consumer Secret -- these map to clientId and clientSecret in VersionForge.

   The consumer secret is only shown once when you create the integration. Copy it immediately and store it securely.

2. Create a Dedicated Role

   Go to Setup > Users/Roles > Manage Roles > New. Create a role named "VersionForge Integration" with these permissions:

   • Transactions: View access to Journal Entries, Bills, Invoices, and Vendor Bills
   • Lists: View access to Accounts, Subsidiaries, Departments, Locations, Classes, Currencies
   • Reports: SuiteAnalytics Workbook permission (for SuiteQL)
   • Setup: Log In Using Access Tokens, SuiteAnalytics Connect

   Restrict the role to the subsidiaries you want VersionForge to access.

3. Assign the Role and Generate Tokens

   Assign the role you created to an integration user (or a service account). Then navigate to Setup > Users/Roles > Access Tokens > New. Select your application (integration record), the user, and the role. Click Save and immediately copy the Token ID and Token Secret.

4. Configure the Credential in VersionForge

   In the VersionForge UI, navigate to Administration > Credentials > Add Credential. Select NetSuite as the connector type and enter all required fields. For TBA, provide accountId, clientId, clientSecret, tokenId, and tokenSecret.

Test Your Connection

After saving the credential, use the Test Connection button on the credential detail page. VersionForge issues a lightweight SuiteQL query (SELECT id FROM account LIMIT 1) to verify authentication and SuiteQL access. A successful test confirms:

• Your OAuth signature (TBA) or bearer token (M2M) is valid
• The role has SuiteQL query permissions
• The account ID resolves to a valid NetSuite REST endpoint

Common Issues

401 Unauthorized on test -- Double-check that the integration user has the correct role assigned and that "Log In Using Access Tokens" is enabled on that role. Also verify your account ID format: sandbox accounts use underscores (e.g., 1234567_SB1) which VersionForge converts to hyphens automatically.

403 INSUFFICIENT_PERMISSION -- The role is missing the SuiteAnalytics Workbook permission. Edit the role under Setup > Users/Roles > Manage Roles and add it.

Token expired or revoked -- NetSuite TBA tokens do not expire on their own, but they can be manually revoked. If a token stops working, generate a new one from the Access Tokens page and update the credential in VersionForge.