HTTP Action Files

Learn how to handle file uploads in HTTP Actions using multipart/form-data encoding and the File tab mapping system.

Overview

When a File slot is resolved in a plugin, the file is not sent in the HTTP request body. Instead, it is passed as a dedicated file argument using the encoding method required by the target API. This is handled automatically by the HTTP Action editor via the File tab.

The File tab constructs a file dictionary where:

Keys = field name expected by the target API
Values = the File object

Only one file is ever included, even if multiple were selected in the UI.

Supported Encoding Types

Encoding Type	Description
`multipart/form-data`	Standard form-based file upload. Each field (including the file) is sent as a separate part. Most common for REST APIs.
`multipart/related`	Used when the file and metadata are semantically linked. Common in APIs like Google Drive.
`application/octet-stream`	Sends the raw binary file directly in the request body. Used when the API expects a single binary stream.
Raw upload	Sends the file content directly without multipart boundaries. Useful for APIs that accept raw file data in the body.
Base64 encoding	Sends the file as a base64-encoded string within a JSON body. See the Send base64 encoded string example below.

File Object Structure

1 {
2   "file_name": string, // Original filename (e.g., "report.pdf")
3   "location": string,  // Internal file ID
4 	"content": string	// base64 encoded
5 }

This object is referenced in the File tab as file.

Mapping in the File Tab

The data keyword is unnecessary when accessing your input argument in the File Mapping section

Use the File tab to map the incoming file to the API’s expected field name.

In the File tab, define:

1 <API field name>: file # or your input_arg name

Example: API expects field attachment

API Field Name	Mapped Value
`attachment`	`file` (this is your `input_arg` name, defaults to `file`)

Generated Request (cURL equivalent):

1 curl -X POST https://api.example.com/upload \
2   -F "attachment=@original_filename.pdf"

The HTTP Action editor constructs this automatically from the File tab mapping.

Example: API requires extra fields

Based on this cURL request to upload an attachment to a ServiceNow table

1 curl "https://instance.servicenow.com/api/now/attachment/upload" \
2 --request POST \
3  -F 'table_name=incident' \
4  -F 'table_sys_id=xyz'\
5  -F 'uploadFile=@ location of the file on file system'

You need to fill up 3 fields:

API Field Name	Mapped Value
`uploadFile`	`file` (this is your `input_arg` name, defaults to `file`)
`table_name`	`your_table_name`
`table_sys_id`	`your_table_sys_id`

You will need to map the file in the File tab:

1 uploadFile: file

And map the remaining fields in the Body tab:

1 {
2   "table_name": "{{your_table_name}}",
3 	"table_sys_id": "{{your_table_sys_id}}"
4 }

Example: Send base64 encoded string

To send the base64 encoded string of the file, you will need to follow the same steps by mapping the file in the File tab and pass the base64 content in the Body of the request with the following syntax files.file_input_arg_name.content

Based on an API that requires the following fields:

API Field Name	Mapped Value
`file_string`	`files.file.content` (this is your `input_arg` name, defaults to `file`)
`notes`	`notes`

You will map the file in the File tab:

1 	file: file

And map the remaining fields and content in the Body tab:

1 {
2   "file_string": {{{files.file.content}}},
3 	"table_sys_id": "{{notes}}"
4 }

Important: The key you access within files must match the key you mapped in the File tab. In the example above, we use files.file.content because we mapped the key as file in the File tab. If you had mapped it to attachment instead, you would need to access it as files.attachment.content. The pattern is always files.[your_mapped_key].[property] where [property] can be content, file_name, or location.

One caveat is that this will create a new input_arg in your input arguments panel. Make sure to delete that dummy argument there.

Filename Handling

Callout: The uploaded filename is fixed to file.file_name at upload time.
You cannot change it via the File tab.

Options to Control Filename

Option	How
User renames before upload	Instruct user: `"Rename file to Q3_Report.pdf before uploading"`
API accepts filename parameter	Send in JSON body:

Let API handle filename

Send filename separately in JSON body:

1 {
2   "filename": "{{file.file_name}}",
3   "category": "invoice"
4 }

cURL Equivalent (Generated Internally)

For an HTTP action with:

URL: POST https://upload.example.com/submit
Body: { "user": "john" }
File mapping: doc → file

1 curl -X POST https://upload.example.com/submit \
2   -H "Content-Type: multipart/form-data" \
3   -F "doc=@report.pdf" \
4   -F "{"user": "john"}"

Best Practices

Always use File tab — never embed in JSON.
Rename early if needed.
Use TEST button — check your service for the uploaded file.

1	{
2	"file_name": string, // Original filename (e.g., "report.pdf")
3	"location": string, // Internal file ID
4	"content": string // base64 encoded
5	}

1	curl -X POST https://api.example.com/upload \
2	-F "attachment=@original_filename.pdf"

1	curl "https://instance.servicenow.com/api/now/attachment/upload" \
2	--request POST \
3	-F 'table_name=incident' \
4	-F 'table_sys_id=xyz'\
5	-F 'uploadFile=@ location of the file on file system'

1	{
2	"table_name": "{{your_table_name}}",
3	"table_sys_id": "{{your_table_sys_id}}"
4	}

1	{
2	"file_string": {{{files.file.content}}},
3	"table_sys_id": "{{notes}}"
4	}

1	{
2	"filename": "{{file.file_name}}",
3	"category": "invoice"
4	}

1	curl -X POST https://upload.example.com/submit \
2	-H "Content-Type: multipart/form-data" \
3	-F "doc=@report.pdf" \
4	-F "{"user": "john"}"