Developer ToolsFree referencePDF, Excel, Word exportNetSuiteAll NetSuite tools

NetSuite REST API Reference: Headers, Query Parameters and Endpoints

A single lookup table for the SuiteTalk REST Web Services headers, query parameters and base endpoints you need when building or debugging a NetSuite integration. Search by name, kind or service, then copy the example line into Postman or your client code.

Download:

Name	Kind	Applies to	Values	Default	Example	Notes
Authorization (OAuth 1.0 TBA)	Request header	All REST services	OAuth realm, oauth_consumer_key, oauth_token, oauth_signature_method, oauth_timestamp, oauth_nonce, oauth_version, oauth_signature	Required	Authorization: OAuth realm="1234567_SB1", oauth_consumer_key="...", oauth_token="...", oauth_signature_method="HMAC-SHA256", ...	realm is the account ID in upper case with underscore (1234567_SB1 for sandbox 1). Signature method HMAC-SHA256.
Authorization (OAuth 2.0)	Request header	All REST services	Bearer <access_token>	Required	Authorization: Bearer eyJraWQiOi...	Access token from the OAuth 2.0 token endpoint. Tokens expire, plan the refresh.
Content-Type	Request header	POST, PUT, PATCH with a body	application/json	None	Content-Type: application/json	Record and SuiteQL bodies are JSON.
Prefer: transient	Request header	query/v1/suiteql	transient	Required for SuiteQL	Prefer: transient	Oracle help states it is a required header for SuiteQL POST requests. Missing it is a common cause of failed SuiteQL calls.
Prefer: respond-async	Request header	Any REST request (record or query)	respond-async	Synchronous if omitted	Prefer: respond-async	Queues the request. Response is 202 with a Location header pointing to the async job.
X-NetSuite-idempotency-key	Request header	Asynchronous requests	Unique key, UUID format in Oracle examples	None	X-NetSuite-idempotency-key: cac827ea-3543-4cda-add2-bae634326c27	Reusing a submitted key returns IDEMPOTENCY_ERROR and a Location header to the original job, so retries do not create duplicates.
X-NetSuite-PropertyNameValidation	Request header	Record API create and update	ignore \| warning \| error	warning	X-NetSuite-PropertyNameValidation: error	Controls what happens with unknown or misspelled field names in the body. Use error in test so typos fail loudly instead of being dropped.
X-NetSuite-PropertyValueValidation	Request header	Record API create and update	ignore \| warning \| error	error	X-NetSuite-PropertyValueValidation: warning	Controls syntax errors in field values. Semantic errors such as a non-existent internal ID always return an error.
Preference-Applied	Response header	Async responses	respond-async	N/A	Preference-Applied: respond-async	Confirms the server accepted the async preference.
Location	Response header	Create, update, transform, async	URL of the record or job	N/A	Location: https://1234567.suitetalk.api.netsuite.com/services/rest/record/v1/customer/647	Create returns 204 with no body. Parse the new internal ID from the last path segment of Location.
limit	Query parameter	Record collections, query/v1/suiteql	Integer page size	1000	?limit=200	Default page size is 1000. SuiteQL over REST returns at most 100,000 results in total.
offset	Query parameter	Record collections, query/v1/suiteql	Integer start index	0	?limit=200&offset=400	Offset must be divisible by limit (offset=20, limit=10 is valid). Follow the next link in the response instead of computing it.
q	Query parameter	Record collection GET	field OPERATOR value, joined with AND / OR	None	?q=email START_WITH barbara	Only fields marked x-ns-filterable in metadata. Quote values with spaces. AND binds before OR, parentheses allowed.
q operators (string)	Query parameter	Record collection GET	CONTAIN, CONTAIN_NOT, IS, IS_NOT, START_WITH, START_WITH_NOT, ENDWITH, END_WITH_NOT (as spelled in help)	N/A	?q=companyname START_WITH "Another Company"	Oracle help spells the end-with operator inconsistently; test it on your account.
q operators (number)	Query parameter	Record collection GET	ANY_OF, BETWEEN, EQUAL, GREATER, GREATER_OR_EQUAL, LESS, LESS_OR_EQUAL, WITHIN, plus _NOT forms	N/A	?q=id ANY_OF [1, 2, 3]	BETWEEN and WITHIN take two values, ANY_OF takes a list.
q operators (date and boolean)	Query parameter	Record collection GET	AFTER, BEFORE, ON, ON_OR_AFTER, ON_OR_BEFORE (+ _NOT); IS, IS_NOT; EMPTY, EMPTY_NOT	N/A	?q=dateCreated ON_OR_AFTER "1/1/2026"	Date format follows N/query rules, not the ISO format used in record bodies.
fields	Query parameter	Single record GET	Comma list of body field IDs	All fields	?fields=companyName,email,entityId	Body fields only. Selective retrieval of sublist and subrecord fields is not supported.
expandSubResources	Query parameter	Single record GET	true \| false	false	?expandSubResources=true	Returns sublists and subrecords inline instead of as links. Larger payloads, fewer round trips.
simpleEnumFormat	Query parameter	Record GET	true \| false	false	?simpleEnumFormat=true	Returns select and enum values in a simpler form. Check the REST API Browser for the exact shape on your record type.
replace	Query parameter	PATCH and PUT	Comma list of sublist or field names	None (lines are merged)	PATCH .../purchaseOrder/88?replace=item	The sublist in the body becomes the full sublist. Omitted lines are removed. This is how you delete lines and update non-keyed sublists.
replaceSelectedFields	Query parameter	PATCH	true \| false	false	PATCH .../myrecord?replaceSelectedFields=true&replace=body1	Only the fields named in replace and set to null in the body are cleared.
/services/rest/record/v1/{recordType}	Endpoint	Record API	GET list, POST create	N/A	POST /services/rest/record/v1/salesOrder	Record type names are camelCase as shown in the metadata catalog (salesOrder, inventoryItem).
/services/rest/record/v1/{recordType}/{id}	Endpoint	Record API	GET, PATCH, PUT (upsert by eid:), DELETE	N/A	GET /services/rest/record/v1/customer/107	Use eid:<externalId> in place of the ID to address by external ID.
/services/rest/record/v1/{recordType}/{id}/!transform/{targetType}	Endpoint	Record API	POST	N/A	POST /services/rest/record/v1/salesOrder/3/!transform/invoice	Body can set fields on the new record. Success returns 204 with Location.
/services/rest/record/v1/metadata-catalog	Endpoint	Metadata	GET, Accept: application/schema+json or application/swagger+json	N/A	GET /services/rest/record/v1/metadata-catalog?select=customer	Field names, types and filterable flags for your account, including custom fields.
/services/rest/query/v1/suiteql	Endpoint	SuiteQL	POST with {"q": "...", "params": [...]}	N/A	POST /services/rest/query/v1/suiteql?limit=1000	Requires Prefer: transient. Bound parameters use ? in q and a params array.
/services/rest/async/v1/job/{id}	Endpoint	Async	GET status; /task/{id}/result for output	N/A	GET /services/rest/async/v1/job/123456	Poll the URL from the Location header of the async response.
/services/rest/auth/oauth2/v1/token	Endpoint	OAuth 2.0	POST, form encoded	N/A	POST /services/rest/auth/oauth2/v1/token	Authorization code, refresh token and client credentials (certificate) grants.
Host	Endpoint	All REST services	<accountid>.suitetalk.api.netsuite.com	N/A	https://1234567-sb1.suitetalk.api.netsuite.com	Hostnames use lower case and a hyphen for sandboxes (1234567-sb1). The OAuth realm uses 1234567_SB1.

Values and defaults for the validation headers, Prefer, idempotency key, paging and q operators come from the SuiteTalk REST Web Services API Guide. To build a full record URL with these parameters, use the NetSuite REST Record API URL Builder.

Get your REST integration reviewed

Send us the request and response from a failing call, with credentials removed, and we will point to the header, parameter or permission causing it.

Optional. The tool and every export work without this. No spam.

Was this tool useful?

How to use it

Filter on Kind to see only request headers, response headers, query parameters or endpoints. The Applies to column tells you which service accepts each item: the record API under record/v1, SuiteQL under query/v1/suiteql, or the async job service. The Example column is written for a real request so you can paste it. When a call fails, check three rows first: Prefer: transient for SuiteQL, the two validation headers for create and update, and the offset rule for paging. Those three account for many failed calls that look like authentication problems.

SuiteQL: POST, Content-Type application/json, Prefer: transient
Create: expect 204 and read the new ID from Location
Async: add Prefer: respond-async and an idempotency key for safe retries

Where this lives in NetSuite

These items are documented in the SuiteTalk REST Web Services API Guide in NetSuite help: REST Web Services Request Processing for async and idempotency, Error Handling in REST Web Services for the validation headers, Record Collection Filtering for q, Collection Paging for limit and offset, and Executing SuiteQL Queries Through REST Web Services. The REST API Browser shows every record type, field and sublist for the current release. Your own account's view, including custom fields, comes from the metadata-catalog endpoint. REST Web Services must be enabled under Setup > Company > Enable Features > SuiteCloud, and the role needs the REST Web Services permission plus the permissions for the records it touches.

Worked example: safe async create

To create a customer without risking a duplicate on retry, send POST /services/rest/record/v1/customer with Prefer: respond-async, X-NetSuite-idempotency-key set to a new UUID you store with the source record, and X-NetSuite-PropertyNameValidation: error so a misspelled field fails instead of being silently dropped. The response is 202 with Location pointing to /services/rest/async/v1/job/{id}. Poll that job until it completes, then read the result. If the network drops and you resend with the same key, NetSuite returns IDEMPOTENCY_ERROR and the Location of the original job, so you poll that job rather than creating a second customer.

Gotchas

PropertyNameValidation defaults to warning, which means unknown field names are ignored and reported in a response header that most clients never read. Set it to error in sandbox. Offset must be a multiple of limit, so offset=150 with limit=100 is rejected. SuiteQL over REST stops at 100,000 rows in total; larger extracts belong in SuiteAnalytics Connect or a Map/Reduce script. The q filter works only on fields flagged filterable and does not join, so for anything relational use SuiteQL. Hostnames use 1234567-sb1 while the OAuth 1.0 realm uses 1234567_SB1; mixing them is a classic INVALID_LOGIN cause.

Frequently Asked Questions

What is the base URL for the NetSuite REST API?

https://<accountid>.suitetalk.api.netsuite.com/services/rest/ followed by record/v1, query/v1, async/v1 or auth/oauth2/v1. The account ID in the hostname is lower case and sandboxes use a hyphen, for example 1234567-sb1. You can confirm it under Setup > Company > Company Information > Company URLs.

Why does my SuiteQL REST call fail?

The most common causes are a missing Prefer: transient header, sending the query as a URL parameter instead of a JSON body with a q property, using GET instead of POST, or an offset that is not a multiple of limit. Also check the role has the REST Web Services permission and view access to every record the query touches, since SuiteQL respects role access.

How do I query records with the NetSuite REST API?

For simple filters on one record type, GET the collection with q, for example /record/v1/customer?q=email START_WITH a. It returns IDs and links only. For joins, selected columns or aggregates, POST SuiteQL to /query/v1/suiteql. Use limit and offset or the next link to page through results.

How do I delete a sublist line through REST?

There is no delete for a single line. PATCH the record with ?replace=item (or the sublist name) and send the sublist containing every line you want to keep. The submitted list becomes the full sublist and omitted lines are removed. Test on a sandbox copy first, since a missing line in the body deletes it.

If you want people to ask NetSuite questions in plain English, with the SuiteQL shown and run under their own role on your own infrastructure, we can set that up.

Talk to an Expert Explore More Free Tools