Skip to main content

​
About NetSuite

NetSuite is Oracle’s cloud ERP for financials, orders, inventory, and CRM. Serval connects to one NetSuite account per connection - the connection is named “NetSuite [Account ID]” and keyed by your Account ID - and calls NetSuite’s SuiteTalk REST Web Services and RESTlets on demand when your workflows run. There are no prebuilt helpers or shipped workflows; every call goes through Serval’s generic NetSuite API request action. Authentication: OAuth 2.0 client credentials (certificate-based machine-to-machine, the default and recommended option) or token-based authentication (TBA / OAuth 1.0a) for existing setups. Data sync: On demand only. NetSuite data is read or written when a workflow step runs - there is no background sync or entity ingestion.

​
What the NetSuite integration enables

Anything defined in the NetSuite API can be accessed through Serval.

​
Get your credentials

Everything Serval needs is created inside NetSuite. Start with the prerequisites that apply to both authentication methods, then follow the tab for the method you plan to use. Oracle’s official reference for REST Web Services is here.
1

Find your Account ID

In NetSuite, go to Setup → Company → Company Information and copy the Account ID. Sandbox accounts use the underscore form, such as 1234567_SB1.
2

Enable REST Web Services

Go to Setup → Company → Enable Features → SuiteCloud and enable SuiteTalk REST Web Services.
3

Create or select an integration record

Go to Setup → Integration → Manage Integrations → New and create (or pick) the integration record Serval will use.
1

Enable OAuth 2.0 on the integration record

Enable OAuth 2.0 on the integration record and copy the Client ID.
2

Upload your certificate and copy the Certificate ID

Go to Setup → Integration → OAuth 2.0 Client Credentials (M2M) Setup, pick the integration and role, upload your public certificate, and copy the generated Certificate ID.
3

Keep the matching private key

Keep the PEM private key that matches the uploaded certificate - you will paste it into Serval, including the BEGIN and END lines.
The signing algorithm you pick in Serval must match the key and certificate pair you uploaded to NetSuite. RSA-PSS (PS256, the default) and ECDSA algorithms are supported - plain RS256 is not.

​
Connect in Serval

1

Enter your NetSuite Account ID

Fill in NetSuite Account ID (required) - the placeholder shows “1234567 or 1234567_SB1”. Use the ID from Setup → Company → Company Information, in its native form (underscores for sandboxes). Leaving it (or any required field) blank is flagged in the form with “This field is required”, and the ID may only contain letters, numbers, underscores, and hyphens - anything else is rejected on save with “account ID can only contain letters, numbers, underscores, and hyphens”.
2

Choose an Authentication method

Authentication method defaults to “OAuth 2.0 client credentials (service account)”; “Token-based authentication (OAuth 1.0/TBA)” is available for existing TBA setups. If a configuration reaches Serval with no method recorded but with any token-based credential filled in, Serval infers token-based authentication. An unrecognized value is rejected with “unsupported authentication method “[value]"".
3

Fill in the credentials for your method

For OAuth 2.0 client credentials: Client ID (required), Certificate ID (required - the certificate ID generated on NetSuite’s M2M setup page), Signing Algorithm (optional select, default “PS256 (RSA-PSS SHA-256)”; also PS384, PS512, ES256, ES384, ES512), Private Key (required multiline secret field - paste the PEM key including the BEGIN and END lines; a missing key is rejected on save with “private key is required for OAuth 2.0 client credentials”), and OAuth 2.0 Scopes (required, pre-filled with rest_webservices; the form suggests rest_webservices, restlets, and suite_analytics as common values, and at least one scope must remain in the list).For token-based authentication: Consumer Key, Consumer Secret, Token ID, and Token Secret are all required. These are secret fields, so a missing one is reported on save with a matching message - for example “consumer key is required for token-based authentication” and “token secret is required for token-based authentication”.
4

Submit the connection

Click Submit to create the connection, named “NetSuite [Account ID]”. Any validation failure is reported as “Invalid NetSuite configuration” followed by the specific cause.
When editing an existing connection, saved secrets appear masked - bullets with only the last four characters visible - alongside a Replace button. Leave a masked secret as-is (or any field blank) to keep the stored value - only the fields you fill in are replaced.

​
Verifying the connection

Serval ships one health check for NetSuite: Test NetSuite Connection - verifies that NetSuite authentication succeeds and REST Web Services are reachable by reading NetSuite’s record metadata catalog with your configured credentials.
  • On success: “Successfully authenticated with NetSuite and reached REST Web Services.”
  • On failure: “Unable to connect to NetSuite. Verify the account ID, selected authentication method, credentials, and REST Web Services permissions.”
A green test only proves REST Web Services access. RESTlet calls additionally need the restlets scope (OAuth 2.0) granted both in Serval and to the NetSuite integration record - and SuiteQL queries, which run through REST Web Services, depend on the connected role’s permissions. For token-based authentication, permissions follow the token’s user and role.

​
Gotchas and troubleshooting

Serval automatically lowercases your Account ID and converts underscores to hyphens to build the NetSuite API address - 1234567_SB1 becomes 1234567-sb1. Enter the ID exactly as NetSuite shows it (underscores for sandboxes, such as 1234567_SB1). For token-based authentication, the ID is also used as the realm exactly as you entered it, so don’t hand-convert it yourself.
The consumer secret and token secret are displayed by NetSuite a single time, at creation. Capture both immediately; if they’re lost, create a new access token or integration record and update the Serval connection.
Only PS256, PS384, PS512 (RSA-PSS) and ES256, ES384, ES512 (ECDSA) signing algorithms are accepted, matching NetSuite’s machine-to-machine requirements. The default is PS256. Anything else is rejected with “unsupported OAuth 2.0 signing algorithm “[value]"", and the algorithm must match the key type of the certificate uploaded to NetSuite.
Serval requests the scopes you list (rest_webservices is pre-filled). REST Web Services calls - including SuiteQL queries - are covered by rest_webservices; calling RESTlets requires the restlets scope; suite_analytics is the other common value the form suggests. Whatever you request, the NetSuite integration record and role must actually be granted the matching access. Under token-based authentication there are no scopes; permissions follow the token’s user and role.
Serval fetches a fresh access token for every request, so a misconfigured certificate or key fails when a workflow (or the health check) runs - with errors like “failed to decode PEM private key”, “failed to parse PEM private key”, “PEM private key must be RSA or ECDSA”, or “NetSuite token request failed with status [number]” followed by NetSuite’s response. Run the health check right after saving to catch these early.
Updates merge field by field: blank fields keep their existing values and masked secrets keep the stored secret. When switching methods, explicitly fill in every field the new method requires - the previous method’s saved values remain stored but are no longer used.
All validation failures on create or update are reported as “Invalid NetSuite configuration” followed by the specific cause - for example “consumer key is required for token-based authentication”. Read the attached message to find the exact field to fix. (Blank required fields are flagged inline in the form with “This field is required” before anything is sent.)
This integration ships no prebuilt workflows, typed endpoints, or entity ingestion. Everything runs through the generic NetSuite API request action against your account’s REST Web Services and RESTlet hosts, so workflow authors describe the NetSuite resource they want to reach.
Need help? Contact support@serval.com for assistance with your NetSuite integration.