NetSuite REST Record API: CRUD Operations with Real Examples

The NetSuite REST Record API is a built-in REST interface that lets you Create, Read, Update, and Delete standard NetSuite records — without writing any SuiteScript. It’s ideal for external systems that need to interact with NetSuite records directly.

What Is the REST Record API?

Unlike RESTlets (which require custom scripts), the REST Record API is a native NetSuite endpoint available for all standard record types including customers, sales orders, invoices, items, and more.

Base URL format:

https://[account-id].suitetalk.api.netsuite.com/services/rest/record/v1/[recordtype]

Authentication

The REST Record API supports both TBA (OAuth 1.0a) and OAuth 2.0. For examples in this tutorial, we’ll use TBA headers.

1. CREATE a Record (POST)

Create a new Customer record:

POST https://[account-id].suitetalk.api.netsuite.com/services/rest/record/v1/customer

Headers:
  Authorization: OAuth realm="[account-id]", ...TBA headers...
  Content-Type: application/json

Body:
{
  "companyName": "Acme Corporation",
  "email": "contact@acme.com",
  "phone": "555-1234",
  "subsidiary": { "id": "1" }
}

On success, NetSuite returns HTTP 204 with a Location header containing the new record’s ID:

Location: /services/rest/record/v1/customer/12345

2. READ a Record (GET)

Retrieve a Customer by internal ID:

GET https://[account-id].suitetalk.api.netsuite.com/services/rest/record/v1/customer/12345

Response example:

{
  "id": "12345",
  "companyName": "Acme Corporation",
  "email": "contact@acme.com",
  "phone": "555-1234",
  "links": [{ "rel": "self", "href": "/services/rest/record/v1/customer/12345" }]
}

GET with Field Selection

Use the fields parameter to limit which fields are returned:

GET /services/rest/record/v1/customer/12345?fields=companyName,email,phone

3. UPDATE a Record (PATCH)

Use PATCH to update specific fields without replacing the whole record:

PATCH https://[account-id].suitetalk.api.netsuite.com/services/rest/record/v1/customer/12345

Body:
{
  "phone": "555-9999",
  "email": "newcontact@acme.com"
}

Returns HTTP 204 on success.

Full Replace with PUT

Use PUT if you want to replace the entire record (omitted fields may be cleared):

PUT https://[account-id].suitetalk.api.netsuite.com/services/rest/record/v1/customer/12345

Body: { full record JSON }

4. DELETE a Record (DELETE)

DELETE https://[account-id].suitetalk.api.netsuite.com/services/rest/record/v1/customer/12345

Returns HTTP 204 on success. Note: some records may have dependencies that prevent deletion.

5. LIST Records (GET with Query)

Retrieve a paginated list of customers:

GET /services/rest/record/v1/customer?limit=10&offset=0

Response includes a links array for pagination and a count field.

Working with Sublists (Line Items)

To add line items to a Sales Order, use the sublist endpoint:

POST /services/rest/record/v1/salesOrder

Body:
{
  "entity": { "id": "12345" },
  "item": {
    "items": [
      {
        "item": { "id": "100" },
        "quantity": 5,
        "amount": 250.00
      }
    ]
  }
}

Error Handling

• 400 Bad Request — Invalid field names or values. Check field IDs in the NetSuite record schema.
• 401 Unauthorized — TBA or OAuth credentials invalid.
• 404 Not Found — Record ID doesn’t exist or you lack permission to view it.
• 409 Conflict — Record is locked by another user or process.

Supported Record Types

Common record types available via REST Record API include: customer, vendor, salesOrder, invoice, purchaseOrder, inventoryItem, employee, project, journalEntry, and many more. See the NetSuite REST API Browser for a full list.

Next Steps

To authenticate securely with the REST Record API, set up Token-Based Authentication (TBA) — covered in the next tutorial.