Multipart Requests

Learn how to build multipart requests

A MultiPartBuilder is used to construct multipart (RFC 2388) payloads for requests. It enables adding raw data-sources or dynamic text content parts to build a multipart payload. Once all the parts have been added, pass the MultiPartBuilder into multi_part_payload field on the request.

var payload = new MultiPartBuilder();
payload.addField("firstname", "Smith");"/file-upload", { multi_part_payload: payload });

This example sends a POST request to /file-upload with Content-Type: multipart/form-data and a random boundary parameter. In the payload, there will be one part with a Content-Disposition header.


addField(fieldname, content) adds a new part to the MultiPartBuilder. Both fieldname and content can contain variables obtained via session.getVar(). The part will have a Content-Disposition header specifiying the fieldname.


addFields(options) is a helper function when to make adding multiple fields via addField() easier.

let payload = new MultiPartBuilder();
  'firstname': 'Mr',
  'lastname': 'Smith',
  'location': 'Cologne',


addFile(options) allows adding raw file fixtures to the multipart payload.

The options hash supports the following keys:

Parameter Required Description
name yes The form name field to be used for this part. Supports variables.
filename yes The filename that should be provided to the server for this part. Supports variables.
content_from_file yes The reference to the raw data source obtained via session.ds.getRawFile(). See data-sources.
content_type no The content-type for this file. Defaults to application/octet-stream. Supports variables.

Parts added via addPart() will have a Content-Disposition, Content-Type and Content-Transfer-Encoding header.

var payload = new MultiPartBuilder();
  'name': 'fileupload',
  'filename': 'userprofile.jpg',
  'content_from_file': session.ds.getRawFile("user-profile.jpg"),


The following example shows how you can use MultiPartBuilder inside your session to perform a POST request with a multipart payload.

var payload = new MultiPartBuilder();

// addField(fieldname, content) adds a single field to the multipart builder
payload.addField("firstname", "Smith");

// addFields(array) allows to adding multiple fields
  "lastname": "Jane",
  "location": "Doe",

// addFile(options) adds a binary file.
// name specifies the form field name.
// filename is the filename for the Content-Disposition header.
// content_type allows for specifying the content-type header
// content_from_file specifies the raw datasource to use. See
  name: "upload_file",
  filename: "certificate.pem",
  content_from_file: session.ds.getRawFile("data/multipart-example.txt"),
  // content_type: "application/octet-stream" // octet is the default

// Finally pass in the MultiPartBuilder into the request with the multi_part_payload key."/data/test.json", {
  tag: "root",
  multi_part_payload: payload,
Last modified May 20, 2022