Skip to main content
Reconcile the first import against NetSuite before relying on its reports. A role or subsidiary restriction can hide records without an error, so an apparently successful sync can still be incomplete.
Control connects directly to NetSuite’s REST API. This connection does not use Nango. Each Control entity connects to one NetSuite subsidiary and the primary accounting book. Set the Control entity currency to the subsidiary’s base currency. The connection test and imports reject a mismatch to prevent reporting amounts in the wrong currency. There are two ways to connect:
  • Every subsidiary of an account. Enter the credentials once. Control lists the account’s subsidiaries and imports each one into its own entity. This is the way to connect a group. See Connect the whole account.
  • One subsidiary. Connect one entity to one subsidiary. See Connect one entity.
An account connection counts as one integration towards your plan and trial limits, however many subsidiaries it imports.

Before you start

A NetSuite administrator must configure the connection. You need:
  • REST Web Services and OAuth 2.0 enabled under Setup → Company → Enable Features → SuiteCloud.
  • SuiteAnalytics Workbook enabled under Enable Features → Analytics, with the role’s Reports → SuiteAnalytics Workbook permission set to Edit. Financial record and transaction permissions should remain read-only.
  • A dedicated integration user and role with access to the subsidiaries you want in Control. To connect the whole account, set the role’s subsidiary restriction to All. All includes inactive subsidiaries; Active does not, so inactive subsidiaries would be left out of the list.
  • Read access to the transaction, transaction line, transaction accounting line, account, subsidiary, currency, accounting period and enabled department/class/location records used by the connector. Accounting-book metadata is checked unless an administrator independently verifies a single-book account as described below.
  • The REST Web Services and Log in using OAuth 2.0 Access Tokens permissions. Review the role’s Records Catalog to confirm that the required SuiteQL records and fields are available. Transaction permissions must cover every posting transaction type you want reported.
Use a dedicated role with the minimum necessary access; do not give Control an Administrator role. An apparently successful query can still omit records hidden by role or subsidiary restrictions. Reconciliation is required to detect incomplete access.

1. Create the integration application

In NetSuite, open Setup → Integration → Manage Integrations → New. Give the application a recognizable name, enable OAuth 2.0 Client Credentials (Machine to Machine) and the REST Web Services scope, and save it. Record the Client ID. This flow does not require a client secret, callback URL or recurring interactive sign-in.

2. Create a certificate and private key

On a trusted computer, generate a P-256 key and an X.509 certificate:
Follow the prompts to identify your organization. Upload only the public certificate to NetSuite. The private key is uploaded through Control’s secure integration setup and stored in its secret store. Never send it through email, Slack, a support ticket or a chat assistant. Control supports EC P-256 (ES256) and RSA 3072/4096-bit (PS256) private keys. The public certificate must match the private key. NetSuite certificates have a maximum validity of two years; the example above uses one year.

3. Map the certificate in NetSuite

Open Setup → Integration → Manage Authentication → OAuth 2.0 Client Credentials (M2M) Setup. Create a mapping for the integration application, dedicated user and role. Upload netsuite-public.pem and save the mapping. Record the generated Certificate ID. Sandbox mappings are separate from production mappings. A sandbox refresh does not preserve the production OAuth setup; verify and recreate the mapping as needed after refreshes.

4. Connect the whole account

In Entities & Data sources, choose Add data source on any entity, select NetSuite, then Connect NetSuite account. Enter the account ID, client ID, certificate ID, private key and accounting book ID from the table in Connect one entity. There is no subsidiary ID: Control lists the subsidiaries for you. Set Account features only as described in Accounts without Multi-Book Accounting or individual dimensions. Control saves the credentials and lists the subsidiaries the role can see. Listing imports nothing. For each subsidiary, choose: Then select Apply. Control tests and imports the subsidiaries one at a time, in subsidiary ID order. Each subsidiary becomes the NetSuite data source of its entity and joins the scheduled sync after its first import. The connection page shows each subsidiary’s status:
  • Queued, Testing, Importing and Imported follow the first import. The page updates on its own while work is running.
  • Failed shows the reason. Fix it in NetSuite, then select Retry.
  • Blocked shows why the action could not be applied, for example a different currency or an entity that already has an accounting data source. Choose another action and apply again.
  • Held means a data check stopped the latest import from reaching reports. Reports keep the last published version until the check passes; the reasons are listed.
Inactive and elimination subsidiaries are listed and imported like any other subsidiary, and their flags are shown. Skip the ones you do not want to report. Rediscover lists subsidiaries added in NetSuite since the last listing. It imports nothing: choose an action for the new ones and apply. A subsidiary the role can no longer see is marked Missing from last discovery; its entity and history are kept. If you delete an entity Control created for a subsidiary, Control does not create it again.

Import the other subsidiaries of an existing connection

If an entity already uses a single-subsidiary NetSuite connection, open that data source and select Import other subsidiaries. Control reuses the saved credentials, so you do not enter them again. The existing entity keeps its subsidiary, accounting book and import history, and the account’s other subsidiaries are listed for you to import as above. If the account is already connected, Control opens that connection instead. Select Rediscover there to link existing single-subsidiary NetSuite data sources of the same account to their subsidiaries.

5. Connect one entity

In Entities & Data sources, select the entity and add the native NetSuite integration. Enter: Run the credential test. It checks the selected subsidiary/book, reference-data access and a sample GL transaction when one is available. A successful test confirms API access; it does not prove complete financial coverage.

Accounts without Multi-Book Accounting or individual dimensions

Leave Account features unchanged unless a NetSuite administrator has verified the settings independently of an API error.
  • Single-book accounting verified: select only after confirming that Full Multi-Book Accounting and Adjustment Only Books are both disabled under Setup → Company → Enable Features → Accounting. The book ID must be observed in NetSuite; do not assume it is 1. An option missing from a menu, one visible book, or a book’s display name alone does not establish this configuration. If the feature status is unavailable, confirm it with the account administrator or NetSuite support before selecting this option.
  • Verified disabled dimensions: select Departments, Classes or Locations only when the corresponding feature is unchecked under Enable Features → Company → Classifications. Missing permissions must be fixed in the reporting role, not treated as a disabled feature.
With a verified single-book account, Control still rejects conflicting book metadata and checks the entered book ID against a bounded posting sample if the metadata record is unavailable. An empty account cannot use that fallback until a posting is available. In an account connection the check runs for each subsidiary: an empty subsidiary in a single-book account without readable book metadata fails its test until it has a posting. Retry it after the first posting. Subsidiary, base currency and book filters remain enforced. Verified disabled dimensions are omitted from reference queries and reported as empty dimension values. Changing that configuration re-reads existing transactions on the next import. If either Multi-Book feature or a dimension is later enabled, update and verify the connection settings before refreshing. Reconfirm account features when replacing credentials; changing the Account ID clears the confirmations, and changing the book ID clears the single-book confirmation. Do not enable an accounting feature or grant financial-record write access merely to make a connection test pass.

What is imported

  • Posted GL entries, with debit and credit amounts in the subsidiary’s base currency.
  • Transaction and line identifiers, document numbers/types, dates, accounting periods and descriptions.
  • Chart of accounts, counterparties referenced by postings, and department/class/location dimensions.
  • The subsidiary and accounting-period reference data needed for reporting, including a conservative closed-through date that stops at reopened periods.
The connector reads the full accessible posting history on the first import. Refreshes compare transaction modification versions across that history, fetch changed transactions in full, and reconcile removed transactions and lines. Historical corrections are not limited to a recent posting-date window. Full reloads re-read every transaction. Financial amounts retain decimal precision. Reporting uses the posting period when a transaction date falls outside it. The pilot does not import invoice attachments, open AR/AP ageing, inventory movements, payroll details or custom segments, and does not write back to NetSuite. Secondary accounting books are rejected to prevent applying an incorrect base currency.

Validate the first import

Compare a closed period’s trial balance and P&L with NetSuite using the same subsidiary, primary book, currency and posting periods. Include balance-sheet opening balances, journals, invoices, credits and any period-end adjustments. Check department/class/location splits and counterparty labels. In a sandbox, verify that changing an old transaction, removing a line, voiding/deleting a transaction and rerunning a refresh produces the expected result without duplicates. Do not modify production transactions merely to test the connector.

Rotate or revoke access

Before the certificate expires, create a new key/certificate, add a new NetSuite mapping, and replace the connection credentials in Control. Test the new credentials before revoking the previous mapping.
  • Account connection: select Replace credentials on the connection page. Every subsidiary of the account uses the new credentials. Confirm the account features again.
  • Single-subsidiary connection: update each Control entity using the old mapping.
To stop access, disable the Control integration and revoke the certificate mapping or integration application in NetSuite. Disabling sync in Control alone does not revoke the credential in NetSuite.

Troubleshooting

  • OAuth/401 error: check the account, Client ID, Certificate ID, matching private key, expiry and user/role/application mapping. Sandbox and production account IDs and mappings differ.
  • Permission/403 error or missing fields: have an administrator check the dedicated role and Records Catalog. Confirm access to all posting transaction types and the subsidiary.
  • A subsidiary is missing from the list: check the role’s subsidiary restriction. Active leaves out inactive subsidiaries; use All. Then select Rediscover.
  • Secondary-book error: select the primary book. A secondary book can have a different base currency and is not supported in this pilot.
  • Primary-book or dimension reference error: check the actual account features as an administrator. Use the verified settings above only for independently confirmed disabled features; other missing records or permission errors remain failures.
  • Transactions changed during extraction: Control rechecks changed transactions up to three times. If posting activity still prevents a complete extraction, retry after it settles. The previous incremental checkpoint is preserved.
  • Totals differ: compare posting periods, opening balances, subsidiary/book selection and role restrictions before changing account mappings in Control.

Oracle references