# NetSuite REST API Reference: Headers, Query Parameters and Endpoints

> Source: https://netray.co/tools/netsuite-rest-web-services-headers-and-parameters-reference
> Publisher: Netray (netray.co), AI and integration engineering for ERP and manufacturing systems.
> Section: Free Tools

## Short answer

Every request header, response header, query parameter and base endpoint you use with SuiteTalk REST Web Services, with values, defaults and examples in one table.

## Category

developer

## Erp

NetSuite

## Audience

- NetSuite developer
- Integration engineer
- NetSuite administrator

## Tool

**Kind:** worksheet

**Mode:** reference

**Columns:**

#### Name

**Key:** name

**Type:** text

#### Kind

**Key:** kind

**Type:** select

**Options:**

- Request header
- Response header
- Query parameter
- Endpoint

#### Applies to

**Key:** applies_to

**Type:** text

#### Values

**Key:** values

**Type:** text

#### Default

**Key:** default

**Type:** text

#### Example

**Key:** example

**Type:** text

#### Notes

**Key:** notes

**Type:** text

**Rows:**

#### Authorization (OAuth 1.0 TBA)

**Kind:** Request header

**Applies to:** All REST services

**Values:** OAuth realm, oauth_consumer_key, oauth_token, oauth_signature_method, oauth_timestamp, oauth_nonce, oauth_version, oauth_signature

**Default:** Required

**Example:** Authorization: OAuth realm="1234567_SB1", oauth_consumer_key="...", oauth_token="...", oauth_signature_method="HMAC-SHA256", ...

**Notes:** realm is the account ID in upper case with underscore (1234567_SB1 for sandbox 1). Signature method HMAC-SHA256.

#### Authorization (OAuth 2.0)

**Kind:** Request header

**Applies to:** All REST services

**Values:** Bearer <access_token>

**Default:** Required

**Example:** Authorization: Bearer eyJraWQiOi...

**Notes:** Access token from the OAuth 2.0 token endpoint. Tokens expire, plan the refresh.

#### Content-Type

**Kind:** Request header

**Applies to:** POST, PUT, PATCH with a body

**Values:** application/json

**Default:** None

**Example:** Content-Type: application/json

**Notes:** Record and SuiteQL bodies are JSON.

#### Prefer: transient

**Kind:** Request header

**Applies to:** query/v1/suiteql

**Values:** transient

**Default:** Required for SuiteQL

**Example:** Prefer: transient

**Notes:** 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

**Kind:** Request header

**Applies to:** Any REST request (record or query)

**Values:** respond-async

**Default:** Synchronous if omitted

**Example:** Prefer: respond-async

**Notes:** Queues the request. Response is 202 with a Location header pointing to the async job.

#### X-NetSuite-idempotency-key

**Kind:** Request header

**Applies to:** Asynchronous requests

**Values:** Unique key, UUID format in Oracle examples

**Default:** None

**Example:** X-NetSuite-idempotency-key: cac827ea-3543-4cda-add2-bae634326c27

**Notes:** Reusing a submitted key returns IDEMPOTENCY_ERROR and a Location header to the original job, so retries do not create duplicates.

#### X-NetSuite-PropertyNameValidation

**Kind:** Request header

**Applies to:** Record API create and update

**Values:** ignore | warning | error

**Default:** warning

**Example:** X-NetSuite-PropertyNameValidation: error

**Notes:** 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

**Kind:** Request header

**Applies to:** Record API create and update

**Values:** ignore | warning | error

**Default:** error

**Example:** X-NetSuite-PropertyValueValidation: warning

**Notes:** Controls syntax errors in field values. Semantic errors such as a non-existent internal ID always return an error.

#### Preference-Applied

**Kind:** Response header

**Applies to:** Async responses

**Values:** respond-async

**Default:** N/A

**Example:** Preference-Applied: respond-async

**Notes:** Confirms the server accepted the async preference.

#### Location

**Kind:** Response header

**Applies to:** Create, update, transform, async

**Values:** URL of the record or job

**Default:** N/A

**Example:** Location: https://1234567.suitetalk.api.netsuite.com/services/rest/record/v1/customer/647

**Notes:** Create returns 204 with no body. Parse the new internal ID from the last path segment of Location.

#### limit

**Kind:** Query parameter

**Applies to:** Record collections, query/v1/suiteql

**Values:** Integer page size

**Default:** 1000

**Example:** ?limit=200

**Notes:** Default page size is 1000. SuiteQL over REST returns at most 100,000 results in total.

#### offset

**Kind:** Query parameter

**Applies to:** Record collections, query/v1/suiteql

**Values:** Integer start index

**Default:** 0

**Example:** ?limit=200&offset=400

**Notes:** Offset must be divisible by limit (offset=20, limit=10 is valid). Follow the next link in the response instead of computing it.

#### q

**Kind:** Query parameter

**Applies to:** Record collection GET

**Values:** field OPERATOR value, joined with AND / OR

**Default:** None

**Example:** ?q=email START_WITH barbara

**Notes:** Only fields marked x-ns-filterable in metadata. Quote values with spaces. AND binds before OR, parentheses allowed.

#### q operators (string)

**Kind:** Query parameter

**Applies to:** Record collection GET

**Values:** CONTAIN, CONTAIN_NOT, IS, IS_NOT, START_WITH, START_WITH_NOT, ENDWITH, END_WITH_NOT (as spelled in help)

**Default:** N/A

**Example:** ?q=companyname START_WITH "Another Company"

**Notes:** Oracle help spells the end-with operator inconsistently; test it on your account.

#### q operators (number)

**Kind:** Query parameter

**Applies to:** Record collection GET

**Values:** ANY_OF, BETWEEN, EQUAL, GREATER, GREATER_OR_EQUAL, LESS, LESS_OR_EQUAL, WITHIN, plus _NOT forms

**Default:** N/A

**Example:** ?q=id ANY_OF [1, 2, 3]

**Notes:** BETWEEN and WITHIN take two values, ANY_OF takes a list.

#### q operators (date and boolean)

**Kind:** Query parameter

**Applies to:** Record collection GET

**Values:** AFTER, BEFORE, ON, ON_OR_AFTER, ON_OR_BEFORE (+ _NOT); IS, IS_NOT; EMPTY, EMPTY_NOT

**Default:** N/A

**Example:** ?q=dateCreated ON_OR_AFTER "1/1/2026"

**Notes:** Date format follows N/query rules, not the ISO format used in record bodies.

#### fields

**Kind:** Query parameter

**Applies to:** Single record GET

**Values:** Comma list of body field IDs

**Default:** All fields

**Example:** ?fields=companyName,email,entityId

**Notes:** Body fields only. Selective retrieval of sublist and subrecord fields is not supported.

#### expandSubResources

**Kind:** Query parameter

**Applies to:** Single record GET

**Values:** true | false

**Default:** false

**Example:** ?expandSubResources=true

**Notes:** Returns sublists and subrecords inline instead of as links. Larger payloads, fewer round trips.

#### simpleEnumFormat

**Kind:** Query parameter

**Applies to:** Record GET

**Values:** true | false

**Default:** false

**Example:** ?simpleEnumFormat=true

**Notes:** Returns select and enum values in a simpler form. Check the REST API Browser for the exact shape on your record type.

#### replace

**Kind:** Query parameter

**Applies to:** PATCH and PUT

**Values:** Comma list of sublist or field names

**Default:** None (lines are merged)

**Example:** PATCH .../purchaseOrder/88?replace=item

**Notes:** 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

**Kind:** Query parameter

**Applies to:** PATCH

**Values:** true | false

**Default:** false

**Example:** PATCH .../myrecord?replaceSelectedFields=true&replace=body1

**Notes:** Only the fields named in replace and set to null in the body are cleared.

#### /services/rest/record/v1/{recordType}

**Kind:** Endpoint

**Applies to:** Record API

**Values:** GET list, POST create

**Default:** N/A

**Example:** POST /services/rest/record/v1/salesOrder

**Notes:** Record type names are camelCase as shown in the metadata catalog (salesOrder, inventoryItem).

#### /services/rest/record/v1/{recordType}/{id}

**Kind:** Endpoint

**Applies to:** Record API

**Values:** GET, PATCH, PUT (upsert by eid:), DELETE

**Default:** N/A

**Example:** GET /services/rest/record/v1/customer/107

**Notes:** Use eid:<externalId> in place of the ID to address by external ID.

#### /services/rest/record/v1/{recordType}/{id}/!transform/{targetType}

**Kind:** Endpoint

**Applies to:** Record API

**Values:** POST

**Default:** N/A

**Example:** POST /services/rest/record/v1/salesOrder/3/!transform/invoice

**Notes:** Body can set fields on the new record. Success returns 204 with Location.

#### /services/rest/record/v1/metadata-catalog

**Kind:** Endpoint

**Applies to:** Metadata

**Values:** GET, Accept: application/schema+json or application/swagger+json

**Default:** N/A

**Example:** GET /services/rest/record/v1/metadata-catalog?select=customer

**Notes:** Field names, types and filterable flags for your account, including custom fields.

#### /services/rest/query/v1/suiteql

**Kind:** Endpoint

**Applies to:** SuiteQL

**Values:** POST with {"q": "...", "params": [...]}

**Default:** N/A

**Example:** POST /services/rest/query/v1/suiteql?limit=1000

**Notes:** Requires Prefer: transient. Bound parameters use ? in q and a params array.

#### /services/rest/async/v1/job/{id}

**Kind:** Endpoint

**Applies to:** Async

**Values:** GET status; /task/{id}/result for output

**Default:** N/A

**Example:** GET /services/rest/async/v1/job/123456

**Notes:** Poll the URL from the Location header of the async response.

#### /services/rest/auth/oauth2/v1/token

**Kind:** Endpoint

**Applies to:** OAuth 2.0

**Values:** POST, form encoded

**Default:** N/A

**Example:** POST /services/rest/auth/oauth2/v1/token

**Notes:** Authorization code, refresh token and client credentials (certificate) grants.

#### Host

**Kind:** Endpoint

**Applies to:** All REST services

**Values:** <accountid>.suitetalk.api.netsuite.com

**Default:** N/A

**Example:** https://1234567-sb1.suitetalk.api.netsuite.com

**Notes:** Hostnames use lower case and a hyphen for sandboxes (1234567-sb1). The OAuth realm uses 1234567_SB1.

**Notes:** 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.

## Content

**Intro:** 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.

**Sections:**

#### How to use it

**Body:** 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.

**Bullets:**

- 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

**Body:** 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

**Body:** 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

**Body:** 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.

**Cta:** 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.

**Faq:**

#### What is the base URL for the NetSuite REST API?

**Answer:** 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?

**Answer:** 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?

**Answer:** 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?

**Answer:** 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.

## Search terms

netsuite rest api reference, netsuite rest web services api guide, netsuite rest api documentation, netsuite rest api endpoints, netsuite rest api query, netsuite prefer transient header, netsuite idempotency key, netsuite rest api q parameter

---
Talk to an engineer: https://netray.co/contact?intent=erp_ai | Machine catalog: https://netray.co/agent/catalog.json