Attaching files to NetSuite records (the File Cabinet folder requirement)

When you attach a file to a NetSuite record through Apideck (POST /accounting/attachments/{reference_type}/{reference_id}), the connector first creates a File record in NetSuite's File Cabinet and then links it to the target record (invoice, bill, credit card charge, expense report, …).

The File Cabinet is a folder-based store, so every file must be created inside a folder. NetSuite has no concept of a "folderless" file. If no folder is supplied, NetSuite rejects the upload with:

USER_ERROR: Please enter value(s) for: Folder

Apideck does not silently pick a folder for you, because the only folders that exist in every account are NetSuite's standard system folders (SuiteScripts, Templates, Images, …) — none of which is an appropriate home for business attachments such as receipts. Instead you tell Apideck which folder to use, in one of two ways.

Option 1 — Per request (`parent_folder_id`)

Send the folder's internal ID in the attachment metadata on each request. With the SDK this is the parent_folder_id field; over raw HTTP it goes in the x-apideck-metadata header:


curl -X POST 'https://unify.apideck.com/accounting/attachments/expense/1509' \
  -H 'Authorization: Bearer <token>' \
  -H 'x-apideck-consumer-id: <consumer>' \
  -H 'x-apideck-app-id: <app>' \
  -H 'x-apideck-service-id: netsuite' \
  -H 'x-apideck-metadata: {"name":"receipt.pdf","parent_folder_id":12345}' \
  -H 'Content-Type: application/pdf' \
  --data-binary @receipt.pdf

Use this when different attachments should land in different folders, or when your integration already knows the right folder per upload.

Option 2 — A default folder on the connection (`attachments_folder_id`)

If your integration does not pass parent_folder_id per request, set a default once on the NetSuite connection. In the Apideck connection settings, fill in Attachments folder ID (attachments_folder_id) with the internal ID of the folder where attachments should be uploaded. Every attachment that omits parent_folder_id then uses this folder.

parent_folder_id (Option 1) always wins when both are present.

What happens if neither is set

The upload fails fast with a clear 400 from Apideck (not the opaque NetSuite USER_ERROR):

NetSuite requires a File Cabinet folder for attachments. Pass parent_folder_id in the attachment metadata, or set a default attachments_folder_id in the connection settings. Find the folder internal ID in NetSuite under Documents > Files > File Cabinet.

How to find a folder's internal ID

You need the internal ID of the folder, not its name.

From the NetSuite UI

Go to Documents > Files > File Cabinet.
Navigate to (or create) the folder you want, e.g. a dedicated "Apideck Attachments" folder.
Click the folder to open it. The internal ID is shown on the folder record, and also appears in the browser URL as folder=<id> (e.g. …/media/mediaitemfolders.nl?folder=12345).

Tip: if internal IDs are not visible in the UI, enable Home > Set Preferences > General > Defaults > Show Internal IDs.

With SuiteQL (to list candidates)

If you have REST/SuiteQL access, you can list folders and their IDs:


-- A specific folder by name
SELECT id, name FROM mediaitemfolder WHERE name = 'Apideck Attachments';

-- Browse top-level folders
SELECT id, name, parent FROM mediaitemfolder WHERE parent IS NULL ORDER BY name;

A note on standard folders (negative IDs)

NetSuite's built-in system folders use negative internal IDs and exist in every account, for example:

ID	Name
-4	Images
-9	Templates
-15	SuiteScripts
-19	SuiteApps

These are writable but are not intended for business attachments — uploading receipts into SuiteScripts works but is messy. Prefer creating a dedicated folder (e.g. "Apideck Attachments") and configuring its ID. The standard folders are listed here only so you can recognise them.

Required role permissions

Creating files requires the connection's NetSuite role to allow file creation in the File Cabinet:

Permission	Area	Level
Documents and Files	Lists	Create (or Full)

This is on top of the Setup permissions every Apideck NetSuite connection needs (Log in using Access Tokens, SOAP Web Services); see the connection guide.