N/sftp Module in NetSuite: Complete Guide to Secure File Transfers in SuiteScript

Integrating NetSuite with external systems often means exchanging files — invoices, inventory exports, EDI documents, and more. The N/sftp module lets your SuiteScripts connect directly to SFTP servers, upload and download files securely, and automate the entire file-transfer workflow without leaving the NetSuite platform.

This guide covers what the N/sftp module is, how to establish a connection, how to upload and download files, a practical real-world example, when to use it, and the best practices that keep your integrations reliable.

What Is the N/sftp Module?

The N/sftp module provides a client for the SSH File Transfer Protocol (SFTP). It lets you connect to a remote SFTP server using a host, port, username, and either a password or a private key, then perform operations such as uploading files, downloading files, listing directories, and deleting remote files. Because the connection is encrypted, it is well-suited for transferring sensitive business data between NetSuite and trading partners or cloud storage systems.

The module is available only in server-side scripts. It is commonly used inside Scheduled Scripts or Map/Reduce scripts where the script runs in the background and has time to complete long-running transfers.

Establishing a Connection

You create a connection with sftp.createConnection(). The required parameters are hostKey (the server’s known-host fingerprint), username, and one of passwordGuid or hostKey for key-based auth. The hostKey is critical for security: it verifies you are talking to the right server and prevents man-in-the-middle attacks. Once the connection object is returned, you use its methods for all file operations.

Code Examples

Example 1 connects to an SFTP server and uploads a file from the NetSuite File Cabinet.

/**
 * @NApiVersion 2.1
 * @NScriptType ScheduledScript
 */
define(['N/sftp', 'N/file'], (sftp, file) => {

  const execute = () => {
    // Load the file from the NetSuite File Cabinet
    const exportFile = file.load({ id: '/SuiteScripts/exports/orders.csv' });

    // Create the SFTP connection
    const connection = sftp.createConnection({
      username: 'ftpuser',
      passwordGuid: 'your-credential-guid-here', // stored in NetSuite credentials
      url: 'sftp.partner.com',
      port: 22,
      hostKey: 'AAAAB3NzaC1yc2EAAAADAQABAAABgQ...' // server fingerprint
    });

    // Upload the file to the remote /incoming directory
    connection.upload({
      directory: '/incoming',
      filename: 'orders.csv',
      file: exportFile
    });

    log.audit('Upload complete', 'orders.csv sent to sftp.partner.com/incoming');
  };

  return { execute };
});

Example 2 downloads a file from the remote SFTP server and saves it to the NetSuite File Cabinet for further processing.

define(['N/sftp', 'N/file'], (sftp, file) => {

  const execute = () => {
    const connection = sftp.createConnection({
      username: 'ftpuser',
      passwordGuid: 'your-credential-guid-here',
      url: 'sftp.partner.com',
      port: 22,
      hostKey: 'AAAAB3NzaC1yc2EAAAADAQABAAABgQ...'
    });

    // Download a file from the remote server
    const downloadedFile = connection.download({
      directory: '/outgoing',
      filename: 'invoice_feedback.csv'
    });

    // Save the downloaded content to the File Cabinet
    const savedFile = file.create({
      name: 'invoice_feedback.csv',
      fileType: file.Type.CSV,
      contents: downloadedFile.getContents(),
      folder: -15 // SuiteScripts root folder
    });
    savedFile.save();

    log.audit('Download complete', 'invoice_feedback.csv saved to File Cabinet');
  };

  return { execute };
});

Example 3 lists the contents of a remote directory and selectively downloads only files that match a naming pattern, which is useful for polling drop-folder integrations.

/**
 * @NApiVersion 2.1
 * @NScriptType ScheduledScript
 */
define(['N/sftp', 'N/file'], (sftp, file) => {

  const execute = () => {
    const connection = sftp.createConnection({
      username: 'ftpuser',
      passwordGuid: 'your-credential-guid-here',
      url: 'sftp.partner.com',
      port: 22,
      hostKey: 'AAAAB3NzaC1yc2EAAAADAQABAAABgQ...'
    });

    // List files in the remote /drop directory
    const listing = connection.list({ path: '/drop' });

    listing.files.forEach((remoteFile) => {
      // Process only CSV files
      if (remoteFile.name.endsWith('.csv')) {
        const downloaded = connection.download({
          directory: '/drop',
          filename: remoteFile.name
        });

        // Save each file to the File Cabinet
        const f = file.create({
          name: remoteFile.name,
          fileType: file.Type.CSV,
          contents: downloaded.getContents(),
          folder: -15
        });
        f.save();

        log.audit('Downloaded', remoteFile.name);
      }
    });
  };

  return { execute };
});

A Real-World Use Case

Imagine a wholesale distributor that sends daily purchase order files to a 3PL warehouse via SFTP, and receives shipping confirmation files back. A Scheduled Script runs every morning, generates a CSV of open orders from a saved search, uploads it to the warehouse SFTP drop folder, then checks the outgoing folder for any new confirmation files and imports them into NetSuite as item fulfillments. The entire integration is automated, auditable, and runs without manual intervention.

When to Use the N/sftp Module

Reach for N/sftp whenever you need to exchange files with an external system over a secure, encrypted channel. It is ideal for EDI file drops, sending export reports to partners, pulling inbound data feeds, and polling warehouse or carrier systems. It is not suitable for real-time API calls (use N/https for that) or for file operations within NetSuite itself (use N/file for those). Because SFTP connections consume governance and time, they belong in background scripts like Scheduled Scripts or Map/Reduce scripts.

Best Practices

Always store credentials using NetSuite’s secure credential management and reference them by GUID rather than hardcoding passwords. Verify the hostKey before go-live and never skip it. Wrap transfers in try-catch blocks and log all errors with log.error so you can diagnose failed transfers from the script execution log. When listing directories, guard against empty folders that could cause the script to silently exit. Consider processing one file per scheduled run and using a Workflow or custom status field to track which files have been imported, preventing duplicates.

The N/sftp module unlocks a clean, native path for file-based integrations directly inside SuiteScript. By combining it with N/search to generate exports and N/file to save downloads, you can build robust, fully automated B2B file exchange workflows without any middleware. Start with a simple upload, prove the connection works, then layer in directory polling and error handling as your integration matures.