1. SuiteCloud Platform
  2. SuiteTalk Web Services
  3. SuiteTalk REST Web Services API Guide
  4. REST Web Services Operations
  5. Working with File Cabinet Records in REST Web Services

Working with File Cabinet Records in REST Web Services

You can use the NetSuite file cabinet to store and organize your business documents in the same way as you store any files on your computer. You can store files that you receive or plan to send by email and you can attach files from the file cabinet to records in NetSuite, such as customer records, transactions, and issues. Most file cabinet folders can be restricted by the folder owner or an administrator.

Using REST web services, you can access and work with file cabinet records (files and folders).

The basic URL of the document service looks as follows:

REST requests sent to the document service are executed synchronously. There is a 10 MB upload and download limit for requests sent to the document service.

You can also use the REST search options to filter and page through the results.

For more information about filtering and pagination, see Record Collection Filtering and Collection Paging.

The following sections show how to work with files and folders.

Working with Metadata

You can access all metadata about the document service at the following URL: http://demo123.suitetalk.api.netsuite.com/services/rest/document/v1/metadata-catalog.

The following example shows the request structure. Direct access to the file and folder sub-catalogs is not supported.

            GET /services/rest/document/v1/metadata-catalog
HTTP 200
accept: application/swagger+json
Content-Type: application/swagger+json; charset=UTF-8
{
   ...
}

Working with Files

You can access files in REST web services through the file's internal or external ID. The following examples demonstrate this usage.

Getting a File Through Internal ID

In this example, the file resource is returned without data. The content field contains links to obtain the data as direct data stream or as a part of entire file object using the expand parameter. To access the file content directly, see the example in Accessing File Content.

              GET /services/rest/document/v1/file/{id}

HTTP 200
accept: application/json
Content-Type: application/json; charset=UTF-8
{
  "name" : "Test.txt",
  "isLink" : false,
   "folder" : {
      "links":[
        {
        "rel": "self", 
        "href": ".../services/rest/document/v1/folder/{folderId}",
        "mediaType": "application/application-json"
        }
      ],
      "id": "{parentId}"
  }     
  "content": {
    "links":[
      {
      "rel": "self", 
      "href": ".../services/rest/document/v1/file/{id}/content",
      "mediaType": "application/octet-stream"
      },
      {
      "rel": "alternate", 
      "href": ".../services/rest/document/v1/file/{id}?expand=content",
      "mediaType": "multipart/form-data"
      }
    ]
  }
}

Getting a File Through External ID

The following example shows how to retrieve a file through its external ID.

              GET /services/rest/document/v1/file/eid:{external ID}
HTTP 200
accept: application/json
Content-Type: application/json; charset=UTF-8
{
  ...
}

Accessing File Content

This method enables you to directly download the file through a web browser. If the file is missing or it does not have content, a 404 error response is returned. If the accessed file has content larger than 10 MB, a 413 error is returned.

              GET /services/rest/document/v1/file/{id}/content
HTTP 200
accept: application/octet-stream
Content-Type: text/csv
...

GET /services/rest/document/v1/file/1/content
HTTP 200
accept: application/octet-stream
Content-Type: application/octet-stream
...

Using Multipart Requests for Accessing File Content

You can access file content as a part of multipart/form-data request. File attributes (name, size, and other fields) are returned as JSON as a single part of response (attributes). File content can then be accessed as a different part of the response (content).

              ../services/rest/document/v1/file/​eid:crm-invoice-2026-001?expand=content​
​
Accept: multipart/form-data​

--FileBoundary​
Content-Disposition: form-data; name="attributes"​
Content-Type: application/json​

{​
"id": "9876",​
"externalId": "crm-invoice-2026-001",​
"name": "invoice-2026-001.pdf",​
"fileType": "PDF",​
"fileSize": 248392,​
"isLink": false,​
"folder": {​
"id": "458",​
"links": [​
{​
"rel": "self",​
"href": "../services/rest/document/v1/folder/458"​
}​
]​
},​
"links": [​
{​
"rel": "self",​
"href": "../services/rest/document/v1/file/9876"​
}​
]​
}​

--FileBoundary​
Content-Disposition: form-data; name="content"; filename="invoice-2026-001.pdf"​
Content-Type: application/pdf​

<binary PDF content>​

--FileBoundary--​

Searching for Files

You can search for files using a GET request. You can use the filter, offset, and q parameters for filtering and pagination. The following example shows this usage.

              GET /services/rest/document/v1/file/?q=createdDate AFTER "1/1/2012"
HTTP 200
accept: application/json
Content-Type: application/json; charset=UTF-8
{
    "links": [
        {
            "rel": "self",
            "href": "...services/rest/document/v1/file/"
        }
    ],
    "count": 1,
    "hasMore": false,
    "items": [
        {
            "links": [
                {
                    "rel": "self",
                    "href": "...services/rest/document/v1/file/1"
                }
            ],
            "id": "1"
        }
    ],
    "offset": 0,
    "totalResults": 1
}

Creating Files Through REST Web Services

You can create a file by sending a POST request that includes at least the file name, folder and either file data or URL. Only multipart requests are supported for sending data. Creating files by sending only data through direct access is not supported. The following example shows how to create a new file.

              POST /services/rest/document/v1/file/
Content-Type: multipart/form-data; boundary=boundary
--boundary
Content-Disposition: form-data; name="attributes"
Content-Type: application/json
{
"isLink": false,
"fileName" : "file.txt",
"folder" : {"id" : "1"},
...
--boundary
Content-Disposition: form-data; name="data"; filename="file.txt"
Content-Type: text/csv
[file content goes there]
--boundary--

Response:
HTTP 204
x-ns-link:  .../services/rest/document/v1/file/{id}

Using PATCH and PUT Operations with Files

You can use the PATCH operation to directly replace file data without changes to the file's attributes.

              PATCH /services/rest/document/v1/file/{id}/content
Content-Type: application/octet-stream
...

Response:
HTTP 204
x-ns-link:  .../services/rest/document/v1/file/{id}

The PUT operation is available for multipart and application/json requests. The file must be specified by external ID. If the file exists, it is replaced. If it does not, a new file is created and the external ID or folder is set accordingly.

All fields that are required in the POST operation are also required in PUT.

If the folder or external ID fields are specified in the body, they must have the same value as these specified in the URL or a user error is returned.

              PUT /services/rest/document/v1/file/eid:{external ID}
Content-Type: application/json
{
"isLink": true,
"URL" : "test.com",
...

Response:
HTTP 204
x-ns-link:  .../services/rest/document/v1/file/{id}

Deleting Files

The following example shows how to delete files. Deleting only file data is not supported.

              DELETE /services/rest/document/v1/file/eid:{external ID}
DELETE /services/rest/document/v1/file/{id}
 
Response:
HTTP 204

Working with Folders

You can access folders in REST web services through the folder's internal or external ID. The following examples demonstrate this usage.

Getting a Folder Through Internal or External ID

The following example shows how to retrieve a folder through its internal or external ID. If the folder is missing, a 404 error is returned. If an incorrect accept header is uses, a 406 error is returned.

              GET /services/rest/document/v1/folder/{id}
GET /services/rest/document/v1/folder/eid:{external ID}
HTTP 200
accept: application/json
Content-Type: application/json; charset=UTF-8
{
  "name" : "folder",
  "id" : "123",
  "parent" : {
      "links":[
       {
        "rel": "self", 
        "href": ".../services/rest/document/v1/folder/{parentId}",
        "mediaType": "application/application-json"
        }
     ],
     "id": "{parentId}"
  }
}

Creating Folders Through REST Web Services

You can create a folder by sending a POST request that includes at least the folder name and parent. Only application/json requests are supported.

              POST /services/rest/document/v1/folder/
Content-Type: application/json
{
"name": "folder",
"parent" : {"id" : "1"},
...

Response:
HTTP 204
x-ns-link:  .../services/rest/document/v1/folder/{id}

Searching Folders

The following example shows a search request.

              GET /services/rest/document/v1/folder/?q=createdDate AFTER "1/1/2012"
HTTP 200
accept: application/json
Content-Type: application/json; charset=UTF-8
{
    "links": [
        {
            "rel": "self",
            "href": "...services/rest/document/v1/folder/"
        }
    ],
    "count": 1,
    "hasMore": false,
    "items": [
        {
            "links": [
                {
                    "rel": "self",
                    "href": "...services/rest/document/v1/folder/1"
                }
            ],
            "id": "1"
        }
    ],
    "offset": 0,
    "totalResults": 1
}

Updating Folders Using the PATCH Operation

The following example shows how to update a folder.

              PATCH /services/rest/document/v1/folder/eid:{externalId}
PATCH /services/rest/document/v1/folder/{id}
Content-Type: application/json
{
"name": "folder renamed",
"parent" : {"id" : "2"},
...
}

Response:
HTTP 204
x-ns-link:  .../services/rest/document/v1/folder/{id}

Deleting Folders

You can use the delete operation to delete folders. If the folder has subfolders or subfiles, an error is thrown and the folder is not deleted.

              DELETE /services/rest/document/v1/folder/eid:{external ID}
DELETE /services/rest/document/v1/folder/{id}

Response:
HTTP 204

Related Topics

General Notices